Skip to content Skip to navigation Skip to topbar

On this page

Using Handlebars

Twilio SendGrid Dynamic Transactional Templates and Marketing Campaigns designs support the Handlebars templating language to render the Personalizations you send via the API and the Substitution Tags stored on your Marketing Campaigns contacts.

Handlebars syntax allows you to personalize the messages in your templates by inserting customers' names and other data to make an email relevant to each individual recipient. For example, if you have a customer's name stored in a JSON property called "name", you can insert the property's value into a template by adding {{ name }} wherever you want the customer's name to appear.

Handlebars syntax allows all of this dynamic templating to occur outside of your code base, meaning changes are done quickly in the template with no update to a code base required.

(information)

Info

If you prefer to use your own templating system, you can still insert dynamic data using Substitution Tags.

Personalizing email with Handlebars

(information)

Info

You can manage your templates programmatically with our Mail Send with Dynamic Transactional Templates API.

The Handlebars language provides many features in addition to basic variable replacement, including iterations (loops) and conditional statements. Our templates and designs support most but not all of this Handlebars functionality. Currently, dynamic templates support the following helpers:

For a full helper reference, see the Handlebars reference on this page.

Use cases

The following use case examples come from the dynamic-template section of our email templates GitHub repo. Each example links to files you can explore on GitHub. You can also work with these templates by uploading them using the Code Editor available in Dynamic Transactional Templates and the Marketing Campaigns Design Library.

The following use cases are listed with the Handlebars helpers used to build them.

Receipt

This example receipt template uses the following helpers:

Password reset

This example transactional template uses the following helpers:

Substitution

Multiple languages

This is an example template that lets you have content in multiple languages, and it uses the following helpers:

Conditional statements - if/else

This is an example template that is advertising items on sale, and it uses the following helpers:

Handlebars reference

The following reference provides sample code blocks for each helper, including HTML email snippets and JSON test data. The code examples are shown in three tabs. The first tab, Handlebars, shows the Handlebars tag. The second tab, JSON, shows example data that would be used to populate the Handlebars tag. The third tab, HTML, shows the final output that the Handlebars tag will be rendered to in your email. You can click each tab to switch between the code samples.

Substitution

Twilio SendGrid templates support the following substitutions:

Basic replacement

1<!-- Template -->
2<p>Hello {{ firstName }}</p>

1// Test data
2{ "firstName": "Ben" }

1<!-- Resulting HTML !-->
2<p>Hello Ben</p>

Dynamic link values

1<!-- Template -->
2<p><a href="{{ url }}">Click Me</a></p>

1// Test data
2{ "url": "https://example.com/shop" }

1<!-- Resulting HTML !-->
2<p><a href="https://example.com/shop">Click Me</a></p>

Deep object replacement

1<!-- Template -->
2<p>Hello {{user.profile.firstName}}</p>

1// Test data
2{
3  "user": {
4    "profile": {
5      "firstName": "Ben"
6    }
7  }
8}

1<!-- Resulting HTML -->
2<p>Hello Ben</p>

Object failure

1<!-- Template -->
2<p>Hello {{user.profile.firstName}}</p>

1// Test data
2{
3  "user": {
4    "orderHistory": [
5      {
6        "date": "2/1/2018",
7        "item": "shoes"
8      },
9      {
10        "date": "1/4/2017",
11        "item": "hat"
12      }
13    ]
14  }
15}

1<!-- Resulting HTML -->
2<p>Hello</p>

Replacement with HTML

(information)

Info

If you include the characters ', " or & in a subject line replacement be sure to use three brackets like below.

1<!-- Template -->
2<!-- Per Handlebars' documentation: If you don't want Handlebars to escape a value, use the "triple-stash", {{{ -->
3<p>Hello {{{firstName}}}</p>

1// Test data
2{ "firstName": "<strong>Ben</strong>" }

1<!-- Resulting HTML -->
2<p>Hello <strong>Ben</strong></p>

formatDate

The formatDate helper takes a time in either epoch or ISO8601 format and converts it to a format you specify using the tokens in the following table. If you send a date field without converting it, it will be displayed in ISO8601 format with the full timestamp (e.g., 2020-01-01T23:00:00.000Z). The following example display results are for Tuesday, January 1st, 2020 3:00:00PM Pacific Standard Time.

Token	Displayed Result
YYYY	2020
YY	20
MMMM	January
MMM	Jan
MM	01
M	1
DD	01
D	1
dddd	Tuesday
ddd	Tue
hh	03
h	3
HH	00
H	00
mm	00
m	0
ss	00
s	0
A	PM
ZZ	-0800
Z	-08:00

1<!-- Template without timezone offset -->
2<p>Join us {{formatDate timeStamp dateFormat}}</p>
3
4<!-- Template with timezone offset -->
5<p>Join us {{formatDate timeStamp dateFormat timezoneOffset}}</p>

1// Test data
2{
3  "timeStamp": "2020-01-01T23:00:00.000Z",
4  "dateFormat": "MMMM DD, YYYY h:mm:ss A",
5  "timezoneOffset": "-0800"
6}

1<!-- Resulting HTML without timezone-->
2<p>Join us January 01, 2020 11:00:00 PM</p>
3
4<!-- Resulting HTML with timezone-->
5<p>Join us January 01, 2020 3:00:00 PM</p>

Insert

1<!-- Insert with a default value -->
2<p>Hello {{insert name "default=Customer"}}! Thank you for contacting us about {{insert businessName "your business"}}.</p>

1// Test data with all values
2{
3   "name": "Ben",
4   "businessName": "Twilio SendGrid"
5}
6
7// Test data with missing value
8{
9  "name": "Ben"
10}

1<!-- Resulting HTML with all values -->
2<p>Hello Ben! Thank you for contacting us about Twilio SendGrid.</p>
3
4<!-- Resulting HTML with missing value and a default-->
5<p>Hello Ben! Thank you for contacting us about your business.</p>

Conditional statements

Twilio SendGrid templates support the following conditionals:

Basic If, Else, Else If

1<!-- Template -->
2{{#if user.profile.male}}
3   <p>Dear Sir</p>
4{{else if user.profile.female}}
5   <p>Dear Madame</p>
6{{else}}
7   <p>Dear Customer</p>
8{{/if}}

1// Test data one
2{
3   "user":{
4      "profile":{
5         "male":true
6      }
7   }
8}
9
10// Test data two
11{
12   "user":{
13      "profile":{
14         "female":true
15      }
16   }
17}
18
19// Test data three
20{
21   "user":{
22      "profile":{
23
24      }
25   }
26}

1<!-- Resulting HTML from test data one -->
2<p>Dear Sir</p>
3
4<!-- Resulting HTML from test data two -->
5<p>Dear Madame</p>
6
7<!-- Resulting HTML from test data three -->
8<p>Dear Customer</p>

If with a root

1<!-- Template -->
2{{#if user.suspended}}
3   <p>Warning! Your account is suspended, please call: {{@root.supportPhone}}</p>
4{{/if}}

1// Test data
2{
3  "user": {
4    "suspended": true
5  },
6  "supportPhone": "1-800-555-5555"
7}

1<!-- Resulting HTML -->
2<p>Warning! Your account is suspended, please call: 1-800-555-5555</p>

Unless

1<!-- Template -->
2{{#unless user.active}}
3   <p>Warning! Your account is suspended, please call: {{@root.supportPhone}}</p>
4{{/unless}}

1// Test data
2{
3  "user": {
4    "active": false
5  },
6  "supportPhone": "1-800-555-5555"
7}

1<!-- Resulting HTML -->
2<p>Warning! Your account is suspended, please call: 1800-555-5555</p>

greaterThan

Basic greaterThan

1<!-- Template -->
2<p>
3Hello Ben!
4{{#greaterThan scoreOne scoreTwo}}
5    Congratulations, you have the high score today!
6{{/greaterThan}}
7 Thanks for playing.
8</p>

1// Test data one
2{
3  "scoreOne": 100,
4  "scoreTwo": 78
5}
6
7// Test data two
8{
9  "scoreOne": 55,
10  "scoreTwo": 78
11}

1<!-- Resulting HTML from test data one-->
2<p>
3  Hello Ben! Congratulations, you have the high score today! Thanks for playing.
4</p>
5
6<!-- Resulting HTML from test data two-->
7<p>Hello Ben! Thanks for playing.</p>

greaterThan with else

1<!-- Template -->
2<p>
3Hello Ben!
4{{#greaterThan scoreOne scoreTwo}}
5    Congratulations, you have the high score today!
6{{else}}
7    You were close, but you didn't get the high score today.
8{{/greaterThan}}
9 Thanks for playing.
10</p>

1// Test data one
2{
3  "scoreOne": 100,
4  "scoreTwo": 78
5}
6
7// Test data two
8{
9  "scoreOne": 55,
10  "scoreTwo": 78
11}

1<!-- Resulting HTML from test data one-->
2<p>
3  Hello Ben! Congratulations, you have the high score today! Thanks for playing.
4</p>
5
6<!-- Resulting HTML from test data two-->
7<p>
8  Hello Ben! You were close, but you didn't get the high score today. Thanks for
9  playing.
10</p>

lessThan

Basic lessThan

1<!-- Template -->
2<p>
3Hello Ben!
4{{#lessThan scoreOne scoreTwo}}
5    You were close, but you didn't get the high score today.
6{{/lessThan}}
7 Thanks for playing.
8</p>

1// Test data one
2{
3  "scoreOne": 55,
4  "scoreTwo": 78
5}
6
7// Test data two
8{
9  "scoreOne": 100,
10  "scoreTwo": 78
11}

1<!-- Resulting HTML from test data one-->
2<p>
3  Hello Ben! You were close, but you didn't get the high score today. Thanks for
4  playing.
5</p>
6
7<!-- Resulting HTML from test data two-->
8<p>Hello Ben! Thanks for playing.</p>

lessThan with else

1<!-- Template -->
2<p>
3Hello Ben!
4{{#lessThan scoreOne scoreTwo}}
5    You were close, but you didn't get the high score today.
6{{else}}
7    Congratulations, you have the high score today!
8{{/lessThan}}
9 Thanks for playing.
10</p>

1// Test data one
2{
3  "scoreOne": 55,
4  "scoreTwo": 78
5}
6
7// Test data two
8{
9  "scoreOne": 100,
10  "scoreTwo": 78
11}

1<!-- Resulting HTML from test data one-->
2<p>
3  Hello Ben! You were close, but you didn't get the high score today. Thanks for
4  playing.
5</p>
6
7<!-- Resulting HTML from test data two-->
8<p>
9  Hello Ben! Congratulations, you have the high score today! Thanks for playing.
10</p>

Equals

The equals comparison can check for equality between two values of the same data type. The equals helper will also attempt to coerce data types to make a comparison of values independent of their data type. For example, {{#equals 3 "3"}} will evaluate to true.

(error)

Danger

Please be aware that the editor's Preview page will not properly render the results of a comparison between coerced values. You will see proper comparisons between coerced values only in a delivered message.

When checking for truthiness, be aware that empty strings, zero integers, and zero floating point numbers evaluate to false. Non-empty strings, non-zero integers, and non-zero floating point numbers, including negative numbers, evaluate to true.

Basic equals

1<!-- Template -->
2<p>
3Hello Ben!
4{{#equals customerCode winningCode}}
5    You have a winning code.
6{{/equals}}
7 Thanks for playing.
8</p>

1// Test data one
2{
3  "customerCode": 289199,
4  "winningCode": 289199
5}
6
7// Test data two
8{
9  "customerCode": 167320,
10  "winningCode": 289199
11}

1<!-- Resulting HTML from test data one-->
2<p>Hello Ben! You have a winning code. Thanks for playing.</p>
3
4<!-- Resulting HTML from test data two-->
5<p>Hello Ben! Thanks for playing.</p>

Equals with else

1<!-- Template -->
2<p>
3Hello Ben!
4{{#equals customerCode winningCode}}
5    You have a winning code.
6{{else}}
7    You do not have a winning code.
8{{/equals}}
9 Thanks for playing.
10</p>

1// Test data one
2{
3  "customerCode": 289199,
4  "winningCode": 289199
5}
6
7// Test data two
8{
9  "customerCode": 167320,
10  "winningCode": 289199
11}

1<!-- Resulting HTML from test data one-->
2<p>Hello Ben! You have a winning code. Thanks for playing.</p>
3
4<!-- Resulting HTML from test data two-->
5<p>Hello Ben! You do not have a winning code. Thanks for playing.</p>

notEquals

The notEquals comparison can check for inequality between two values of the same data type. The notEquals helper will also attempt to coerce data types to make a comparison of values independent of their data type. For example, {{#notequals 3 "3"}} will return true.

Basic notEquals

1<!-- Template -->
2<p>
3Hello Ben!
4{{#notEquals currentDate appointmentDate}}
5    Your appointment is not today.
6{{/notEquals}}
7 We look forward to your visit.
8</p>

1// Test data one
2{
3  "currentDate": 20230715,
4  "appointmentDate": 20230715
5}
6
7// Test data two
8{
9  "currentDate": 20230710,
10  "appointmentDate": 20230715
11}

1<!-- Resulting HTML from test data one-->
2<p>Hello Ben! We look forward to your visit.</p>
3
4<!-- Resulting HTML from test data two-->
5<p>Hello Ben! Your appointment is not today. We look forward to your visit.</p>

notEquals with else

1<!-- Template -->
2<p>
3Hello Ben!
4{{#notEquals currentDate appointmentDate}}
5    Your appointment is not today.
6{{else}}
7    Your appointment is today.
8{{/notEquals}}
9 We look forward to your visit.
10</p>

1// Test data one
2{
3  "currentDate": 20230715,
4  "appointmentDate": 20230715
5}
6
7// Test data two
8{
9  "currentDate": 20230710,
10  "appointmentDate": 20230715
11}

1<!-- Resulting HTML from test data one-->
2<p>Hello Ben! Your appointment is today. We look forward to your visit.</p>
3
4<!-- Resulting HTML from test data two-->
5<p>Hello Ben! Your appointment is not today. We look forward to your visit.</p>

And

And without else

1<!-- Template -->
2<p>
3Hello Ben!
4{{#and favoriteFood favoriteDrink}}
5   Thank you for letting us know your dining preferences.
6{{/and}}.
7 We look forward to sending you more delicious recipes.</p>

1// Test data one
2{
3  "favoriteFood": "Pasta",
4  "favoriteDrink": ""
5}
6
7// Test data two
8{
9  "favoriteFood": "Pasta",
10  "favoriteDrink": "Coffee"
11}

1<!-- Resulting HTML from test data one -->
2<p>Hi Ben! We look forward to sending you more delicious recipes.</p>
3
4<!-- Resulting HTML from test data two -->
5<p>
6  Hi Ben! Thank you for letting us know your dining preferences. We look forward
7  to sending you more delicious recipes.
8</p>

And with else

1<!-- Template -->
2<p>
3Hello Ben!
4{{#and favoriteFood favoriteDrink}}
5   Thank you for letting us know your dining preferences.
6{{else}}
7   If you finish filling out your dining preferences survey, we can deliver you recipes we think you'll be most interested in.
8{{/and}}.
9 We look forward to sending you more delicious recipes.</p>

1// Test data one
2{
3  "favoriteFood": "Pasta",
4  "favoriteDrink": ""
5}
6
7// Test data two
8{
9  "favoriteFood": "Pasta",
10  "favoriteDrink": "Coffee"
11}

1<!-- Resulting HTML from test data one -->
2<p>
3  Hi Ben! If you finish filling out your dining preferences survey, we can
4  deliver you recipes we think you'll be most interested in. We look forward to
5  sending you more delicious recipes.
6</p>
7
8<!-- Resulting HTML from test data two -->
9<p>
10  Hi Ben! Thank you for letting us know your dining preferences. We look forward
11  to sending you more delicious recipes.
12</p>

Or

Basic or

1<!-- Template -->
2<p>
3Hello Ben!
4{{#or isRunner isCyclist}}
5   We think you might enjoy a map of trails in your area.
6{{/or}}.
7 Have a great day.
8</p>

1// Test data one
2{
3  "isRunner": true,
4  "isCyclist": false
5}
6
7// Test data two
8{
9  "isRunner": false,
10  "isCyclist": false
11}
12// Test data three
13{
14  "isRunner": false,
15  "isCyclist": true
16}

1<!-- Resulting HTML from test data one -->
2<p>
3  Hi Ben! We think you might enjoy a map of trails in your area. You can find
4  the map attached to this email. Have a great day.
5</p>
6
7<!-- Resulting HTML from test data two -->
8<p>Hi Ben! Have a great day.</p>
9
10<!-- Resulting HTML from test data three -->
11<p>
12  Hi Ben! We think you might enjoy a map of trails in your area. You can find
13  the map attached to this email. Have a great day.
14</p>

Or with else

1<!-- Template -->
2<p>
3Hello Ben!
4{{#or isRunner isCyclist}}
5   We think you might enjoy a map of trails in your area. You can find the map attached to this email.
6{{else}}
7   We'd love to know more about the outdoor activities you enjoy. The survey linked below will take only a minute to fill out.
8{{/or}}.
9 Have a great day.
10</p>

1// Test data one
2{
3  "isRunner": true,
4  "isCyclist": false
5}
6
7// Test data two
8{
9  "isRunner": false,
10  "isCyclist": false
11}
12// Test data three
13{
14  "isRunner": false,
15  "isCyclist": true
16}

1<!-- Resulting HTML from test data one -->
2<p>
3  Hi Ben! We think you might enjoy a map of trails in your area. You can find
4  the map attached to this email. Have a great day.
5</p>
6
7<!-- Resulting HTML from test data two -->
8<p>
9  Hi Ben! We'd love to know more about the outdoor activities you enjoy. The
10  survey linked below will take only a minute to fill out. Have a great day.
11</p>
12
13<!-- Resulting HTML from test data three -->
14<p>
15  Hi Ben! We think you might enjoy a map of trails in your area. You can find
16  the map attached to this email. Have a great day.
17</p>

Length

The length helper will return the number of characters in a given string or array. For non-string and non-array values, length will return 0. Length can be useful in combination with other helpers as shown with greaterThan in the following example.

1<!-- Templates -->
2<p>
3Hello Ben!
4{{#greaterThan (length cartItems) 0}}
5 It looks like you still have some items in your shopping cart. Sign back in to continue checking out at any time.
6{{else}}
7 Thanks for browsing our site. We hope you'll come back soon.
8{{/greaterThan}}
9</p>

1// Test data one
2{
3  "cartItems": ["raft", "water bottle", "sleeping bag"]
4}
5
6// Test data two
7{
8  "cartItems": []
9}

1<!-- Resulting HTML with test data one-->
2<p>
3  Hello Ben! It looks like you still have some items in your shopping cart. Sign
4  back in to continue checking out at any time.
5</p>
6
7<!-- Resulting HTML with test data two-->
8<p>Hello Ben! Thanks for browsing our site. We hope you'll come back soon.</p>

Iterations

You can loop or iterate over data using the {{#each }} helper function to build lists and perform other useful templating actions.

Basic Iterator with each

1<!-- Template -->
2<ol>
3  {{#each user.orderHistory}}
4   <li>You ordered: {{this.item}} on: {{this.date}}</li>
5  {{/each}}
6</ol>

1// Test data
2{
3  "user": {
4    "orderHistory": [
5      {
6        "date": "2/1/2018",
7        "item": "shoes"
8      },
9      {
10        "date": "1/4/2017",
11        "item": "hat"
12      }
13    ]
14  }
15}

1<!-- Resulting HTML -->
2<ol>
3  <li>You ordered: shoes on: 2/1/2018</li>
4  <li>You ordered: hat on: 1/42017</li>
5</ol>

Combined examples

The following examples show you how to combine multiple Handlebars functions to create a truly dynamic template.

Dynamic content creation

1<!-- Template -->
2{{#each user.story}}
3   {{#if this.male}}
4      <p>{{this.date}}</p>
5   {{else if this.female}}
6      <p>{{this.item}}</p>
7   {{/if}}
8{{/each}}

1// Test data
2{
3  "user": {
4    "story": [
5      {
6        "male": true,
7        "date": "2/1/2018",
8        "item": "shoes"
9      },
10      {
11        "male": true,
12        "date": "1/4/2017",
13        "item": "hat"
14      },
15      {
16        "female": true,
17        "date": "1/1/2016",
18        "item": "shirt"
19      }
20    ]
21  }
22}

1<!-- Resulting HTML -->
2<p>2/1/2018</p>
3<p>1/4/2017</p>
4<p>shirt</p>

Dynamic content creation with dynamic parts 1

1<!-- Template -->
2{{#each user.story}}
3   {{#if this.male}}
4      {{#if this.date}}
5         <p>{{this.date}}</p>
6      {{/if}}
7      {{#if this.item}}
8         <p>{{this.item}}</p>
9      {{/if}}
10   {{else if this.female}}
11      {{#if this.date}}
12         <p>{{this.date}}</p>
13      {{/if}}
14      {{#if this.item}}
15         <p>{{this.item}}</p>
16      {{/if}}
17   {{/if}}
18{{/each}}

1// Test data
2{
3  "user": {
4    "story": [
5      {
6        "male": true,
7        "date": "2/1/2018",
8        "item": "shoes"
9      },
10      {
11        "male": true,
12        "date": "1/4/2017"
13      },
14      {
15        "female": true,
16        "item": "shirt"
17      }
18    ]
19  }
20}

1<!-- Resulting HTML -->
2<p>2/1/2018</p>
3<p>shoes</p>
4<p>1/4/2017</p>
5<p>shirt</p>

Dynamic content creation with dynamic parts 2

1<!-- Template -->
2{{#if people}}
3   <p>People:</p>
4   {{#each people}}
5      <p>{{this.name}}</p>
6   {{/each}}
7{{/if}}

1// Test data
2{
3  "people": [{ "name": "Bob" }, { "name": "Sally" }]
4}

1<!-- Resulting HTML -->
2<p>People:</p>
3<p>Bob</p>
4<p>Sally</p>

Using Handlebars

Info

Personalizing email with Handlebars

Info

Use cases

Receipt

Password reset

Multiple languages

Newsletter

Advertisement

Handlebars reference

Substitution

Basic replacement

Dynamic link values

Deep object replacement

Object failure

Replacement with HTML

Info

formatDate

Insert

Conditional statements

Basic If, Else, Else If

If with a root

Unless

greaterThan

Basic greaterThan

greaterThan with else

lessThan

Basic lessThan

lessThan with else

Equals

Danger

Basic equals

Equals with else

notEquals

Basic notEquals

notEquals with else

And

And without else

And with else

Or

Basic or

Or with else

Length

Iterations

Basic Iterator with each

Combined examples

Dynamic content creation

Dynamic content creation with dynamic parts 1

Dynamic content creation with dynamic parts 2

Additional Resources