- A template is a container; versions are the emails
- Creating the template
- Designing a version
- Making it dynamic with Handlebars
- An order confirmation, as an example
- Nothing sends until a version is active
- Sending with the Mail Send API
- Templates in Mailgun and Brevo
- My advice for your first dynamic template
- Frequently asked questions
In SendGrid, go to Email API, Dynamic Templates, click Create a Dynamic Template, name it and click Create. Then open the template, click Add Version, pick a starting design and the Design Editor or Code Editor, add Handlebars variables, save, and click Make Active. Only then will it send.
A template is a container; versions are the emails
Here's the idea that makes SendGrid's dynamic templates click. The template itself doesn't hold anything to send. Inside it you create one or more versions, and the active version is the email that goes out. That lets you keep an old design while you build a new one, then switch with one click.
Creating the template
- Log in and go to Email API > Dynamic Templates.
- Click Create a Dynamic Template, type a name in the Dynamic Template Name field and click Create.
The new template appears in the Template list. Click it to see its Template ID, its versions and the Add Version button. If you get an error at this point, you might have reached your template limit.
Designing a version
- Click the template name, then Add Version.
- Choose the Your Email Designs or SendGrid Email Designs tab and pick a starting template.
- Choose the Design Editor, a visual interface, or the Code Editor, a text editor for HTML.
- Set the Version Name, and optionally a Subject and Preheader, which can also be set when you send.
In the Design Editor, the Build tab gives you Add Modules, Global Styles and Advanced, where you can import or export HTML and change values in the HTML head. If you've got a designer, the Code Editor lets them paste in finished HTML.
Making it dynamic with Handlebars
SendGrid supports the Handlebars templating language in the text, the HTML and the subject line, so you can drop in personal details such as a first name or an order number. Include an unsubscribe module too, and choose which unsubscribe group accepts unsubscribes from this template. Then save, and you've got a dynamic version.
If you need ideas, SendGrid provides sample dynamic templates on GitHub for receipts, password resets, account activations, newsletters and sale notifications.
An order confirmation, as an example
Say you want a receipt email from your shop. In the Code Editor or the Design Editor, you'd write a greeting with a first-name variable, a line with the order number variable, and a short list of items. The subject could use the order number too, such as 'Your order' followed by the number. In the API call, your developer sends those same names inside dynamic_template_data, and each customer gets their own details in the same design. Start from SendGrid's sample receipt on GitHub and you'll have most of the layout done.
Nothing sends until a version is active
The Twilio SendGrid Docs flag the step people miss. A template is only a container, and nothing sends until a version is set as active. Open the template's version list, click the three bullet icon on the version you want, and click Make Active. The personalisation data also has to arrive in the right place in your API call, or your variables will come out blank.
Sending with the Mail Send API
Copy the Template ID. It starts with d- followed by 62 hexadecimal characters. Your developer then calls the Mail Send REST API with that ID and puts the personal data inside personalizations.dynamic_template_data. Each key in that data matches a Handlebars variable in your design, so it's worth agreeing the names up front.
| In the template | In the API call |
|---|---|
| Handlebars variable such as a first name | A matching key in dynamic_template_data |
| Subject left blank in the version | Subject set at send time |
| The active version | Chosen automatically by the template ID |
Before you send to real customers, check the email reaches the inbox. My email deliverability checklist covers the settings that matter.
Templates in Mailgun and Brevo
Mailgun's templates page covers HTML email templates for blast, newsletter and transactional email.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
Brevo's marketing automation page offers premade templates or a drag-and-drop editor to build your own. For a head to head on sending platforms, see my comparison of SendGrid and Mailgun.
My advice for your first dynamic template
Start from one of SendGrid's sample designs, keep variables to the two or three you need, and send yourself a test with real data before you make it active. Name versions clearly so you know which is live, and keep the Template ID somewhere your developer can find it.
Want your tool on this list? Featured spots and reviews here are paid partnerships. Here's how to partner with me.
Frequently asked questions
Where do I create a dynamic template in SendGrid?
Email API > Dynamic Templates > Create a Dynamic Template.
What templating language does it use?
Handlebars.
What are versions?
Each template can have several versions. Only the active one is used.
How do I send with it?
Call the Mail Send API with the template ID and dynamic_template_data.
What does the template ID look like?
It starts with d- followed by 62 hexadecimal characters.
