Guide
Handlebars in Amazon SES templates.
Last updated 5 October 2026
A working reference for the template syntax SES actually renders: variables, conditionals, loops, and partials, with the rules on escaping and missing data that cause most failed sends.
Conditions without typos
Build if blocks and loops visually, with merge-tag autocomplete, and preview them with sample data.
Open the editorWhat SES supports
Amazon SES renders stored templates, the ones you create with CreateEmailTemplate in the SES v2 API, with Handlebars. AWS documents four features and refers to the Handlebars built-in helpers for the rest (SES advanced personalization).
| Feature | Syntax | Where it’s documented |
|---|---|---|
| Variables and nested paths | {{contact.firstName}} | AWS |
| Loops | {{#each}} | AWS |
| Conditionals | {{#if}} {{else}} | AWS |
| Inline partials | {{#* inline}} {{> name}} | AWS |
| Inverse condition | {{#unless}} | Handlebars built-in |
| Loop data | @index @first @last this | Handlebars built-in |
| Equality and comparisons | None | Not available |
Helpers that aren’t in the AWS documentation are standard Handlebars. Check them against your own data with test rendering before you rely on them in production.
Variables and nested data
Placeholders read from the JSON you pass as TemplateData when you send. Use a dot to reach into nested objects, as many levels deep as you need. Given this data:
{
"contact": { "firstName": "Ada", "lastName": "Lovelace" },
"plan": { "name": "Team", "renewsOn": "12 Nov 2026" },
"isTrial": false,
"items": [
{ "name": "Team plan", "qty": 1, "price": "$120.00" },
{ "name": "Extra seats", "qty": 3, "price": "$36.00" }
]
}these placeholders render the customer’s name and plan:
Hello {{contact.firstName}}
Your {{plan.name}} plan renews on {{plan.renewsOn}}.Placeholders work in the subject and text parts as well as the HTML. Group related fields into objects (contact, plan, order) so templates stay readable as they grow.
Conditionals
if and else
An {{#if}} block renders when its value is truthy. False, null, a missing value, an empty string, 0, and an empty array all count as false.
{{#if isTrial}}
<p>Your trial ends on {{trialEndsOn}}.</p>
{{else}}
<p>Thanks for being a customer.</p>
{{/if}}Because an empty array is false, {{#if items}} is the usual way to hide a section when a list has nothing in it.
else if
Chain conditions with {{else if}}. The first true branch wins.
{{#if isOverdue}}
<p>Your payment is overdue.</p>
{{else if isTrial}}
<p>Your trial ends on {{trialEndsOn}}.</p>
{{else}}
<p>Your next invoice is on {{plan.renewsOn}}.</p>
{{/if}}unless
{{#unless}} is the inverse of if: it renders when the value is false or missing.
{{#unless emailVerified}}
<p><a href="{{verifyUrl}}">Verify your email address</a></p>
{{/unless}}Comparing values
This is the most common surprise. Handlebars has no built-in eq, gt, and, or or helper, and SES gives you no way to register one, so this won’t work:
{{! Not available: SES has no way to register this helper }}
{{#if (eq plan.name "Team")}} ... {{/if}}Do the comparison in your code and send the answer as a boolean:
"plan": { "name": "Team", "isTeam": true }
{{#if plan.isTeam}}
<p>Invite your team from Settings.</p>
{{/if}}The same applies to thresholds (isOverLimit), combinations (canUpgrade), and anything else that needs logic. The template decides what to show, and your code decides what’s true.
Loops
{{#each}} repeats a block for every item in an array. Inside the block, field names refer to the current item. Add {{else}} for an empty list:
<table>
{{#each items}}
<tr>
<td>{{name}} × {{qty}}</td>
<td>{{price}}</td>
</tr>
{{else}}
<tr><td colspan="2">No items on this order.</td></tr>
{{/each}}
</table>Loop data
{{@index}} is the zero-based position, {{@first}} and {{@last}} are true on the first and last items, and {{this}} is the current item, which you need for arrays of plain strings:
{{#each items}}
{{@index}}. {{name}}{{#unless @last}},{{/unless}}
{{/each}}
{{#each tags}}
<span>{{this}}</span>
{{/each}}Reaching outside the loop
Inside each, a bare field name looks in the current item. Use ../ to read from the data around the loop:
{{#each items}}
<p>{{name}} for {{../contact.firstName}}</p>
{{/each}}The loop markup counts once toward the 500 KB template limit, but the rendered email grows with the data. Gmail clips messages over about 102 KB, so cap very long lists in your code and link to the rest. For working examples, the receipt, invoice, and order confirmation templates each repeat their line items with each.
Inline partials
SES doesn’t store shared partials across templates, but you can define an inline partial at the top of a part and reuse it within that part. AWS’s syntax:
{{#* inline "fullName"}}{{firstName}}{{#if lastName}} {{lastName}}{{/if}}{{/inline}}\nThe \n after {{/inline}} is required to separate the definition from the content, and it isn’t rendered. Use the partial with {{> name}}, including inside loops:
<h1>Hello {{> fullName}}!</h1>
<ul>
{{#each friends}}
<li>{{> fullName}}</li>
{{/each}}
</ul>Partials don’t carry across parts. If you use one in both the HTML and the text version, define it in both.
Escaping
In most Handlebars setups, {{value}} escapes HTML and {{{value}}} doesn’t. Don’t rely on that in SES. AWS states that SES doesn’t escape HTML content when it renders the HTML part.
Escape user-entered data before you send it. Names, company names, and anything from a form should be HTML-escaped in your code before it goes into TemplateData. Otherwise a value like <b> becomes markup in the email.
Missing data and testing
SES renders when it sends, not when you call the API. AWS warns that a message with invalid personalization content can be accepted and then never delivered (SES templates guide). Three habits prevent most of these failures:
- Test render before you ship.
test-render-email-templaterenders a stored template with the data you give it and returns the MIME message, or the error:
Run it with complete data, with optional fields left out, and with empty lists.aws sesv2 test-render-email-template \ --template-name order-receipt \ --template-data '{"contact":{"firstName":"Ada"},"items":[]}' - Guard optional fields. Wrap anything that might be missing in
{{#if}}rather than assuming it’s there. - Publish Rendering Failure events. Use a configuration set that sends Rendering Failure events to Amazon SNS, so a failed render shows up instead of disappearing. See SES template rendering failures and how to test SES templates.
Default data in bulk sends
With SendBulkEmail, DefaultContent holds the template data used for any entry whose ReplacementTemplateData is an empty object, {}. AWS documents it as a fallback for empty entries, not as defaults merged into each recipient’s data, so send complete data for every recipient.
"DefaultContent": {
"Template": {
"TemplateName": "order-receipt",
"TemplateData": "{ \"contact\": { \"firstName\": \"there\" }, \"items\": [] }"
}
},
"BulkEmailEntries": [
{ "Destination": { "ToAddresses": ["ada@example.com"] },
"ReplacementEmailContent": { "ReplacementTemplate": {
"ReplacementTemplateData": "{}" } } }
]Cheat sheet
{{name}} variable
{{contact.firstName}} nested path
{{! a comment }} not rendered
{{#if x}} … {{else}} … {{/if}} condition
{{#if x}} … {{else if y}} … {{/if}}
{{#unless x}} … {{/unless}} inverse condition
{{#each list}} … {{/each}} loop
{{#each list}} … {{else}} … {{/each}} empty list fallback
{{this}} {{@index}} {{@first}} {{@last}}
{{../parentField}} step out of the loop
{{#* inline "p"}} … {{/inline}}\n define partial (per part)
{{> p}} use partialFor template structure, creating templates, sending, and limits, see the Amazon SES email templates guide.
Writing Handlebars visually
Huskar Templates is a visual editor for SES templates. Conditions and loops are real Handlebars attached to blocks: show a block when a path is truthy, or repeat a section over a list. Merge tags are chips with {{ autocomplete, so paths match your data. Preview each template with sample data profiles, including empty lists and missing values, in Gmail, Apple Mail, and Outlook frames, then publish to SES. See the product.
FAQ
Does Amazon SES use Handlebars?
Yes. Stored templates created with the SES v2 CreateEmailTemplate operation are rendered with Handlebars. AWS documents nested attributes, each loops, if and else conditionals, and inline partials, and points to the Handlebars built-in helpers for anything beyond that.
How do I write an if statement in an SES template?
Use {{#if field}} … {{else}} … {{/if}}. The block renders when the field is truthy. False, null, a missing value, an empty string, 0, and an empty array all count as false.
Can I compare values, like if plan equals "Team", in SES?
Not directly. Handlebars has no built-in equality helper, and SES gives you no way to register custom helpers. Compute the comparison in your code and send it as a boolean, for example "isTeam": true, then use {{#if isTeam}}.
How do I loop over a list in an SES template?
Use {{#each items}} … {{/each}}. Inside the loop, fields refer to the current item, {{this}} is the item itself, and {{@index}} is its position. Add {{else}} before {{/each}} to show something when the list is empty.
Does SES escape HTML in template variables?
No. AWS states that SES does not escape HTML content when rendering the HTML part. Escape any user-entered data in your code before you put it in TemplateData.
How do I test an SES template with sample data?
Run aws sesv2 test-render-email-template with the template name and a JSON string of data. It returns the rendered MIME message, or an error if the template cannot render with that data.