How to Send an Email with Dynamic Templates

Before you begin, complete the following tasks:

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

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

Twilio SendGrid allows multiple versions of a dynamic template. Each version might offer different content on the same theme. This splits the process for creating dynamic templates into creating the dynamic template and creating a version of that dynamic template.

As a component, a dynamic templates provides a unique ID to the Mail APIs.

1. Log in to the Twilio SendGrid app.
2. Go the Dynamic Templates page.
3. Click Create a Dynamic Template.
4. Type a human-readable name into the Dynamic Template Name field.
5. Click Create.
   • The Dynamic Templates page displyas your template in the Template list.
   • If you click the name of a dynamic template, a panel displays with the Template ID number, a list of template versions, and the Add Version button.

To begin editing your created template, complete the following steps.

1. Log in to the Twilio SendGrid app.
2. Go the Dynamic Templates page.
3. Click the name of the template you want to design.
   The details of the template display.
4. Click Add Version.
5. Click either the Your Email Designs or the SendGrid Email Designs tab.
6. Hover over the desired starting template and click Select.
7. To modify the starting template, click Select for either the Design Editor or Code Editor.
   • The Design Editor provides a visual interface for building email templates.
   • The Code Editor provides a text editor for modifying HTML code.
8. Complete the settings for this version:
   • Add a human-readable label for this version in the Version Name box.
   • Add a subject line for your email in the Subject box. This is optional. You can set a subject line when sending the email.
   • Add an extended preview of your email in the Preheader box. This is also optional and can be set when you send your email.
9. Click the Build tab.
   The Design Editor provides three main features:
   • Add Modules: Drag and drop, then customize pre-built components into your email template.
   • Global Styles: Set the broad design of your email body and content container of your email template. These settings include:
     • Colors and fonts in the Email Body section, and
     • Width of the email content box and background color outside that box in the Content Container section.
   • Advanced: Import or export HTML and change the HTML head values.
10. Design your template.
    You can include personalization variables into your dynamic template. Twilio SendGrid supports the Handlebars templating language for the text, HTML, and subject lines of your template. Learn how to use Handlebars.
11. Include an unsubscribe module.
    1. Drag the Unsubscribe module into your email template.
    2. Change its formatting settings as needed.
    3. Choose which unsubscribe group should accept unsubscribes from this template in the Unsubscribe Group dropdown menu.
12. Whenever you want to save progress on your template, click Save in the top navigation.
13. When finished, click the left arrow icon in the top navigation.
14. Click the name of the template you last saved to open the version list for that template.
15. To set a specific version of the template as active, click Make Active from the three bullet icon at the right of the template.

To use sample templates, see the dynamic-template directory in the Twilio SendGrid email-template GitHub repo. These samples include receipts, password resets, account activations, newsletters, and sale notifications.

To send mail using Dynamic Templates, use the Mail Send REST API resource. The API requests on this page use cURL with the receipt example template.

Add your dynamic content, the Handlebars variable values, to the data payload of your API request.

• The payload accepts a JSON document.
• Add the dynamic data that your template uses into the dynamic_template_data object. The previous example highlights those lines for you.
• Include the template ID for your dynamic template in the JSON body data.
  • The template ID starts with d- followed by 62 hexadecimal characters.
  • If you forget your template ID, find it in one of two ways:

    • Call the templates resource.

      Display the find all dynamic templates API

    • Log in to Twilio SendGrid app then go to the Dynamic Templates page. Click the name of the template. The template ID displays under the template name.

Using the previous cURL command, you could customize your template in the following ways.

1. Insert the person's name.
   Copy code block

   <div>Hello {{name}}!</div>

2. Loop through the list of items ordered.
   Copy code block

   1
   {{#list items}}
   2
   {{image}} {{text}} {{price}}
   3
   {{/list}}

3. Add a condition.
   Copy code block

   1
   {{#with name}}
   2
   <div>Hello {{name}}!</div>
   3
   {{/with}}

The Handlebars variables point to JSON keys in your JSON payload.

• Mail Send with Dynamic Templates
• Unsubscribe Groups
• Using Handlebars