Receive email with the MailSlurp API and SDK

Receiving email in code should feel like waiting for a normal application event: create an address, trigger the message, wait for the right email, and inspect the result.

This focused guide shows the shortest MailSlurp SDK path. Use it for signup tests, OTP and password-reset checks, monitoring, or a small integration that needs to read a received message. For every retrieval and content option, see the complete receiving email guide.

Quick answer

With MailSlurp you can receive an email in four steps:

1. Create an inbox and keep its id and emailAddress.
2. Send or trigger an email to that address.
3. Wait for the expected message with a timeout.
4. Read the body, headers, links, and attachments from the returned email.

Use a wait method when one application action should produce one known message. Use email webhooks when your service processes inbound mail continuously.

Install and configure the JavaScript SDK

Install the MailSlurp client:

npm install --save mailslurp-client

Create the client with an API key from the MailSlurp dashboard:

import { MailSlurp } from "mailslurp-client";

const mailslurp = new MailSlurp({ apiKey: your_key_here });

Keep the key in your environment or secret manager. Do not put it in browser code or commit it to a repository.

Create a receiving address

An inbox has two values you will use throughout the workflow:

• emailAddress is the destination you give to the system sending the message.
• id identifies the inbox in MailSlurp API and SDK calls.

Create a new inbox:

const MailSlurp = require("mailslurp-client").default;
const mailslurp = new MailSlurp({
  apiKey: process.env.API_KEY ?? "your-api-key",
});

// create an inbox with options using the inbox controller
const inbox = await mailslurp.inboxController.createInbox({
  // name is used a contact name when sending
  name: "John Doe",
  // use the expanded domain pool so randomly assigned email address is more varied
  useDomainPool: true,
  // permanent by default or supply an expires at time
  expiresAt: undefined,
});

For automated tests, create a fresh inbox for each test or worker. This prevents a message from one run satisfying the wait condition in another.

Wait for the received email

After triggering your application, wait for the message instead of listing the inbox immediately. Email delivery is asynchronous, so an immediate list request can succeed before the expected message arrives.

const latestEmail = await mailslurp.waitForLatestEmail(inbox.id, 30000, unreadOnly);

A useful wait call includes:

• the inbox ID
• a bounded timeout
• unreadOnly when an older email must not match

Use at least 60 seconds when the sender or delivery path can be slow. Your test runner and HTTP client must also allow the request to remain open for that long.

Match the message you actually expect

waitForLatestEmail is a good first example, but subject or sender matching is safer when an inbox can receive several message types.

const matchingEmails = await mailslurp.waitForMatchingEmails(
  {
    // match for emails with no attachments
    conditions: [
      {
        condition: ConditionOptionConditionEnum.HAS_ATTACHMENTS,
        value: ConditionOptionValueEnum.FALSE,
      },
    ],
    // match for emails from a specific email address
    matches: [
      {
        field: MatchOptionFieldEnum.FROM,
        should: MatchOptionShouldEnum.CONTAIN,
        value: inbox.emailAddress,
      },
    ],
  },
  1,
  inbox.id,
  timeout,
  unreadOnly,
);

For an OTP test, match the expected sender and subject before extracting a code. For a password-reset test, match the message generated after the current test started. These small constraints make failures easier to understand and reduce false positives.

Read the complete message

List endpoints return compact email previews. When you have an email ID and need the body, headers, or attachment IDs, fetch the complete email:

const completeEmail = await mailslurp.emailController.getEmail({
  emailId,
});

console.log(completeEmail.subject, completeEmail.body, completeEmail.attachments);

The full email gives you the content needed to:

• assert the subject and sender
• inspect the plain-text or HTML body
• extract a verification link or one-time code
• review SMTP and authentication headers
• find attachment IDs for download

If you need CSS selectors, regular expressions, or link extraction, continue with extracting email content.

Download attachments

Attachments are separate resources associated with the email. Fetch the complete email first, then download the attachment you need by ID. This keeps the initial inbox and webhook payloads small even when a message carries a large file.

Use the email attachment API guide for download examples, metadata, base64 responses, and file checks.

Choose wait methods, listing, or webhooks

Your job	Best starting point
Block a test until one known message arrives	Wait for the latest or first matching email
Find mail that is already in an inbox	List inbox emails, then fetch by email ID
Process every inbound message in a running service	Subscribe to NEW_EMAIL webhooks
Receive through an existing mail client	Use MailSlurp SMTP and IMAP access

Wait methods and webhooks solve different timing problems. A wait call lets one test or request pause until its expected message exists. A webhook tells a long-running application that new work is ready. Many teams use both: waits for CI and webhooks for production intake.

A reliable receive-email test

A useful test proves the customer journey, not merely that an inbox contains mail:

1. Create a new inbox for the test.
2. Give its address to the real signup, login, or reset flow.
3. Record the time just before triggering the email.
4. Wait for a message with the expected sender or subject.
5. Assert the recipient and message content.
6. Extract the link or code and complete the action.
7. Keep the email ID with failure output for investigation.

That final action matters. A delivered password-reset email with a broken link is still a failed customer journey.

Troubleshooting

The wait returned an old email

Use a new inbox per test, restrict the wait to unread messages, or match on sender, subject, and a recent time window.

The request timed out

Confirm the sender used the inbox emailAddress, increase both the MailSlurp timeout and the calling client's timeout, and check inbox receiving diagnostics.

The body is missing from a list result

Inbox lists contain previews. Fetch the complete message with its email ID before reading the body or attachment IDs.

Several test workers read the same message

Give each worker its own inbox. Shared inboxes make parallel tests contend for the same unread messages and are much harder to debug.

Next step

Start with the receive email API overview if you are comparing capabilities, or open the complete receiving email guide for search, HTML queries, attachments, webhooks, and forwarding.