Section tags are similar to substitution tags in how they’re built, but are specific to the message, not the recipient. You have to have a substitution tag value for each recipient, but you can have any number of section tags. Section tags can then contain Substitution tags for the recipient if needed. Section tags have to be contained within a Substitution tag, since SendGrid needs to know which data to populate for the recipient. See the Section Tag Example Walkthrough below.

It’s possible & acceptable to use only Substition tags. However, that method is not DRY, and you may come against message size limitations.


The format of the SMTP API section tag has the form:

1
2
3
4
5
6
{
  "section": {
    ":sectionName1": "section 1 text",
    ":sectionName2": "section 2 text"
  }
}

How you flag your section tags may depend on the library you use to create your SMTP connection, the language you are writing your code in, or any intermediate mail servers that your servers will send mail through. In some cases -subVal- may be the best choice while in other cases, %subVal%, #subVal#, or :subVal may make more sense. The flag doesn’t matter, as long as it’s a unique string.

Do not use spaces inside your section or substitution tags! e.g. %first name% The space breaks the string.


Section Tag Walkthrough

Message body sent to SendGrid:

1
2
3
4
5
6
7
8
9
10
11
12
<html>
 <body>
   Hi :salutation,<br />
   Thanks so much for joining us at our event!

   <p>You have registered for the following event:<br />
    :event_details.</p>

   Thanks,<br />
   The SendGrid Team
 </body>
</html>

The accompanying X-SMTPAPI JSON header would look like:

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": [
    "alice@foo.com",
    "bob@bar.com",
    "casey@baz.com"
  ],
  "sub": {
    ":salutation": [
      ":female",
      ":male",
      ":neutral"
    ],
    ":name": [
      "Alice",
      "Bob",
      "Casey"
    ],
    ":event_details": [
      ":event1",
      ":event2",
      ":event1"
    ],
    ":event_date": [
      "Jan 1",
      "Feb 14",
      "Aug 11"
    ]
  },
  "section": {
    ":male": "Mr. :name",
    ":female": "Ms. :name",
    ":neutral": ":name",
    ":event1": "New User Event on :event_date",
    ":event2": "Veteran User Appreciation on :event_date"
  }
}

Alice receives:

1
2
3
4
5
6
7
8
9
10
11
12
<html>
 <body>
   Hi Ms. Alice,<br />
   Thanks so much for joining us at our event!

   <p>You have registered for the following event:<br />
    New User Event on Jan 1.</p>

   Thanks,<br />
   The SendGrid Team
 </body>
</html>

Bob receives:

1
2
3
4
5
6
7
8
9
10
11
12
<html>
 <body>
   Hi Mr. Bob,<br />
   Thanks so much for joining us at our event!

   <p>You have registered for the following event:<br />
    Veteran User Appreciation on Feb 14.</p>

   Thanks,<br />
   The SendGrid Team
 </body>
</html>

Casey receives:

1
2
3
4
5
6
7
8
9
10
11
12
<html>
 <body>
   Hi Casey,<br />
   Thanks so much for joining us at our event!

   <p>You have registered for the following event:<br />
    New User Event on Aug 11.</p>

   Thanks,<br />
   The SendGrid Team
 </body>
</html>

Section Tag Walkthrough Explained

Our example uses nested substitution and section tags in order to demonstrate the possible complexity that can be used to create extremely customizable emails for your users.

Substitution process:

  1. :salutation body tag read, which directs to the Section tag.
  2. :salutation header value populated to body. This creates a :name tag in the body.
  3. :name body tag read, which directs to the Substitution tag.
  4. :name header value populated to body.
  5. :event_details body tag read, which directs to the Section tag.
  6. :event_details header value populated to the body. This creates a :event_date tag in the body.
  7. :event_date body tag read, which directs to the Substitution tag.
  8. :event_date header value populated to the body.