What we do
Tools
Industries
Department
How we workLet's talk →
Home/SendGrid/Build a SendGrid Template With Handlebars
SendGrid

How a SendGrid Template Gets Built, Tested and Sent With Dynamic Data

The order confirmation went out as "Hi ," with an empty item table, and SendGrid's activity feed says delivered. A dynamic template is an email stored in SendGrid with Handlebars placeholders in it. Your send names the template's ID and hands over a JSON object of values. Any value that's missing simply renders as nothing, and no error tells you.

SendGrid template in four moves

Create the template and give it a name.

Email API Dynamic Templates Create a Dynamic Template

Add a version: click the template name, choose a starting design, then the Design Editor or Code Editor. Set the subject, save, and choose Make Active.

Add Version

Copy the ID shown under the template's name. It starts with d-.

Send it with POST /v3/mail/send: template_id at the top level, and the values in dynamic_template_data inside each personalization.

What the send request has to carry

A minimal request body has three parts: from, template_id set to your d- ID, and a personalizations array where each entry has its own to and its own dynamic_template_data. That last object is the whole truth the template sees. If the template says {{order.total}}, the object needs an order key with a total inside it.

Because each personalization carries its own data, one request can greet three people by three names. The subject can come from the version's Subject box, and Handlebars works there too, so Order {{order.number}} is on its way is fine. Use triple braces in a subject when the value can contain an apostrophe, a quote or an ampersand, or it arrives escaped.

Lost the ID? GET /v3/templates?generations=dynamic lists your dynamic templates with their IDs.

Handlebars in a SendGrid template that holds up against real orders

SendGrid supports most of Handlebars, not all of it. These are the helpers its docs list.

  1. 1

    Name placeholders after the shape of your data

    Deep objects work, so {{customer.first_name}} and {{order.shipping.method}} read cleanly and match what your code already has. Flattening everything into first_name_1 keys is where typos creep in.

  2. 2

    Loop over line items

    Wrap the row in {{#each order.items}} ... {{/each}} and use {{this.name}} and {{this.price}} inside. Pass an array, even for a single item.

  3. 3

    Branch with the supported conditionals

    if, else, unless, equals, notEquals, greaterThan, lessThan, and, or and length are available. For example, show a tracking block only with {{#if order.tracking_url}}.

    Watch for: the editor preview doesn't compare mixed types properly, such as 3 against "3". Check those branches in a real delivered message.

  4. 4

    Give every greeting a fallback

    {{insert customer.first_name "default=there"}} prints "there" when the name is missing, instead of leaving a gap. Use formatDate for dates, or they print exactly as your code sent them.

  5. 5

    Preview against test data

    In the editor, paste a sample JSON object into the test data panel and the preview renders against it. Use a real order with the awkward cases: two items, no tracking yet, a name with an apostrophe.

  6. 6

    Add a new version for changes

    Click Add Version on the template, edit, save, and choose Make Active when it's ready. SendGrid sends whichever version is active, so the ID in your code never changes.

A delivered SendGrid email with the wrong words in it

"Hi ," with no name

How you'll know: The request was accepted and the greeting is empty.

Fix: The key in dynamic_template_data doesn't match the placeholder: wrong case, wrong nesting, or not sent. Fix the key, and add an insert default so the next miss still reads properly.

HTML tags printed as text

How you'll know: Customers see <strong> in the email body.

Fix: Double braces escape HTML. Use triple braces, {{{ }}}, for a block of HTML your own code built, and never for text a customer typed.

Your edit never shows up

How you'll know: You changed the template and the old design still goes out.

Fix: You edited a version that isn't active. Open the template, use the menu beside the version, and choose Make Active.

Right layout, yesterday's numbers

How you'll know: A price, balance or delivery date in the email was true earlier and isn't now.

Fix: The template only knows what it was handed. Build dynamic_template_data from a live lookup at send time, not from a cached copy, and refuse to send when a required key is empty.

Dynamic templates in practice

What is a SendGrid Dynamic Template?

An email design saved in SendGrid under an ID that starts with d-, written with Handlebars placeholders, conditionals and loops. At send time SendGrid merges it with the data object you pass and produces one personalized email per recipient.

How do I pass data into a SendGrid template?

Put a dynamic_template_data object inside each personalization in your /v3/mail/send request, and set template_id to the template's ID. Each placeholder reads its value from the matching key in that object.

Can a SendGrid template show different content for different recipients?

Yes. Each personalization has its own data, and Handlebars conditionals such as if, unless and equals, plus each loops, decide which blocks appear for that recipient.

Does SendGrid support template versioning?

Yes. One template can hold several versions, and the active one is what sends. To trial a redesign on part of your traffic, copy it to a second template and let your code choose which ID each send uses.

Why would a SendGrid template send the wrong information if the API call succeeds?

Because SendGrid checks the request, not the facts in it. A missing key renders as blank and a stale value renders exactly as given. n-frames builds the send-time checks that catch both before the email leaves.

Where do I find a SendGrid template ID?

In SendGrid, open Email API, then Dynamic Templates, and click the template's name. The ID appears under it, starting with d-. From code, GET /v3/templates?generations=dynamic returns them all.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.