Inbound Email Processing Overview

Set Up an Inbound Domain

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

API

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

{
    "key": "example key",
    "domain": "inbound.example.com"
}

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

Go to Inbound in your Transactional Email account.
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 Transactional Email account. You’ll need to add these records or edit your existing MX records to point to the servers shown in that window only.

Web app

To set up an inbound domain:

Go to Inbound in your Transactional Email account.
Add the domain or subdomain name where you’ll receive mail and click the + Add New Inbound Domain button.
Click the DNS Settings button for any domain you’ve added to get the DNS records you’ll need to add for your domain.
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.

Note

Transactional Email 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 Transactional API or web application. Let’s start by looking at how to add a route via the Transactional 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.

API

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

{
    "key": "example key",
    "domain": "inbound.example.com",
    "pattern": "mailbox-*",
    "url": "http://example.com/webhook-url"
}

Web app

To add a new route:

Go to Inbound in your Transactional Email account.
Click the Routes button next to the inbound domain you want to edit.
Click the + Add New Route button.
Enter the full local part or pattern in the first box that appears.
Enter the webhook URL where Transactional Email should POST inbound emails.
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:

Notes

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, Transactional Email will fallback and attempt a POST request.
The POST will be the same type of POST as a Transactional Email 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 Transactional Email 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

RequestBin provides you with a URL to collect and inspect HTTP requests. To get started, go to https://requestbin.com/, 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 Transactional Email:

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

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

In Transactional Email, 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

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 http://92832de0.ngrok.io) and add this as the webhook URL for your inbound route in Transactional Email. 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.

Troubleshooting

Transactional Email 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 Transactional Email) 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.

Key	Description
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 Transactional Email received the message
	subject	the subject line of the message
	tags	the tags applied to the message
	sender	the Transactional Email 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 Transactional Email.

Articles in this section

Inbound Email Processing Overview

In This Article:

Set Up an Inbound Domain

API

Web app

Add a Route

API

Web app

Example routes

Test Inbound Webhooks

Third-party webhook testing and debugging tools

RequestBin

Runscope

ngrok

Troubleshooting

Inbound Events Format