Sections are an extension of substitution values that allow a user to specify large text blocks that will be mostly the same that can then be selected and customized on a per user basis. This is useful for sending dynamic content where a large section of the body will be similar across several users, as opposed to duplicating that text each time.

The format of the SMTP section key has the form:

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

Typical usage is to have a tag in the body of your email that references a per user substitution tag. This user tag will contain a reference to a section tag. Section text may contain references to per recipient substitution variables.

Section Tag Example

Message body:
1
2
3
4
5
6
7
8
<html>
 <body>
   Hi -intro-,<br>
   Thanks so much for joining us at our event!
   Thanks,
   The SendGrid Team
 </body>
</html>

An accompanying SMTPAPI JSON header might look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
X-SMTPAPI: {
  "to": ["john@bar.com","jane@baz.com","bill@baz.com"],
  "sub": {
    "-intro-": ["-greetGuy-", "-greetGirl-", "-greetBoy-"],
    "-name-": ["John", "Jane", "Bill"]
  },
  "section": {
    "-greetGuy-": "Mr. -name-",
    "-greetGirl-": "Ms. -name-",
    "-greetBoy-": "-name-"
  }
}
The final email for Jane would look like this:
1
2
3
4
5
6
7
8
<html>
 <body>
   Hi Ms. Jane,<br>
   Thanks so much for joining us at our event!
   Thanks,
   The SendGrid Team
 </body>
</html>