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

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