Now that you’ve sent a sent a test SMTP email with Telnet, and integrated with SendGrid, it’s time to build content.

Getting started building

SMTP works by passing a JSON string with as many SMTP objects as you want to SendGrid. To do this, add the JSON string to your message under a header named “X-SMTPAPI” like this:

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
{
  "to": [
    "example@example.com",
    "example@example.com"
  ],
  "sub": {
    "%name%": [
      "Ben",
      "Joe"
    ],
    "%role%": [
      "%sellerSection%",
      "%buyerSection%"
    ]
  },
  "section": {
    "%sellerSection%": "Seller information for: %name%",
    "%buyerSection%": "Buyer information for: %name%"
  },
  "category": [
    "Orders"
  ],
  "unique_args": {
    "orderNumber": "12345",
    "eventID": "6789"
  },
  "filters": {
    "footer": {
      "settings": {
        "enable": 1,
        "text/plain": "Thank you for your business"
      }
    }
  },
  "send_at": 1409348513
}

Limitations

  • There is a hard limit of 10,000 addresses in a multiple recipient e-mail. However, the best practice is to split up large jobs to around 1,000 recipients - this 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 to send to multiple recipients, you cannot use the standard SMTP protocols “TO” field to send to multiple recipients because doing so can generate duplicate messages to the addresses listed in both. 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 MTA’s to split the header on non-space boundaries- this causes inserted spaces in the final e-mail. If your e-mail is going through another MTA before reaching SendGrid, it is likely to have an even lower setting for maximum header length and may truncate the header.
  • When using the API, 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 e-mail out for final delivery, so it is safe to set this to an address that can receive the bounces so that you will be alerted to any errors.
  • When sending Unicode characters via the SMTP API, you should escape these characters using the \u escape character. When you do this, Unicode characters like á becomes \u00E1.

Customizing your send (filters)

You can customize the emails you send via SMTP by using different settings (also referred to as filters). Change these settings in the X-SMTPAPI header.

For example, to send a blind carbon copy (BCC) of your email to the address example@example.com, include the following in your X-SMTPAPI header:

1
2
3
4
5
6
7
8
9
10
{
  "filters" : {
    "bcc" : {
      "settings" : {
        "enable" : 1,
        "email" : "example@example.com"
      }
    }
  }
}

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

Scheduling Your Send

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

1
2
3
{
  "send_at": 1409348513
}

For more information, see our scheduling parameters documentation.

Substitution Tags

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

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

1
2
3
4
5
6
7
8
9
10
11
12
{
  "to": [
    "john.doeexampexample@example.com",
    "example@example.com"
  ],
  "sub": {
    "{{name}}": [
      "John",
      "Jane"
    ]
  }
}

For more information, see our substitution tags documentation.

Section Tags

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.

Suppression Groups

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

1
2
3
{
  "asm_group_id": 1
}

For more information, see our suppression groups documentation.

Categories

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

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

For more information, see our categories documentation

Categories should only be used for broad topics. To attach unique identifiers, please use unique arguments.

Unique Arguments

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.

Additional Resources