SendGrid’s SMTP API allows developers to specify custom handling instructions for e-mail. This is accomplished through a header, X-SMTPAPI, that is inserted into the message. The header is a JSON encoded list of instructions and options for that email.

The X-SMTPAPI headers that you add will be stripped from the final email, because they are instruction headers for how SendGrid will handle your email. So you can expect to not actually see these headers in the final email.

An example X-SMTPAPI header

1
2
3
4
5
{
    "category": [
        "newuser"
    ]
}

In this case, the header is telling the processing routine to assign this email the category of “newuser”.

The X-SMTPAPI Header

The X-SMTPAPI header is a JSON-encoded associative array consisting of several sections, below are examples of JSON strings using each section. This header can be added to any SMTP message sent to SendGrid and the instructions in the header will be interpreted and applied to that message’s transaction.

See Requirements and Limitations

Apps: An associative array of filters and their settings, used to override filter settings is already setup for your account. Settings are an associative array of the setting names and their values.

1
2
3
4
5
6
7
8
9
10
11
{
  "filters": {
    "footer": {
      "settings":
        {
          "enable": 1,
          "text/plain": "Thank you for your business"
        }
    }
  }
}

Category: Associates the category of email this should be logged as. You may insert up to 10 categories as an array, these categories are not predefined. Categories are intended for broader tracking, such as “newsletter” or “password_reset”.

1
2
3
4
5
6
{
  "category": [
    "category1",
    "category2"
  ]
}

Scheduling Parameters: A collection of attributes that can delay sending and allow for faster mail flow.

1
2
3
{
  "send_at": 1409348513
}

Section: Sections can be used to simplify substitution values that are common to many recipients. This is an associative array of sections that can be used in substitution values.

1
2
3
4
5
6
{
  "section": {
    "%sellerSection%": "Seller information for: %name%",
    "%buyerSection%": "Buyer information for: %name%"
  }
}

Substitution: An associative array of substitution tags, where each tag is associated with a list of replacement text for the tag in the body text. Each Substitution value corresponds to an email in the “To” section of the JSON string.

1
2
3
4
5
6
7
8
9
10
11
12
{
  "sub": {
    "%name%": [
      "Ben",
      "Joe"
    ],
    "%role%": [
      "%sellerSection%",
      "%buyerSection%"
    ]
  }
}

To: An array of addresses to send the message to, optionally including the display name.

1
2
3
4
5
6
{
  "to": [
    "<ben@example.com>",
    "Joe Smith <joe@example.com>"
  ]
}

Unique Arguments: An associative array of arguments and their values to be applied to all emails sent in this SMTP API transaction. Unique Args are intended for more detailed tracking, such as “newsletter_fall_sale_1_1_14” or “password_reset_user123456”.

1
2
3
4
5
6
{
  "unique_args": {
    "orderNumber": "12345",
    "eventID": "6789"
  }
}
For an example X-SMTPAPI header using all the above methods see our Using the SMTP API page.