SMTP Headers: Custom Fields, SendGrid Magic

As a developer, you utilize the SMTP protocol whenever your app sends or receives an email. This protocol is well defined in several RFCs, but who wants to sift through RFCs in order to take advantage of full power of email (actually, I do, but I’m strange)? In the post I’ll give you guidance to dig as deep as you want and I’ll also tell you the basics needed to get started right away.

Formal Definition

Email headers are typically hidden from the end user. Generally, email headers are used to define routing information, which determine where the email is sent and how it arrived there. We can also add custom information to the header as discussed in the following section.

The Simple Mail Transfer Protocol (SMTP) is currently defined by RFC 5321 and you can find header field definitions in RFC 822 and syntax standards in RFC 5322.

RFC 2076 provides a list of the most commonly used email headers. Wikipedia also provides a list of the email headers that must and should be included.

SendGrid’s Header Magic

According to RFC 822 we have the ability to add custom email headers prefixed with X-.

We have added such a header, X-SMTPAPI, which allows you to dynamically customize your emails at send time.

You can use this header to turn on/off SendGrid Apps (Filters), add categories, create substitution tags, create sections that allow you to simplify substitution values common to many recipients and add your own unique arguments.

You may find code examples that utilize X-SMTPAPI in Perl, PHP, Python and Ruby at our documentation.

Email Header Customization

Using SendGrid, you can add an unlimited number of unique arguments to your email, which can then be tracked using our Event Webhook or at the Email Activity page.

Using our SMTP API, it is easy to add your own unique arguments to the header using a simple JSON string.

If you prefer to work with a REST-like API, our Web API mail endpoint also allows you to add your own custom headers. Simply provide your JSON string using the headers parameter.

Tools

Google and MXToolBox have tools that make it easy to interpret email headers by simply pasting the raw headers into their service. Both services also include tutorials to help deepen your understanding.

Ideas for Usage

Using our built in X-SMTPAPI header, you can:

• Categorize your emails according to type and review email analytics by your defined types. (e.g Marketing vs. Transactional).
• Dynamically turn on/off SendGrid Apps (Filters) depending on business logic. (e.g. Footer customization)
• Create smart templates that fill in tag substitutions at run-time.

By creating your own custom arguments, you can:

• Track individual email behavior.
• Automate the processing of email replies.
• Send variables to assist with future email processing.
• Create email readers that adapt based on the custom arguments.