sendgrid dynamic template data not working

"Dynamic template data not working" is not an SMTP reply code or a named SendGrid API error — it's the common description of a successful send (HTTP 202 Accepted) in which the Handlebars variables in your dynamic template come out empty or appear as literal {{text}} instead of your data. Because the API returns 202, nothing fails loudly; the breakdown is in how the template and the dynamic_template_data payload line up. Below are the concrete causes, most common first.

What causes SendGrid dynamic template data to render blank?

1. Field name mismatch. A Handlebars tag only resolves if a key with the exact same name exists in dynamic_template_data. {{firstName}} will not be filled by first_name. Missing or misspelled keys render as empty strings silently (Using Handlebars).
2. Illegal characters in the field name. Field names must use only alphanumeric characters (A–Z, 0–9) and underscores, and must start with a letter or underscore. Spaces are the classic trap: {{first name}} saves without an error but never substitutes (Handlebars Syntax Errors).
3. dynamic_template_data in the wrong place. It must live inside each personalizations object, not at the top level of the request body. Top-level data is ignored.
4. Wrong template type / ID. The template_id must be a Dynamic template ID — it starts with d- followed by a 32-character hexadecimal string (a UUID with its dashes removed), for example d-f43daeeaef504760851f727007e0b5d0. A legacy transactional template ID will not interpret Handlebars; legacy templates use substitutions with -tag- syntax instead.
5. Mixing substitutions with a dynamic template. These are mutually exclusive. Sending both returns the API error "Substitutions may not be used with dynamic templating."
6. No active version. A dynamic template renders the version marked active in the UI. If you never clicked "Make Active," there is no content to populate.
7. Unbalanced braces or HTML escaping. {{unbalanced}}} breaks rendering. Values containing HTML or ' " & are HTML-escaped by {{ }}; use triple braces {{{ value }}} to output raw HTML.

How do I fix SendGrid dynamic template data?

Step 1 — Confirm placement and ID. Put dynamic_template_data inside personalizations and use the d-... ID:

{
  "from": { "email": "you@example.com" },
  "personalizations": [
    {
      "to": [{ "email": "user@example.com" }],
      "dynamic_template_data": { "first_name": "Ada", "order_id": 1234 }
    }
  ],
  "template_id": "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Step 2 — Match names exactly. Open the active version of the template and make every {{key}} match a key in your JSON character-for-character. Keep names to letters, digits, and underscores; no spaces.

Step 3 — Remove conflicts. Delete any substitutions block from the request when using a dynamic template. Use one system or the other.

Step 4 — Test with the editor's preview data. The template editor lets you paste test JSON. If it renders there but not in your send, the data shape differs from your live payload — log the exact body you send. (Note: variables nested inside greaterThan/equals/and/or conditionals can look blank in the editor preview yet render correctly in the delivered email — a known editor-only display bug.)

Step 5 — Handle nested data and HTML. Use dot notation for nested objects ({{user.profile.name}}), {{#each items}}...{{this.name}}...{{/each}} for arrays, and {{{html_block}}} when the value is intended to be raw HTML.