Building an X-SMTPAPI Header

The Twilio SendGrid SMTP service allows you to pass SendGrid a JSON string with as many SMTP objects as you want. This functionality is made possible by including a header named X-SMTPAPI. This page provides instructions for using the X-SMTPAPI to modify and control your mail send.

The X-SMTPAPI is a powerful way to modify your SMTP messages. However, there are several things to keep in mind when using the header.

• Ensure that you are sending just ONE X-SMTPAPI header per SMTP transaction. For any request received with multiple X-SMTPAPI headers on the same request, Twilio SendGrid will adhere to the first X-SMTPAPI header instance on each request.
• There is a hard limit of 10,000 addresses in a multiple recipient email. However, the best practice is to split large jobs into separate transactions of approximately 1,000 recipients, which allows better processing load distribution. If you have a large number of additional substitutions or sections in the headers, it is best to split the send into even smaller groups.
• When using the X-SMTPAPI header to send to multiple recipients, you cannot use SMTP's standard RCPT TO command to also send to multiple recipients. Doing so can generate duplicate messages to the addresses listed in both the X-SMTPAPI "to" field and the RCPT list. For more information, see RFC 5321.
• Ensure that the header is limited to a maximum total line length of 1,000 characters. Failure to do this can cause intermediate Mail Transfer Agents (MTAs) to split the header on non-space boundaries, which causes inserted spaces in the final email. If your email is going through another MTA before reaching SendGrid, it is likely that the other MTA will have an even lower setting for maximum header length and may truncate the header.
• When using the X-SMTPAPI header, if our system encounters a parsing error, the message will be bounced to the address specified in the MAIL FROM portion of the SMTP session. The MAIL FROM address is re-written when we send the email for final delivery, so it is safe to set the MAIL FROM to an address that can receive the bounces and alert you to any errors.
• When sending Unicode characters via the SMTP API, you should escape these characters using the \u escape character. For example, the Unicode á character will look like this: \u00E1.

1
{
2
  "to": ["example@example.com", "example@example.com"],
3
  "sub": {
4
    "%name%": ["Ben", "Joe"],
5
    "%role%": ["%sellerSection%", "%buyerSection%"]
6
  },
7
  "category": ["Orders"],
8
  "unique_args": {
9
    "orderNumber": "12345",
10
    "eventID": "6789"
11
  },
12
  "filters": {
13
    "footer": {
14
      "settings": {
15
        "enable": 1,
16
        "text/plain": "Thank you for your business"
17
      }
18
    }
19
  },
20
  "send_at": 1409348513
21
}

You can customize the emails you send via SMTP by using different settings (also referred to as filters).

The X-SMTPAPI header is a JSON-encoded object (key-value pairs) consisting of several sections. Below are examples of JSON strings using each section.

• Scheduling Your Send
• BCC Behavior
• Substitution Tags
• Suppression Groups
• Categories
• Unique Arguments
• SMTP Filters
• IP Pools

Schedule your email send time using the send_at parameter within your X-SMTPAPI header. Set the value of send_at formatted as a UNIX timestamp.

1
{
2
  "send_at": 1409348513
3
}

For more information, see our scheduling parameters documentation.

It is possible to simulate blind carbon copy (BCC) behavior using SMTP with or without the X-SMTPAPI header. The concept of BCC exists outside of SMTP as defined by RFC 5321.

When sending email with SMTP, all recipients are listed using SMTP's RCPT (recipient) command. In addition to the sender, which is set with SMTP's MAIL command, these RCPT addresses can be thought of as part of the message envelope—they instruct sending email servers where to deliver the message. These addresses are not designated as carbon copy (CC), BCC, or another type of recipient—they are all just recipients.

The SMTP DATA command follows the MAIL and RCPT commands in an SMTP transaction. The DATA command allows you to insert message headers, which can be thought of as portions of the email body or the text inside the envelope. The DATA command is what allows you to create BCC behavior using SMTP without the X-SMTPAPI.

The following code shows an example of an SMTP transaction with BCC behavior. How this example achieves BCC behavior is explained following the example.

1
235 Authentication successful
2
MAIL FROM:tiramisu@example.com
3
250 Sender address accepted
4
RCPT TO:person1@sendgrid.com
5
250 Recipient address accepted
6
RCPT TO:person2@sendgrid.com
7
250 Recipient address accepted
8
DATA
9
354 Continue
10
From: "Tira Misu" <tiramisu@example.com>
11
To: <person1@sendgrid.com>
12
Subject: Test message subject
13
This is the test message body.
14
.
15
250 Ok: queued as Yo60h6C5ScGPeP5fUWU3Kw

Notice that there are two recipients designated by RCPT commands, "person1@sendgrid.com" and "person2@sendgrid.com." These addresses are both part of the message envelope.

In the DATA command, there is also a "To" header. This header lists only "person1@sendgrid.com." This is where differentiating between the envelop "To" (RCPT TO) and header "To" becomes important. The header "To" set in the DATA command does not tell the sending email server to deliver the message to any address, only the RCPT or envelop "To" does this. The header "To" instead provides recipients with a friendly display of any addresses included in the "To" header.

To achieve BCC behavior, you can deliver a message to a recipient by adding them in a RCPT but omit their address from the header "To". The message will be delivered to each RCPT address, but only the addresses listed in the header "To" will be visible to other recipients.

In the previous code sample, "person2@sendgrid.com" will be treated like a BCC address because that address is not included in the header "To." The "person1@sendgrid.com" is listed in the header "To" and will therefore be visible to other recipients of the message. This means both recipients receive the message, but recipient2@sendgrid.com is not visible to recipient1@sendgrid.com while recipient1@sendgrid.com is visible to recipient2@sendgrid.com.

By omitting any addresses from the header "To," you will be hiding them from the other recipients and therefore treating them like BCC recipients.

The following code shows an example of an SMTP transaction with BCC behavior using the X-SMTPAPI header. How this example achieves BCC behavior is explained following the example.

1
235 Authentication successful
2
MAIL FROM:tiramisu@example.com
3
250 Sender address accepted
4
RCPT TO:sender@sendgrid.com
5
250 Recipient address accepted
6
DATA
7
354 Continue
8
x-smtpapi: {"to":["person1@sendgrid.com","person2@sendgrid.com"]}
9
From: "Tira Misu" <tiramisu@example.com>
10
Subject: This is a test
11
Body of test message.
12
.
13
250 Ok: queued as uKIPst3rQtCl_hLVB9RvEw

Using the X-SMTPAPI header achieves BCC behavior in a slightly different way than by omitting addresses from a "To" header. The X-SMTPAPI header's "to" field allows you to set multiple recipients in a JSON array.

1
{
2
  "to": ["person1@sendgrid.com", "person2@sendgrid.com"]
3
}

When SendGrid receives the message and parses the X-SMTPAPI header, it will treat each recipient address in the X-SMTPAPI "to" field as a separate RCTP TO or envelope address. This means each recipient will receive the same DATA content, but with an added friendly display "to" header set to its own address. A single recipient in the X-SMTPAPI "to" field in the previous code sample will eventually look something like the following example.

1
235 Authentication successful
2
MAIL FROM:test@example.com
3
250 Sender address accepted
4
RCPT TO:person1@sendgrid.com
5
250 Recipient address accepted

The addresses in the X-SMTPAPI "to" field are not duplicated in a header "To," for all recipients. Only the individual recipient is included in the header "To" for each messages (Each recipient sees only their own address). The additional recipients will therefore not be visible to each recipient of the message.

Substitution tags allow you to dynamically insert specific content relevant to each of your recipients, such as their first and last names.

For example, to use a substitution tag to replace the first name of your recipient, insert the tag {{name}} in the HTML of your message:

1
<html>
2
  <head></head>
3
  <body>
4
    <p>
5
      Hello {{name}},<br />
6
      The body of your email would go here...
7
    </p>
8
  </body>
9
</html>

To define the value that will replace the {{name}} tag, define the following in your X-SMTPAPI header:

1
{
2
  "to": ["john.doe@example.com", "jan.doe@example.com"],
3
  "sub": {
4
    "{{name}}": ["John", "Jane"]
5
  }
6
}

For more information, see our substitution tags documentation.

Section tags are similar to substitution tags, but rather than replace tags with content for each recipient; section tags allow you to replace a tag with more generic content— like a salutation.

For more information, see our section tags documentation.

You can specify an unsubscribe group for an email sent via SMTP by including the asm_group_id parameter in your X-SMTPAPI header. Set the value of asm_group_id to the numerical ID of the group you would like to use.

1
{
2
  "asm_group_id": 1
3
}

For more information, see our suppression groups documentation.

Categories allow you to track your emails according to broad topics that you define, like "Weekly Newsletter" or "Confirmation Email". Define the category by using the category parameter within your X-SMTPAPI header:

1
{
2
  "category": "Example Category"
3
}

For more information, see our categories documentation.

Use unique arguments to track your emails based on specific identifiers unique to individual messages. Unique arguments can be retrieved via SendGrid's Event Webhook or your email activity page.

For more information, see our unique arguments documentation.

SMTP Filters can be used for turning on or off a number of different features for your sending. For example, you can turn on open or click tracking on a per-send basis.

For more information, see our SMTP Filters documentation.

IP Pools can be used to send you mail over a specific group of IPs. It is common to create different pools for transactional and marketing email.

For more information, see our IP Pools documentation.

1
{
2
  "ip_pool": "pool_name"
3
}

• How to send email
• Getting started with the API
• SMTP Service Crash Course
• Getting Started with the SMTP API
• Integrating with SMTP