Twilio SendGrid can help process email using the Inbound Parse webhook. The Inbound Parse webhook parses the contents and attachments for incoming email to a email server, then send that data to a URL of your choice. You can choose how your application handles this parsed data.
To review pre-made integrations for the Twilio SendGrid Inbound Parse webhook, see the Library Index.
Prerequisites
Before you configure the Inbound Parse webhook, complete the following tasks:
Create and configure MX records.
Choose the hostname or receiving domain that receives the emails to parse.
Define the URL that receives your parsed emails.
Create an MX record
Go to the MX Records page on your domain provider website.
If you don't know who hosts your domain, contact your website administrator or networking team.
Create a new MX record.
Set the subdomain or hostname to the one that processes incoming email followed by a period (.).
This hostname should serve no other purpose other than parsing your incoming email.
Never change the MX record for your domain. If you do, your domain stops receiving email.
Set the priority to 10.
Set the mail server address to mx.sendgrid.net.
If your provider offers field for priority, type 10 before the mail server address. 10 mx.sendgrid.net.
Leave the Time to Live or TTL value unchanged.
Click Save or Add depending on your domain provider user interface.
Example MX record
1
HOST TYPE TTL SERVER
2
------ ---- ---- ----------------
3
parse. MX 3600 mx.sendgrid.net.
Set the email server and webhook URL
The inbound parse requires two parameters:
Receiving domain: The domain that encompasses the email servers that receive the email messages you want to parse
Destination URL: The URL at which your Inbound Parse webhook is hosted
In the Destination URL, type the webhook URL that should receive the parsed email data. This URL must be accessible from the internet.
In the Additional Options section, select one or both of the options.
To have Inbound Parse check incoming email 2.5 MB or smaller for spam, select Check incoming emails for spam. Checking this box also includes the spam report and spam score in the payload. In general, spam email messages don't exceed 2.5 MB. The Twilio SendGrid-generated report marks those messages as not spam.
To URL encode both the email messages and their attachments, select POST the raw, full MIME message.
If you don't select POST the raw, full MIME message, Twilio SendGrid URL encodes the message but not their attachments. If your code only reads URL-encoded content, it can drop attachments.
Click Add.
Test your webhook
To test the webhook, send an email from your email account to an email address on your receiving domain, like example@example.com.
The local-part of this email address, anything before @, can be any single word or combination of words with three exceptions: abuse, postmaster, and unsubscribe. This means you can't use abuse@subdomain.example.com, postmaster@subdomain.example.com, and unsubscribe@subdomain.example.com.
Examples of the payloads and their parameters
Default Data FormatRaw Data Format
Parameter
Description
headers
The raw headers of the email.
dkim
The verification results of any DKIM and domain keys signatures in the message.
content-ids
The identifiers of the attachments included in the email message.
to
A JSON object containing the email address of the recipient extracted from the message headers.
text
The text-formatted form of the email message body.
html
The HTML-formatted form of the email message body, if provided.
from
The email sender extracted from the message headers.
sender_ip
The IP address from which the email message was sent.
A JSON object that contains the character sets of the values extracted from the message.
SPF
The results of the Sender Policy Framework verification of the message sender and receiving IP address.
View an example default payload
Default webhook payload
1
[Date] array(16) {
2
["headers"]=>
3
string(1970) "Received: by mx0047p1mdw1.sendgrid.net with SMTP id 6WCVv7KAWn Wed, 27 Jul 2016 20:53:06 +0000 (UTC)
4
Received: from mail-io0-f169.google.com (mail-io0-f169.google.com [209.85.223.169]) by mx0047p1mdw1.sendgrid.net (Postfix) with ESMTPS id AA9FFA817F2 for <example@example.com>; Wed, 27 Jul 2016 20:53:06 +0000 (UTC)
5
Received: by mail-io0-f169.google.com with SMTP id b62so81593819iod.3 for <example@example.com>; Wed, 27 Jul 2016 13:53:06 -0700 (PDT)
A single-element array containing the address of the recipient of the received email message
subject
The subject line of the email message.
spam_score
The SpamAssassin rating that determines if it considers this message spam.
charsets
A JSON object that contains the character sets of the values extracted from the message.
SPF
The results of the Sender Policy Framework verification of the message sender and receiving IP address.
(information)
Limit message size
To aid in delivery, limit the total size of your message, including the message and attachments, to 30 MB. Other inbox providers might have their own limitations. Some ISPs and companies might limit the size, type of attachments, or both, or even block them completely.
Raw webhook payload
1
array(11) {
2
["dkim"]=>
3
string(22) "{@sendgrid.com : pass}"
4
["email"]=>
5
string(8879) "Received: by mx0032p1mdw1.sendgrid.net with SMTP id rOkt2xLLKV Tue, 19 Jul 2016 15:06:29 +0000 (UTC)
6
Received: from mail-it0-f45.google.com (mail-it0-f45.google.com [209.85.214.45]) by mx0032p1mdw1.sendgrid.net (Postfix) with ESMTPS id 26D6080397 for <parse@parse.yourdomain>; Tue, 19 Jul 2016 15:06:22 +0000 (UTC)
7
Received: by mail-it0-f45.google.com with SMTP id f6so93587860ith.1 for <example@example.com>; Tue, 19 Jul 2016 08:06:22 -0700 (PDT)