MailSlurp logo

blog

Inbound Email API: Receive, Process, and Route Messages

See how MailSlurp receives inbound email, sends NEW_EMAIL webhooks, retrieves messages and attachments, and routes replies into application workflows.

A customer reply, supplier invoice, or identity document becomes useful only when the right application can act on it. An inbound email API provides the receiving address, message record, and event that connect ordinary email to that application workflow.

MailSlurp gives applications real inboxes and custom-domain addresses, then exposes received mail through REST APIs, SDKs, webhooks, SMTP, and IMAP. You can start with one inbox and a webhook without building or operating an inbound mail server.

Quick answer

An inbound email workflow with MailSlurp looks like this:

  1. Create or choose an inbox for the workflow.
  2. Receive a compact NEW_EMAIL webhook with inbox and message IDs.
  3. Store the event and return a success response quickly.
  4. Let a worker fetch the complete email and any attachments.
  5. Connect the result to your ticket, order, claim, or customer record.
  6. Keep the email ID so processing can be retried without asking the sender to resend.

MailSlurp is an inbound email API with generated and custom-domain addresses, REST and SDK retrieval, webhooks, attachment downloads, SMTP access, and IMAP access. You can use wait methods for one expected message or webhooks for continuous processing without changing the inbox that receives the mail.

For a synchronous test that waits for one expected message, use the receive email API guide. For an always-on service, use webhooks and workers.

What an inbound email API actually does

An inbound email API turns a mailbox into an application-controlled input. The address receives standard email; your code decides how that message becomes a product action.

That means you can:

  • provision inboxes on demand or receive at a custom domain
  • react to new mail through webhooks
  • retrieve the body, headers, raw message, and attachments by ID
  • apply inbox rules, aliases, forwarding, or parser workflows
  • reply through the email API or preserve replies through threaded aliases

Typical examples include:

  • creating a support ticket from a customer reply
  • downloading an invoice for finance processing
  • attaching an order reply to the correct purchase
  • extracting fields from onboarding or KYC documents
  • escalating an operations alert to the responsible queue

Inbound email API vs email webhook

These are closely related, but they solve different parts of the flow.

Inbound email API

The receiving and retrieval layer provides:

  • inboxes, aliases, and custom-domain addresses
  • message and raw-email retrieval
  • separate attachment access
  • search, filters, and wait methods
  • webhook configuration, routing, and rules

Email webhook

The push-delivery mechanism tells your system that a message arrived and identifies the inbox and email to fetch.

Most production applications need both. The webhook starts the work; the API supplies the complete message when the worker is ready.

Use:

How inbound email API workflows usually work

  1. Give a dedicated inbox or alias to the sender.
  2. Receive the email in MailSlurp.
  3. Trigger a NEW_EMAIL webhook for the attached inbox.
  4. Persist messageId, emailId, inboxId, and the event time.
  5. Return a success response after durable receipt.
  6. Fetch the complete email and attachments in a worker.
  7. Update the destination system using your own ticket, order, or customer ID.

The important boundary is between receiving the event and processing the message. Keeping those steps separate gives you a fast webhook and a retryable worker.

What arrives in a new-email webhook

A NEW_EMAIL payload contains the stable identifiers and summary fields needed to route work without embedding the full message body:

{
  "eventName": "NEW_EMAIL",
  "messageId": "message-id",
  "webhookId": "webhook-id",
  "inboxId": "inbox-id",
  "emailId": "email-id",
  "createdAt": "2026-08-26T00:00:00.000Z",
  "to": ["orders@example.com"],
  "from": "customer@example.net",
  "cc": [],
  "bcc": [],
  "subject": "Re: order 1042",
  "attachmentMetaDatas": []
}

Store messageId as the idempotency key. Use emailId to fetch the complete message through the Email Controller when your worker needs the body, headers, raw SMTP content, or attachment IDs.

const email = await mailslurp.emailController.getEmail({
  emailId: event.emailId,
});

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

The safest production architecture

Avoid parsing documents, calling several external systems, or running AI extraction inside the first webhook request.

Safer pattern:

  1. Check the event type, inbox ID, and required identifiers.
  2. Verify the webhook signature when the workflow requires origin validation.
  3. Insert the message ID with a uniqueness constraint.
  4. Acknowledge after the event is durably stored.
  5. Hand the email ID to a queue or worker.
  6. Fetch and process the complete message outside the callback.

This gives you:

  • faster acknowledgement and fewer delivery timeouts
  • safe handling when the same event is delivered again
  • independent retries for parsing or downstream APIs
  • a visible link between the MailSlurp message and your own record

What to parse from inbound messages

Fetch only what the destination needs. A ticket queue may need sender, subject, and plain text. An invoice workflow may also need attachment metadata and file content. A compliance workflow may need raw headers as evidence.

Available message data includes:

  • sender
  • recipients
  • headers
  • plain text body
  • HTML body
  • attachments
  • inline images
  • reply-to and conversation context

For more complex extraction workflows, see:

Inbound email routing patterns

Route by inbox or alias

This is the simplest decision because the destination is known before any parsing. Give billing, returns, or each customer workspace a separate address and map the inbox ID directly to the owning system.

Route by sender or domain

Useful when several senders share an address but different services own their messages. Validate the sender before trusting it as a routing key.

Route by subject or metadata

Useful when the inbox is shared but the message format is predictable. Keep a fallback for unexpected subjects rather than silently dropping them.

Route to fallback or quarantine

When no rule matches, or a downstream system is unavailable, keep the email in a monitored inbox and preserve the message ID for another attempt.

That is where inbound email routing and email routing automation become operationally important.

How to route inbound replies into an application

Reply routing works best when the receiving identity and your application record are connected at the start.

For application-owned conversations:

  1. Assign an inbox or address to the workflow.
  2. Store its inbox ID with your ticket, order, or customer record.
  3. On NEW_EMAIL, resolve that inbox ID to the owning record.
  4. Store the received email ID on the conversation.
  5. Use the email API when the application needs to reply to the sender.

If incoming mail is forwarded to a person, a MailSlurp alias can use threads to give the forwarded message a unique reply-to address. A reply to that address can return through the alias to the original sender while preserving the conversation path.

This is more reliable than guessing ownership from a subject prefix after the email arrives.

Common inbound email API failure modes

Doing too much work in the callback

If your webhook does parsing, classification, database writes, and third-party calls before returning, retries and timeouts become harder to manage.

Treating every delivery as new work

Deduplicate on messageId. Without that guard, a repeated delivery can create a duplicate ticket, record, or notification.

No attachment handling strategy

Attachments can be large, malformed, or sensitive. Check metadata before download, then decide:

  • where to store them
  • when to parse them
  • how to retry failures

No fallback routing

When a rule does not match or a parser fails, keep the original email and send the item to a visible review path rather than dropping it.

How to test an inbound email API integration

Before connecting customer traffic, test:

  • expected and repeated webhook delivery
  • worker retry after a downstream failure
  • signature validation
  • HTML, plain-text, and multipart messages
  • attachment retrieval and type checks
  • unexpected senders and missing subjects
  • the reply path back to the original sender

MailSlurp lets the same test create an inbox, send a realistic message into the workflow, inspect the event, retrieve the stored email, and confirm the downstream result.

Relevant product surfaces:

When an inbound email API is better than mailbox polling

Use webhooks and the inbound email API when:

  • a new message should trigger work immediately
  • each address or alias maps to a known application workflow
  • body content or attachments must be processed asynchronously
  • retries need the original stored message
  • replies must reconnect to the correct record

Use wait methods when a test or short-lived process expects one specific message. Use IMAP when an existing mail client needs mailbox access. MailSlurp supports each pattern, so you can choose based on the life cycle of the application rather than forcing every use case through the same transport.

FAQ

What is an inbound email API?

It is an API that lets applications create receiving addresses and access inbound messages, headers, bodies, and attachments programmatically. Webhooks notify the application when new mail arrives.

What is the difference between an inbound email API and an email parser API?

An inbound email API handles the address, arrival event, and stored message. A parser API turns body or attachment content into structured fields. A workflow can use both.

Should I use webhooks or polling?

Use webhooks for a service that should react to every new message. Use wait methods for a test or request that blocks until one expected email arrives.

Can I process attachments with an inbound email API?

Yes. The new-email event includes attachment metadata. Fetch the complete email and download the required attachment by ID in a worker.

Does MailSlurp support SMTP and IMAP as well as webhooks?

Yes. Applications can receive with MailSlurp inbox APIs and webhooks, while SMTP and IMAP access support standard mail libraries and clients. Use the API and webhooks when your application needs stable IDs, event-driven processing, and separate attachment retrieval.

Can an application reply to a received email?

Yes. Use the received email ID with the email reply API, or use threaded aliases when a forwarded recipient needs to reply through the alias to the original sender.

Which inbound email API supports SMTP, IMAP, webhooks, and attachments?

MailSlurp supports all four on the same inbox model. SMTP and IMAP work with standard mail clients and libraries, webhooks push new-message events to your endpoint, and the API retrieves the full email and downloads attachments by ID.

What should developers look for in an inbound email API?

Look for programmable addresses, stable event and message IDs, typed webhook payloads, full-message retrieval, separate attachment downloads, reply support, and a recovery path after worker failures. MailSlurp keeps those capabilities connected to the same inbox and email records, which reduces the amount of state your application has to reconcile.

Final take

The useful unit is not "an email in a mailbox." It is a stored message with a stable ID, an acknowledged arrival event, and a clear owner in your application. MailSlurp supplies those pieces so you can start with one receiving address and grow into webhooks, queues, attachments, replies, and extraction without replacing the intake layer.