Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Substitution and Section Tags


(information)

Info

If you prefer to use Twilio SendGrid Dynamic Transactional Templates and Marketing Campaigns designs, use Handlebars.


Simple Name Substitution

simple-name-substitution page anchor

This example will show you how to create a name substitution for your emails. We will be using the tag -name- in this example. In this example, the tag -name- will get replaced with the name of the recipient.

Email Content

email-content page anchor

_10
Hello -name-,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello -name-,<br /></p>
_10
</body>
_10
</html>


_10
{
_10
"to": ["john@domain.com", "jane@domain.com", "matt@domain.com"],
_10
"sub": {
_10
"-name-": ["John", "Jane", "Matt"]
_10
}
_10
}


_59
{
_59
"personalizations": [
_59
{
_59
"to": [
_59
{
_59
"email": "john@domain.com",
_59
"name": "John"
_59
}
_59
],
_59
"subject": "Example 01",
_59
"substitutions": {
_59
"-name-": "John"
_59
}
_59
},
_59
{
_59
"to": [
_59
{
_59
"email": "jane@domain.com",
_59
"name": "Jane"
_59
}
_59
],
_59
"subject": "Example 02",
_59
"substitutions": {
_59
"-name-": "Jane"
_59
}
_59
},
_59
{
_59
"to": [
_59
{
_59
"email": "matt@domain.com",
_59
"name": "Matt"
_59
}
_59
],
_59
"subject": "Example 03",
_59
"substitutions": {
_59
"-name-": "Matt"
_59
}
_59
}
_59
],
_59
"from": {
_59
"email": "sender@senddomain.com",
_59
"name": "Sender"
_59
},
_59
"reply_to": {
_59
"email": "sender@senddomain.com",
_59
"name": "Sender"
_59
},
_59
"subject": "Example",
_59
"content": [
_59
{
_59
"type": "text/plain",
_59
"value": "Hello -name-,"
_59
},
_59
{
_59
"type": "text/html",
_59
"value": "Hello -name-,"
_59
}
_59
]
_59
}

john@domain.com


_10
Hello John,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello John,<br /></p>
_10
</body>
_10
</html>

jane@domain.com


_10
Hello Jane,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello Jane,<br /></p>
_10
</body>
_10
</html>

matt@domain.com


_10
Hello Matt,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello Matt,<br /></p>
_10
</body>
_10
</html>


First Name and Last Name Substitutions

first-name-and-last-name-substitutions page anchor

This example will show you how to create a first name and last name substitution for your emails. We will be using the tags -first_name- and -last_name- in this example. In this example the tag -first_name- will get replaced with the first name of the recipient and the tag -last_name- will get replaced with the last name of the recipient.


_10
Hello -first_name- -last_name-,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello -first_name- -last_name-,<br /></p>
_10
</body>
_10
</html>


_11
{
_11
"to": [
_11
"john.smith@domain.com",
_11
"jane.williams@domain.com",
_11
"matt.johnson@domain.com"
_11
],
_11
"sub": {
_11
"-first_name-": ["John", "Jane", "Matt"],
_11
"-last_name-": ["Smith", "Williams", "Johnson"]
_11
}
_11
}


_62
{
_62
"personalizations": [
_62
{
_62
"to": [
_62
{
_62
"email": "john.smith@domain.com",
_62
"name": "John Smith"
_62
}
_62
],
_62
"subject": "Example 01",
_62
"substitutions": {
_62
"-first_name-": "John",
_62
"-last_name-": "Smith"
_62
}
_62
},
_62
{
_62
"to": [
_62
{
_62
"email": "jane.williams@domain.com",
_62
"name": "Jane Williams"
_62
}
_62
],
_62
"subject": "Example 02",
_62
"substitutions": {
_62
"-first_name-": "Jane",
_62
"-last_name-": "Williams"
_62
}
_62
},
_62
{
_62
"to": [
_62
{
_62
"email": "matt.johnson@domain.com",
_62
"name": "Matt Johnson"
_62
}
_62
],
_62
"subject": "Example 03",
_62
"substitutions": {
_62
"-first_name-": "Matt",
_62
"-last_name-": "Johnson"
_62
}
_62
}
_62
],
_62
"from": {
_62
"email": "sender@senddomain.com",
_62
"name": "Sender"
_62
},
_62
"reply_to": {
_62
"email": "sender@senddomain.com",
_62
"name": "Sender"
_62
},
_62
"subject": "Example",
_62
"content": [
_62
{
_62
"type": "text/plain",
_62
"value": "Hello -first_name- -last_name-,"
_62
},
_62
{
_62
"type": "text/html",
_62
"value": "Hello -first_name- -last_name-,"
_62
}
_62
]
_62
}

john.smith@domain.com


_10
Hello John Smith,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello John Smith,<br /></p>
_10
</body>
_10
</html>

jane.williams@domain.com


_10
Hello Jane Williams,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello Jane Williams,<br /></p>
_10
</body>
_10
</html>

matt.johnson@domain.com


_10
Hello Matt Johnson,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello Matt Johnson,<br /></p>
_10
</body>
_10
</html>


Simple Greeting Section with Name Substitution

simple-greeting-section-with-name-substitution page anchor
(error)

Danger

Due to low usage, the Section Tags feature has been deprecated. It will be fully removed on 06/22/2020. Click here for more information.

This example will show you how to create a section as a greeting with a name substitution. We will be using the tags -warm_welcome-, -greeting- and -name- in this example. In this example, we have created a greeting using the section tag -warm_welcome-. The -warm_welcome- tag is replaced with the -greeting- substitution which calls the section "Hello -name-,". The -name- tag in "Hello -name-," is then replaced with the recipient's name.


_10
-warm_welcome-


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>-warm_welcome-<br /></p>
_10
</body>
_10
</html>


_10
{
_10
"to": ["john@domain.com", "jane@domain.com", "matt@domain.com"],
_10
"sub": {
_10
"-name-": ["John", "Jane", "Matt"],
_10
"-warm_welcome-": ["-greeting-", "-greeting-", "-greeting-"]
_10
},
_10
"section": {
_10
"-greeting-": "Hello -name-,"
_10
}
_10
}


_65
{
_65
"personalizations": [
_65
{
_65
"to": [
_65
{
_65
"email": "john@domain.com",
_65
"name": "John"
_65
}
_65
],
_65
"subject": "Example 01",
_65
"substitutions": {
_65
"-name-": "John",
_65
"-warm_welcome-": "-greeting-"
_65
}
_65
},
_65
{
_65
"to": [
_65
{
_65
"email": "jane@domain.com",
_65
"name": "Jane"
_65
}
_65
],
_65
"subject": "Example 02",
_65
"substitutions": {
_65
"-name-": "Jane",
_65
"-warm_welcome-": "-greeting-"
_65
}
_65
},
_65
{
_65
"to": [
_65
{
_65
"email": "matt@domain.com",
_65
"name": "Matt"
_65
}
_65
],
_65
"subject": "Example 03",
_65
"substitutions": {
_65
"-name-": "Matt",
_65
"-warm_welcome-": "-greeting-"
_65
}
_65
}
_65
],
_65
"from": {
_65
"email": "sender@senddomain.com",
_65
"name": "Sender"
_65
},
_65
"reply_to": {
_65
"email": "sender@senddomain.com",
_65
"name": "Sender"
_65
},
_65
"subject": "Example",
_65
"content": [
_65
{
_65
"type": "text/plain",
_65
"value": "-warm_welcome-"
_65
},
_65
{
_65
"type": "text/html",
_65
"value": "<html>\n <head></head>\n <body>\n <p>-warm_welcome- \n </p>\n </body>\n</html>"
_65
}
_65
],
_65
"sections": {
_65
"-greeting-": "Welcome -name-,"
_65
}
_65
}


_10
john@domain.com


_10
Hello John,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello John,<br /></p>
_10
</body>
_10
</html>

jane@domain.com


_10
Hello Jane,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello Jane,<br /></p>
_10
</body>
_10
</html>

matt@domain.com


_10
Hello Matt,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello Matt,<br /></p>
_10
</body>
_10
</html>


Greeting Section with First & Last Name Substitutions

greeting-section-with-first--last-name-substitutions page anchor

This example will show you how to create a section with first name and last name substitution for your emails. We will be using the tags -warm_welcome-, -greeting-, -first_name- and -last_name- in this example. In this example, we have created a greeting using the section tag -warm_welcome-. The -warm_welcome- tag is replaced with the -greeting- substitution which calls the section "Hello -first_name- -last_name-,". The -first_name- and -last_name- tags in "Hello -first_name- -last_name-," is then replaced with the recipients first and last names.


_10
-warm_welcome-


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>-warm_welcome-<br /></p>
_10
</body>
_10
</html>


_15
{
_15
"to": [
_15
"john.smith@domain.com",
_15
"jane.williams@domain.com",
_15
"matt.johnson@domain.com"
_15
],
_15
"sub": {
_15
"-first_name-": ["John", "Jane", "Matt"],
_15
"-last_name-": ["Smith", "Williams", "Johnson"],
_15
"-warm_welcome-": ["-greeting-", "-greeting-", "-greeting-"]
_15
},
_15
"section": {
_15
"-greeting-": "Hello -first_name- -last_name-,"
_15
}
_15
}


_68
{
_68
"personalizations": [
_68
{
_68
"to": [
_68
{
_68
"email": "john.smith@domain.com",
_68
"name": "John Smith"
_68
}
_68
],
_68
"subject": "Example 01",
_68
"substitutions": {
_68
"-first_name-": "John",
_68
"-last_name-": "Smith",
_68
"-warm_welcome-": "-greeting-"
_68
}
_68
},
_68
{
_68
"to": [
_68
{
_68
"email": "jane.williams@domain.com",
_68
"name": "Jane Williams"
_68
}
_68
],
_68
"subject": "Example 02",
_68
"substitutions": {
_68
"-first_name-": "Jane",
_68
"-last_name-": "Williams",
_68
"-warm_welcome-": "-greeting-"
_68
}
_68
},
_68
{
_68
"to": [
_68
{
_68
"email": "matt.johnson@domain.com",
_68
"name": "Matt Johnson"
_68
}
_68
],
_68
"subject": "Example 03",
_68
"substitutions": {
_68
"-first_name-": "Matt",
_68
"-last_name-": "Johnson",
_68
"-warm_welcome-": "-greeting-"
_68
}
_68
}
_68
],
_68
"from": {
_68
"email": "sender@senddomain.com",
_68
"name": "Sender"
_68
},
_68
"reply_to": {
_68
"email": "sender@senddomain.com",
_68
"name": "Sender"
_68
},
_68
"subject": "Example",
_68
"content": [
_68
{
_68
"type": "text/plain",
_68
"value": "-warm_welcome-"
_68
},
_68
{
_68
"type": "text/html",
_68
"value": "<html>\n <head></head>\n <body>\n <p>-warm_welcome- \n </p>\n </body>\n</html>"
_68
}
_68
],
_68
"sections": {
_68
"-greeting-": "Welcome -first_name- -last_name-,"
_68
}
_68
}


_10
john.smith@domain.com


_10
Hello John Smith,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello John Smith,<br /></p>
_10
</body>
_10
</html>

jane.williams@domain.com


_10
Hello Jane Williams,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello Jane Williams,<br /></p>
_10
</body>
_10
</html>

matt.johnson@domain.com


_10
Hello Matt Johnson,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello Matt Johnson,<br /></p>
_10
</body>
_10
</html>


Three Different Greeting Sections with First & Last Name Substitutions

three-different-greeting-sections-with-first--last-name-substitutions page anchor

This example will show you how to create three different sections, each with first name and last name substitution for your emails. We will be using the tags -warm_welcome-, -greeting01-, -greeting02-, -greeting03-, -first_name- and -last_name- in this example. In this example, we have created three different greetings using the section tag -warm_welcome-. The -warm_welcome- tag is replaced with either -greeting01-, -greeting02- or -greeting03- substitution. This will call one of the three sections. In each of these sections, there is the -first_name- and -last_name- tags which will get replaced with the recipients first and last names.


_10
-warm_welcome-


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>-warm_welcome-<br /></p>
_10
</body>
_10
</html>


_17
{
_17
"to": [
_17
"john.smith@domain.com",
_17
"jane.williams@domain.com",
_17
"matt.johnson@domain.com"
_17
],
_17
"sub": {
_17
"-first_name-": ["John", "Jane", "Matt"],
_17
"-last_name-": ["Smith", "Williams", "Johnson"],
_17
"-warm_welcome-": ["-greeting01-", "-greeting02-", "-greeting03-"]
_17
},
_17
"section": {
_17
"-greeting01-": "Welcome -first_name- -last_name-,",
_17
"-greeting02-": "Hello -first_name- -last_name-,",
_17
"-greeting03-": "Dear -first_name- -last_name-,"
_17
}
_17
}


_70
{
_70
"personalizations": [
_70
{
_70
"to": [
_70
{
_70
"email": "john.smith@domain.com",
_70
"name": "John Smith"
_70
}
_70
],
_70
"subject": "Example 01",
_70
"substitutions": {
_70
"-first_name-": "John",
_70
"-last_name-": "Smith",
_70
"-warm_welcome-": "-greeting01-"
_70
}
_70
},
_70
{
_70
"to": [
_70
{
_70
"email": "jane.williams@domain.com",
_70
"name": "Jane Williams"
_70
}
_70
],
_70
"subject": "Example 02",
_70
"substitutions": {
_70
"-first_name-": "Jane",
_70
"-last_name-": "Williams",
_70
"-warm_welcome-": "-greeting02-"
_70
}
_70
},
_70
{
_70
"to": [
_70
{
_70
"email": "matt.johnson@domain.com",
_70
"name": "Matt Johnson"
_70
}
_70
],
_70
"subject": "Example 03",
_70
"substitutions": {
_70
"-first_name-": "Matt",
_70
"-last_name-": "Johnson",
_70
"-warm_welcome-": "-greeting03-"
_70
}
_70
}
_70
],
_70
"from": {
_70
"email": "sender@senddomain.com",
_70
"name": "Sender"
_70
},
_70
"reply_to": {
_70
"email": "sender@senddomain.com",
_70
"name": "Sender"
_70
},
_70
"subject": "Example",
_70
"content": [
_70
{
_70
"type": "text/plain",
_70
"value": "-warm_welcome-"
_70
},
_70
{
_70
"type": "text/html",
_70
"value": "<html>\n <head></head>\n <body>\n <p>-warm_welcome- \n </p>\n </body>\n</html>"
_70
}
_70
],
_70
"sections": {
_70
"-greeting01-": "Welcome -first_name- -last_name-,",
_70
"-greeting02-": "Hello -first_name- -last_name-,",
_70
"-greeting03-": "Dear -first_name- -last_name-,"
_70
}
_70
}

john.smith@domain.com


_10
Welcome John Smith,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Welcome John Smith,<br /></p>
_10
</body>
_10
</html>

jane.williams@domain.com


_10
Hello Jane Williams,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Hello Jane Williams,<br /></p>
_10
</body>
_10
</html>

matt.johnson@domain.com


_10
Dear Matt Johnson,


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>Dear Matt Johnson,<br /></p>
_10
</body>
_10
</html>


Three Confirmation Sections and Substitutions

three-confirmation-sections-and-substitutions page anchor

This example will show you how to create three different sections for confirmation emails. We will be using the tags -name-, -confirmations-, -confirmation_001-, -confirmation_002-, -confirmation_003- and -order_id- in this example. In this example, we have created three different confirmations using the section tag -confirmations-. The -confirmations- tag is replaced with either -confirmation_001-, -confirmation_002- or -confirmation_003- substitution. This will call one of the three sections. In each of these sections, there is the -order_id- tag which will get replaced with the recipient's order id.


_10
Hello -name-,
_10
-confirmations-


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>
_10
Hello -name-,<br />
_10
-confirmations-
_10
</p>
_10
</body>
_10
</html>


_17
{
_17
"to": ["john@domain.com", "jane@domain.com", "matt@domain.com"],
_17
"sub": {
_17
"-name-": ["John", "Jane", "Matt"],
_17
"-confirmations-": [
_17
"-confirmation_001-",
_17
"-confirmation_002-",
_17
"-confirmation_003-"
_17
],
_17
"-order_id-": ["12345", "23456", "34567"]
_17
},
_17
"section": {
_17
"-confirmation_001-": "Thanks for choosing SendGrid. This email is to confirm that we have processed your order -order_id-.",
_17
"-confirmation_002-": "Thanks for choosing SendGrid. This email is to confirm that we have processed your order -order_id-. This invoice is to be paid by bank transfer within 7 days from the date of your monthly statement.",
_17
"-confirmation_003-": "Thanks for choosing SendGrid. This email is to confirm that we have processed your order -order_id-. You can download your invoice as a PDF for your records."
_17
}
_17
}


_70
{
_70
"personalizations": [
_70
{
_70
"to": [
_70
{
_70
"email": "john@domain.com",
_70
"name": "John"
_70
}
_70
],
_70
"subject": "Example 01",
_70
"substitutions": {
_70
"-name-": "John",
_70
"-order_id-": "12345",
_70
"-confirmations-": "-confirmation_001-"
_70
}
_70
},
_70
{
_70
"to": [
_70
{
_70
"email": "jane@domain.com",
_70
"name": "Jane"
_70
}
_70
],
_70
"subject": "Example 02",
_70
"substitutions": {
_70
"-name-": "Jane",
_70
"-order_id-": "23456",
_70
"-confirmations-": "-confirmation_002-"
_70
}
_70
},
_70
{
_70
"to": [
_70
{
_70
"email": "matt@domain.com",
_70
"name": "Matt"
_70
}
_70
],
_70
"subject": "Example 03",
_70
"substitutions": {
_70
"-name-": "Matt",
_70
"-order_id-": "34567",
_70
"-confirmations-": "-confirmation_003-"
_70
}
_70
}
_70
],
_70
"from": {
_70
"email": "sender@senddomain.com",
_70
"name": "Sender"
_70
},
_70
"reply_to": {
_70
"email": "sender@senddomain.com",
_70
"name": "Sender"
_70
},
_70
"subject": "Example",
_70
"content": [
_70
{
_70
"type": "text/plain",
_70
"value": "Hello -name-,\n-confirmations-"
_70
},
_70
{
_70
"type": "text/html",
_70
"value": "<html>\n <head></head>\n <body>\n <p>Hello -name-, \n -confirmations-</p>\n </body>\n</html>"
_70
}
_70
],
_70
"sections": {
_70
"-confirmation_001-": "Thanks for choosing SendGrid. This email is to confirm that we have processed your order -order_id-.",
_70
"-confirmation_002-": "Thanks for choosing SendGrid. This email is to confirm that we have processed your order -order_id-. This invoice is to be paid by bank transfer within 7 days from the date of your monthly statement.",
_70
"-confirmation_003-": "Thanks for choosing SendGrid. This email is to confirm that we have processed your order -order_id-. You can download your invoice as a PDF for your records."
_70
}
_70
}

john@domain.com


_10
Welcome John,
_10
Thanks for choosing SendGrid. This email is to confirm that we have processed your order 12345.


_10
<html>
_10
<head></head>
_10
<body>
_10
<p>
_10
Welcome John,<br />
_10
Thanks for choosing SendGrid. This email is to confirm that we have
_10
processed your order 12345.
_10
</p>
_10
</body>
_10
</html>


_10
jane@domain.com


_10
Hello Jane,
_10
Thanks for choosing SendGrid. This email is to confirm that we have processed your order 23456. This invoice is to be paid by bank transfer within 7 days from the date of your monthly statement.


_11
<html>
_11
<head></head>
_11
<body>
_11
<p>
_11
Hello Jane,<br />
_11
Thanks for choosing SendGrid. This email is to confirm that we have
_11
processed your order 23456. This invoice is to be paid by bank transfer
_11
within 7 days from the date of your monthly statement.
_11
</p>
_11
</body>
_11
</html>

matt@domain.com


_10
Dear Matt,
_10
Thanks for choosing SendGrid. This email is to confirm that we have processed your order 34567. You can download your invoice as a PDF for your records.


_11
<html>
_11
<head></head>
_11
<body>
_11
<p>
_11
Dear Matt,<br />
_11
Thanks for choosing SendGrid. This email is to confirm that we have
_11
processed your order 34567. You can download your invoice as a PDF for
_11
your records.
_11
</p>
_11
</body>
_11
</html>


Rate this page: