SendGrid can parse the attachments and contents from incoming emails. Application examples include receiving uploads and posting blog articles via email.
The parse API will POST the parsed email to a URL configured you specify. SendGrid automatically queues and retries any POSTs that respond with a 5XX status error. Additionally, we retry errors when we encounter 4XX status responses to prevent data loss for customers that have misconfigured their website or POST URL.
Info If you don’t want email messages to be retried in case of an error in delivery, please respond with a 200 status to the POST request.
In order to avoid returning an error your link is required to return a 200 HTTP code when the email is received. This lets our system know that your link has received the email response and then it is removed from our send queue. If we do not get a valid 200 HTTP response, our servers will believe they have failed to deliver your message and will continue trying to send it. Messages that cannot be delivered after 3 days will be dropped.
The following steps are required to begin parsing email:
- Point the MX Record of the Domain/Hostname or Subdomain to mx.sendgrid.net
- Associate the Domain/Hostname and the URL in the Parse API settings page
The following parameters will be included in the POST to your callback URL.
|headers||The raw headers of the email.|
|text||Text body of email. If not set, email did not have a text body.|
|html||HTML body of email. If not set, email did not have an HTML body.|
|from||Email sender, as taken from the message headers.|
|to||Email recipient field, as taken from the message headers.|
|cc||Email cc field, as taken from the message headers.|
|dkim||A JSON string containing the verification results of any dkim and domain keys signatures in the message.|
|SPF||The results of the Sender Policy Framework verification of the message sender and receiving IP address.|
|envelope||A JSON string containing the SMTP envelope. This will have two variables: to, which is an array of recipients, and from, which is the return path for the message.|
|charsets||A JSON string containing the character sets of the fields extracted from the message.|
|spam_score||Spam Assassin’s rating for whether or not this is spam.|
|spam_report||Spam Assassin’s spam report.|
|attachments||Number of attachments included in email.|
|attachmentX||These are file upload names, where N is the total number of attachments. For example, if the number of attachments is 0, there will be no attachment files. If the number of attachments is 3, parameters attachment1, attachment2, and attachment3 will have file uploads. TNEF files (winmail.dat) will be extracted and have any attachments posted.|
Info The total message size limit, including the message itself and any number of attachments, is 20MB. Be aware that other mail handlers will have their own limitations, and some ISPs and companies either dramatically limit the size and/or type of attachments, or even block them altogether.
If you will be receiving email which is not in ASCII only format, you will want to read this section.
Messages, and their headers, can have character set data associated with them. In order to simplify the parsing of messages for the end user, SendGrid will decode the to, from, cc, and subject headers if needed. All headers will be converted to UTF-8 for uniformity, since technically a header can be in many different character sets.
The charsets variable will contain a JSON encoded hash of the header / field name and its respective character set. For instance, it may look like:
This shows that all headers should be treated as UTF-8, and the text body is latin1.
In this example, we want to parse all emails at firstname.lastname@example.org and post the parsed email to http://sendgrid.com/email.php.
Given this scenario, the following are the parameters you would set at the Parse API settings page:
1 2 3 4 5 6 7 8 9 10 11 12
Warning If you are using a hosting service, you don’t have direct access to the server’s file system. In that case, you need to modify the path for the parse log to be somewhere you do have access to. In most cases, the second line in the code above:
1 2 3
should be changed to…
1 2 3
After receiving the email, the file /tmp/parse.log will contain the following (note that the contents depend upon what parameters you have enabled, also note that the formatting of the data you receive may differ slightly):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
1 2 3 4 5 6 7 8 9 10 11