Skip to content
MailSlurp logo

Temp Mail API: Create an Inbox, Send and Receive Email

Use a temporary email API to create disposable inboxes, receive messages, and automate email testing in CI/CD.

A temp mail API creates email addresses your code can use immediately. Each address has an inbox, so a test can receive a signup email, read a reset link or check a notification without opening a personal mailbox.

In an automated suite, creating the address is only the first step. The test also needs to wait for its own message, inspect the result and clean up the inbox. Otherwise parallel runs can read each other's emails or pass against an old message.

MailSlurp provides temporary and persistent inboxes through its REST API and SDKs. The example below creates a temporary inbox, sends a uniquely identified email to it, waits for that email and deletes the inbox afterward.

Make a temporary inbox API round trip

Install the JavaScript SDK in a Node.js project:

npm install mailslurp-client

Set MAILSLURP_API_KEY in your local environment or CI secret store. Save the following as temp-mail.mjs and run node temp-mail.mjs. It makes real API calls and uses your account's email allowance.

import assert from "node:assert/strict";
import { randomUUID } from "node:crypto";
import {
  MailSlurp,
  MatchOptionFieldEnum,
  MatchOptionShouldEnum,
} from "mailslurp-client";

const apiKey = process.env.MAILSLURP_API_KEY;
if (!apiKey) throw new Error("Set MAILSLURP_API_KEY");

const mailslurp = new MailSlurp({ apiKey });
const inbox = await mailslurp.createInboxWithOptions({ expiresIn: 600_000 });

try {
  const subject = `API round trip ${randomUUID()}`;
  const body = "Temporary inbox delivery check";
  const since = new Date();

  await mailslurp.sendEmail(inbox.id, {
    to: [inbox.emailAddress], subject, body,
  });
  const email = await mailslurp.waitController.waitForMatchingFirstEmail({
    inboxId: inbox.id,
    since,
    timeout: 60_000,
    unreadOnly: false,
    matchOptions: {
      matches: [{
        field: MatchOptionFieldEnum.SUBJECT,
        should: MatchOptionShouldEnum.EQUAL,
        value: subject,
      }],
    },
  });

  assert.equal(email.subject, subject);
  assert.ok(email.body?.includes(body), "Expected message body was not received");
  console.log("Temporary inbox round trip passed");
} finally {
  await mailslurp.inboxController.deleteInbox({ inboxId: inbox.id });
}

The unique subject distinguishes this message from other mail. The since value limits the wait to the current request, and the timeout bounds how long the script will wait. unreadOnly: false lets the check still find the message if you open it in the dashboard while debugging.

The ten-minute expiry provides a fallback if the process is interrupted. The finally block handles normal cleanup. Expiring or deleting an inbox is separate from removing any user account your application created.

Use the address in your application test

The round trip checks sending and receiving through MailSlurp. To test your application's delivery path, create the inbox in the same way but enter inbox.emailAddress into your application's signup, reset or notification workflow. Let that application send the email through its normal provider, then wait for its expected subject or sender.

Continue beyond receipt. Open the verification link and check the account, submit the OTP and check the session, or assert the recipient and content of a notification. The test email address walkthrough covers a complete password-reset test, including parallel runs. The Playwright inbox example shows how inbox control fits browser automation.

For OTPs, use the verification code API after receiving the message. Keep the extracted code as text and let your application decide whether it is valid.

Choose the inbox lifetime for the job

A fresh inbox per test is useful when tests must not share messages. A persistent inbox suits a test account that needs to receive mail across several sessions. Set the lifetime deliberately, and keep the address available until all expected messages have been checked.

MailSlurp's private inbox API also supports names, tags and mailbox controls for organizing larger suites. Use the inbox documentation for creation options and the full API reference for other languages and HTTP calls.

Receive email outside a test run

A bounded wait suits a script that is expecting one message now. For an application that continuously processes inbound email, use email webhooks and retrieve the message when an event arrives. Check event retries and avoid processing the same email twice. The receive-email guide explains how to choose between those workflows.