Skip to contentSkip to navigationSkip to topbar
On this page

How to Send an Email with Dynamic Templates



Before you begin

before-you-begin page anchor

Before you create and send an email using a dynamic template, you need to do the following:

  • Create a SendGrid account
  • Create an API Key
  • Add an unsubscribe group (optional)
(information)

Info

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


Design a dynamic template

design-a-dynamic-template page anchor
  1. Open the Dynamic Templates(link takes you to an external page) page and click Create Template .
  2. Add a unique template name and then click Save .
  3. To begin editing your new template, click Add Version .
  4. Select an editor and click Continue .
  5. Design your template. For more information on using Handlebars, see Using Handlebars .
  6. Set the template to Active to enable sending.
(information)

Info

After designing your template, it is crucial to set it to Active in order to use it for sending emails. Find the editor template and click Make Active.

Dynamic Template ID.

Unsubscribe modules for dynamic templates

unsubscribe-modules-for-dynamic-templates page anchor

If you want to create a static unsubscribe module for a dynamic template, you can copy the contents of an unsubscribe module into a text module and then replace the sender name and address substitution tags with the desired information or handlebars syntax as shown below.

For sample templates that include examples of receipts, password resets, account activations, newsletters, and sale notifications, check out the dynamic-template section of our email template's GitHub repo(link takes you to an external page).

The cURL calls on this page use the receipt example template(link takes you to an external page).

(error)

Danger

To send mail using Dynamic Templates, you must use the Web API mail.send. SMTP sends do not support Dynamic Templates.


Send a transactional email

send-a-transactional-email page anchor

To send a dynamic transactional email:

In order to send a dynamic transactional email using cURL, set your call up to look something like this:

1
curl -X "POST" "https://api.sendgrid.com/v3/mail/send" \
2
-H 'Authorization: Bearer <<YOUR_API_KEY>>' \
3
-H 'Content-Type: application/json' \
4
-d '{
5
"from":{
6
"email":"example@.sendgrid.net"
7
},
8
"personalizations":[
9
{
10
"to":[
11
{
12
"email":"example@sendgrid.net"
13
}
14
],
15
"dynamic_template_data":{
16
"total":"$ 239.85",
17
"items":[
18
{
19
"text":"New Line Sneakers",
20
"image":"https://marketing-image-production.s3.amazonaws.com/uploads/8dda1131320a6d978b515cc04ed479df259a458d5d45d58b6b381cae0bf9588113e80ef912f69e8c4cc1ef1a0297e8eefdb7b270064cc046b79a44e21b811802.png",
21
"price":"$ 79.95"
22
},
23
{
24
"text":"Old Line Sneakers",
25
"image":"https://marketing-image-production.s3.amazonaws.com/uploads/3629f54390ead663d4eb7c53702e492de63299d7c5f7239efdc693b09b9b28c82c924225dcd8dcb65732d5ca7b7b753c5f17e056405bbd4596e4e63a96ae5018.png",
26
"price":"$ 79.95"
27
},
28
{
29
"text":"Blue Line Sneakers",
30
"image":"https://marketing-image-production.s3.amazonaws.com/uploads/00731ed18eff0ad5da890d876c456c3124a4e44cb48196533e9b95fb2b959b7194c2dc7637b788341d1ff4f88d1dc88e23f7e3704726d313c57f350911dd2bd0.png",
31
"price":"$ 79.95"
32
}
33
],
34
"receipt":true,
35
"name":"Sample Name",
36
"address01":"1234 Fake St.",
37
"address02":"Apt. 123",
38
"city":"Place",
39
"state":"CO",
40
"zip":"80202"
41
}
42
}
43
],
44
"template_id":"[template_id]"
45
}'

It is important to note 2 sections of this call when using dynamic templates:

In order to send dynamic content, you need to specify a JSON blob containing the dynamic data your template will use in the dynamic_template_data object. The Handlebars script you write will refer to the values in your JSON blob by referencing the JSON key, check out these examples. This Handlebars templating can be used in the text, html, and subject lines of your template.

1
"dynamic_template_data":{
2
"total":"$ 239.85",
3
"items":[
4
{
5
"text":"New Line Sneakers",
6
"image":"https://marketing-image-production.s3.amazonaws.com/uploads/8dda1131320a6d978b515cc04ed479df259a458d5d45d58b6b381cae0bf9588113e80ef912f69e8c4cc1ef1a0297e8eefdb7b270064cc046b79a44e21b811802.png",
7
"price":"$ 79.95"
8
},
9
{
10
"text":"Old Line Sneakers",
11
"image":"https://marketing-image-production.s3.amazonaws.com/uploads/3629f54390ead663d4eb7c53702e492de63299d7c5f7239efdc693b09b9b28c82c924225dcd8dcb65732d5ca7b7b753c5f17e056405bbd4596e4e63a96ae5018.png",
12
"price":"$ 79.95"
13
},
14
{
15
"text":"Blue Line Sneakers",
16
"image":"https://marketing-image-production.s3.amazonaws.com/uploads/00731ed18eff0ad5da890d876c456c3124a4e44cb48196533e9b95fb2b959b7194c2dc7637b788341d1ff4f88d1dc88e23f7e3704726d313c57f350911dd2bd0.png",
17
"price":"$ 79.95"
18
}
19
],
20
"receipt":true,
21
"name":"Sample Name",
22
"address01":"1234 Fake St.",
23
"address02":"Apt. 123",
24
"city":"Place",
25
"state":"CO",
26
"zip":"80202"
27
}

In addition to specifying the dynamic template data, you need to specify the template ID. The template ID is 64 characters with one dash (d-uuid). If you forget your template ID and want to access it from the API, use the following curl call to retrieve all of your dynamic templates:

1
curl --request GET \
2
--url 'https://api.sendgrid.com/v3/templates?generations=dynamic' \
3
--header 'Authorization: Bearer <<YOUR_API_KEY>>' \
4
--header 'Content-Type: application/json'

For legacy templates:

1
curl --request GET \
2
--url 'https://api.sendgrid.com/v3/templates?generations=legacy' \
3
--header 'Authorization: Bearer <<YOUR_API_KEY>>' \
4
--header 'Content-Type: application/json'

You can also copy your template ID from the app and paste it into your call.

You can copy your template ID from the app and paste it into your call.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.