SendGrid can parse the attachments and contents of incoming emails. Application examples include receiving uploads and posting blog articles via email.
The Parse API will POST the parsed email to a URL that you specify. If a POST is unsuccessful, SendGrid automatically queues and retries any POSTs that respond with a 4XX or 5XX status. This prevents data loss for customers who have misconfigured their website or POST URL.
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. It is then 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. This can also be done using the Parse Settings Endpoint.
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. Attachments provided with this parameter, are provided in the form of file uploads. TNEF files (winmail.dat) will be extracted and have any attachments posted.|
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.