How to Send an Email with Dynamic Templates

Before you begin

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)

Design a dynamic template

Open the Dynamic Templates page and click Create Template.
Add a unique template name and then click Save.
To begin editing your new template, click Add Version.
Select an editor and click Continue.
Design your template. For more information on using Handlebars, see Using Handlebars.
Set the template to Active to enable sending.

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.

Unsubscribe modules for dynamic templates

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.

The cURL calls on this page use the receipt example template.

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

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:

curl -X "POST" "https://api.sendgrid.com/v3/mail/send" \
     -H 'Authorization: Bearer <<YOUR_API_KEY>>' \
     -H 'Content-Type: application/json' \
     -d '{
   "from":{
      "email":"example@.sendgrid.net"
   },
   "personalizations":[
      {
         "to":[
            {
               "email":"example@sendgrid.net"
            }
         ],
         "dynamic_template_data":{
            "total":"$ 239.85",
            "items":[
               {
                  "text":"New Line Sneakers",
                  "image":"https://marketing-image-production.s3.amazonaws.com/uploads/8dda1131320a6d978b515cc04ed479df259a458d5d45d58b6b381cae0bf9588113e80ef912f69e8c4cc1ef1a0297e8eefdb7b270064cc046b79a44e21b811802.png",
                  "price":"$ 79.95"
               },
               {
                  "text":"Old Line Sneakers",
                  "image":"https://marketing-image-production.s3.amazonaws.com/uploads/3629f54390ead663d4eb7c53702e492de63299d7c5f7239efdc693b09b9b28c82c924225dcd8dcb65732d5ca7b7b753c5f17e056405bbd4596e4e63a96ae5018.png",
                  "price":"$ 79.95"
               },
               {
                  "text":"Blue Line Sneakers",
                  "image":"https://marketing-image-production.s3.amazonaws.com/uploads/00731ed18eff0ad5da890d876c456c3124a4e44cb48196533e9b95fb2b959b7194c2dc7637b788341d1ff4f88d1dc88e23f7e3704726d313c57f350911dd2bd0.png",
                  "price":"$ 79.95"
               }
            ],
            "receipt":true,
            "name":"Sample Name",
            "address01":"1234 Fake St.",
            "address02":"Apt. 123",
            "city":"Place",
            "state":"CO",
            "zip":"80202"
          }
      }
   ],
   "template_id":"[template_id]"
}'

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.

         "dynamic_template_data":{
            "total":"$ 239.85",
            "items":[
               {
                  "text":"New Line Sneakers",
                  "image":"https://marketing-image-production.s3.amazonaws.com/uploads/8dda1131320a6d978b515cc04ed479df259a458d5d45d58b6b381cae0bf9588113e80ef912f69e8c4cc1ef1a0297e8eefdb7b270064cc046b79a44e21b811802.png",
                  "price":"$ 79.95"
               },
               {
                  "text":"Old Line Sneakers",
                  "image":"https://marketing-image-production.s3.amazonaws.com/uploads/3629f54390ead663d4eb7c53702e492de63299d7c5f7239efdc693b09b9b28c82c924225dcd8dcb65732d5ca7b7b753c5f17e056405bbd4596e4e63a96ae5018.png",
                  "price":"$ 79.95"
               },
               {
                  "text":"Blue Line Sneakers",
                  "image":"https://marketing-image-production.s3.amazonaws.com/uploads/00731ed18eff0ad5da890d876c456c3124a4e44cb48196533e9b95fb2b959b7194c2dc7637b788341d1ff4f88d1dc88e23f7e3704726d313c57f350911dd2bd0.png",
                  "price":"$ 79.95"
               }
            ],
            "receipt":true,
            "name":"Sample Name",
            "address01":"1234 Fake St.",
            "address02":"Apt. 123",
            "city":"Place",
            "state":"CO",
            "zip":"80202"
         }

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:

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

For legacy templates:

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

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

Additional Resources

Need some help?

We all do sometimes. Get help now from the Twilio SendGrid Support Team.

Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.