How to Send an Email with Dynamic Templates
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)
Info
If you prefer to use your own templating system, you can still insert dynamic data using Substitution Tags.
- 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.
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.
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.
Danger
To send mail using Dynamic Templates, you must use the Web API mail.send. SMTP sends do not support Dynamic Templates.
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:
1curl -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:
1curl --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:
1curl --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.
