Receive email API for code, tests, and automation

A receive email API lets an application create an address, wait for mail, and read the resulting message without a person opening a mailbox. MailSlurp combines real inboxes with wait methods, search, message retrieval, attachments, webhooks, SMTP, and IMAP access.

That makes the same receiving layer useful for a five-minute password-reset test and for a service that processes inbound customer mail all day.

Quick answer

A practical receive email API should let you:

create a real email address in code
wait for a new or matching message with a timeout
fetch a complete email by ID
extract links, OTP codes, headers, and attachment IDs
download attachments only when they are needed
push new-message events to a webhook

For a working SDK walkthrough, start with receive email with the MailSlurp API.

Which receive pattern fits your application?

The important choice is not REST versus SDK. It is whether one caller is waiting for one expected message, or a running service must react to every message.

What your code needs to do	MailSlurp starting point
Wait until one expected email arrives	Wait for latest or first matching email
Read messages that already arrived	List the inbox, then fetch the complete email by ID
Process every inbound message	Subscribe an inbox to a `NEW_EMAIL` webhook
Read mail through an existing client or library	Use SMTP and IMAP access
Route replies and attachments into internal systems	Use the inbound email API with webhooks and rules

Wait methods are especially useful in CI because the API holds the request until the condition is met or the timeout expires. Webhooks are the better fit for an always-on application because MailSlurp tells your endpoint when new work arrives.

Receive an email in a test

A reliable test isolates the inbox and waits for a specific result:

Create a fresh MailSlurp inbox for the test run.
Give its address to the real signup, reset, or notification flow.
Trigger the action that sends the email.
Wait for a message that matches the expected sender or subject.
Inspect the body, links, headers, and attachments.
Follow the link or submit the code to finish the customer journey.

Wait for a matching email in code:

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,
);

Creating an inbox per test is more than cleanup. It prevents an old message or a parallel worker from satisfying the wrong wait condition.

What a complete email gives you

Inbox list results are intentionally compact. Fetch the email by ID when your code needs the complete body or attachment references.

With the full message your application can inspect:

sender, recipients, subject, and reply-to details
parsed HTML or plain-text content
raw headers for delivery investigation
links and verification codes
attachment IDs and metadata

This separation keeps list and webhook responses quick while letting workers retrieve large content only when a workflow needs it.

Where teams use a receive email API

QA for account flows

finish signup through the confirmation link
submit a password-reset token
verify a device or MFA fallback message

Release and monitoring checks

confirm invoices, receipts, and alerts still arrive
validate the recipient and subject after template changes
keep the email ID and headers with a failed monitor result

Inbound application workflows

receive a customer reply and connect it to a ticket
download an invoice or claims attachment in a worker
route a message into extraction, review, or an internal API

For continuous intake, use email webhooks so the application does not have to poll. Store the webhook message ID before processing and fetch the full email by email ID when a worker is ready.

What to compare in a receive email API

Look beyond whether a provider can return a message. The useful questions appear when several messages, test workers, or attachment types arrive at once.

Can code create a new address without manual setup?
Can a wait match sender, recipient, subject, and time conditions?
Can each parallel test use its own inbox?
Can the API return both parsed content and raw headers?
Are attachments addressable separately from the message?
Can webhooks and API retrieval use the same inbox and email IDs?
Can a failed worker retrieve the original message again?

Receive API best practices

Isolate inboxes per test or worker to avoid cross-run interference.
Use explicit timeouts and match criteria instead of arbitrary sleeps.
Validate the sender and subject before parsing body content.
Treat a webhook as a notification, then fetch the stored email in a worker.
Keep the MailSlurp inbox and email IDs alongside your own test, ticket, or order ID.
Download attachments only after checking their metadata and expected type.

When delivery itself is under investigation, combine the received message with:

Receive email API or inbound email API?

A receive email API answers: "Has the message arrived, and what does it contain?"

An inbound email API answers: "What should happen in my application when this message arrives?"

MailSlurp supports both jobs on the same inbox model. Tests can wait and assert, while production services can subscribe to webhooks, apply routing rules, and retrieve the full message asynchronously.

FAQ

Can I use this for OTP and magic-link tests?

Yes. This is one of the most common receive-email API use cases in CI and staging.

Can I receive attachments?

Yes. Fetch the complete email to obtain its attachment IDs, then download the required attachment through the attachment API.

Should I poll an inbox in production?

Use a webhook when every new message should start work immediately. Keep API retrieval available so a worker can fetch the complete email or retry processing later.

Does it work with custom domains?

Yes. You can receive on generated addresses and custom-domain addresses depending on your setup.

Can I reply to a received email?

Yes. MailSlurp can reply to a received email through the email API. For conversations routed through forwarded aliases, threaded aliases preserve a path back to the original sender. See inbound email routing.

Start receiving email

Follow the receive email API and SDK guide to create an inbox and wait for the first message, or open Email integration testing to add receive assertions to a real customer journey.

Receive email API for waiting, reading, and testing messages