Inbound Email Processing Overview

In This Article:

Use our inbound processing to receive email for your application or let users interact with your app via email. Mandrill receives, processes, and parses email for your application, then sends it to you via HTTP POST webhooks.

Inbound processing isn’t designed to replace a traditional email inbox, but it lets you accept and process emails programmatically. Before you can receive email with Mandrill, you’ll need to set up an inbound domain and one or more routes.

Set Up an Inbound Domain

You can add inbound domains using the Mandrill API or web application. Let’s start by looking at how to add an inbound domain via the Mandrill API.


Using the inbound/add-domain endpoint, specify and API key and the subdomain you’d like to add:

    "key": "example key",
    "domain": ""

Now that you’ve added the inbound domain, you’ll need to edit the MX records so they point at Mandrill’s servers. To get the appropriate MX records:

  1. Go to Inbound in your Mandrill account.
  2. Locate the domain you added via the API and click the DNS Settings button. A new window will appear with the MX settings for your Mandrill account. You’ll need to add these records or edit your existing MX records to point to the servers shown in that window only.
    MX records set up window in web app

Web app

To set up an inbound domain:

  1. Go to Inbound in your Mandrill account.
  2. Add the domain or subdomain name where you’ll receive mail and click the + Add New Inbound Domain button.
  3. Click the DNS Settings button for any domain you’ve added to get the DNS records you’ll need to add for your domain.
  4. Test the records for your domain using the Test button. We’ll check the MX records for the domain to be sure they’re configured properly.


  • Mandrill handles all mail for the inbound domain or subdomain, so we recommend using a subdomain that doesn’t exist yet or a dedicated domain that you use for inbound mail processing only.

  • Refer to your DNS provider’s help documentation for instructions on adding MX records for your domain or subdomain.

  • Propagation time will depend on your DNS provider—it may take hours or days for changes to your MX records to take effect. If there’s an issue with the records, we’ll show an error message with more details.

Add a Route

You can add routes using the Mandrill API or web application. Let’s start by looking at how to add a route via the Mandrill API. A route defines the local part (everything before the @ symbol) of the email address(es) where you’ll receive mail.

Be specific (providing the full local part exactly), or define patterns using wildcard matching. We’ll send any emails that match a specified route to the corresponding webhook. Routes support two types of wildcards: * for multi-character and ? for single-character.


Using the inbound/add-route endpoint, specify an API key, domain, pattern, and URL you’d like to add:

    "key": "example key",
    "domain": "",
    "pattern": "mailbox-*",
    "url": ""

Web app

To add a new route:

  1. Go to Inbound in your Mandrill account.
  2. Click the Routes button next to the inbound domain you want to edit.
  3. Click the + Add New Route button.
  4. Enter the full local part or pattern in the first box that appears.
  5. Enter the webhook URL where Mandrill should POST inbound emails.
  6. Click the Save button.

Example routes

If you want all messages at a domain to go to the same URL, use the global catchall * as your route match:

Inbound route catchall example


  • When you save a route, we’ll check the URL to be sure it exists using a HEAD request (not POST).

  • If the URL doesn’t exist or returns something other than a 200 HTTP response to the HEAD request, Mandrill will fallback and attempt a POST request.

  • The POST will be the same type of POST as a Mandrill webhook, except that the mandrill_events parameter will be an empty array, and the POST will be signed with a with a generic key (with the value 'test-webhook').

Test Inbound Webhooks

Now that you’ve added an inbound domain and one or more routes, you can test your inbound webhooks.

Next, go to the Inbound page in your Mandrill account, click Routes for the inbound domain you want to test, then click the send test button. We’ll POST 2 example inbound events to your webhook URL.

Third-party webhook testing and debugging tools

If you want to test webhooks in an external or temporary environment before making changes in production, check out one or more of the third-party tools listed below.


RequestBin provides you with a URL to collect and inspect HTTP requests. To get started, go to, check the box next to "Private (only viewable from this browser)", then click the "Create a RequestBin" button. Next, copy the bin URL they provide for you and enter that as your webhook URL for your inbound route in Mandrill:

RequestBin test URL for inbound webhooks in Mandrill web interface

Save your route, then click the send test button to generate two example POSTs to your RequestBin URL. Inspect requests with RequestBin by clicking the button in next to your bin URL in the upper right corner of the page or editing your bin URL and appending ?inspect to the end.


Runscope provides API performance monitoring and HTTP request logging and inspection. Get started by creating a new Runscope bucket to capture incoming requests from Mandrill (you'll use the bucket URL as your Mandrill webhook URL).

In Mandrill, save your webhook URL then click the send test button to generate two example POSTs to your Runscope Bucket. You can view the test requests in Runscope in the Captures stream view or Traffic Inspector.


ngrok creates a secure public URL to a local server on your machine so you can test webhooks locally. Follow the steps in the ngrok docs to get started.

Grab the forwarding URL they provide (like and add this as the webhook URL for your inbound route in Mandrill. Save your route then click the send test button to generate 2 example POSTs to your ngrok public URL. Inspect your ngrok traffic by visiting http://localhost:4040/ in your web browser.


Mandrill batches events for each webhook URL and POSTs approximately every minute. If the webhook URL doesn't return a 200 HTTP response code, that POST request will be re-attempted up to 100 times and random increasing intervals.

If a particular POST request is unsuccessful and is being retried, no other POSTs will be attempted until the first one succeeds or ultimately fails (after 100 attempts). Subsequent events are batched and deferred until the first completes. Once the first batch completes, deferred batches will be processed sequentially.

Because webhook requests can ultimately fail, it's best to accept and store data (with an HTTP 200 response to Mandrill) for later processing to avoid data loss.

Inbound Events Format

Inbound emails are processed based on the routes you’ve set up, and messages matching the routes are sent to your specified URL(s) as a webhook.

ts The timestamp when the event occurred—integer UTC Unix format.
event The name of the event (for inbound, will be inbound).
msg Details about the message for which the event occurred.
raw_msg the full content of the received message, including headers and content
headers an array of the headers received for the message, such as ‘Dkim-Signature’, ‘Mime-version’, ‘Date’, ‘Message-Id’, etc.
text the text version of the message
html the HTML version of the message
from_email the from email address for the message
from_name the from name for the message
to the recipients of the message, and their names
email the email address where Mandrill received the message
subject the subject line of the message
tags the tags applied to the message
sender the Mandrill sender of the message
attachments an array of attachments for the message, with filenames as keys. If there are no attachments, key is omitted. Each attachment has the following keys:
name the file name
type the MIME type of the attachment
content the attachment content
base64 boolean whether the attachment contents are Base64 encoded
images an array of images for the message, with filenames as keys. If there are no images, key is omitted. Each image has the following keys:
name the file name
type the MIME type of the image
content the image content
base64 boolean whether the image contents are Base64 encoded
spam_report the results of processing the message with the default SpamAssassin rules. Contains the following keys:
score the total spam score for the message
matched_rules an array containing details about the rules that the message matched. Each rule entry contains the following keys:
name the name of the rule
description a short description of the rule
score the score for this individual rule
spf spf validation results, or null if an error occurred while checking SPF for the message. Contains the following keys:
result the spf validation result. One of: pass, neutral, fail, softfail, temperror, permerror, none
detail a human-readable description of the result
dkim details about the message’s DKIM signature, if any
signed boolean whether the message contained a DKIM signature (true or false)
valid whether the message’s DKIM signature was valid. Always false if signed is false.


For inbound emails, tags and sender are included to match other webhooks, but inbound messages generally won’t have tags since they’re being received instead of sent, and the sender is null since the event is for a message not being sent by Mandrill.