Guide
Test Amazon SES templates in CI and catch rendering failures early
Last updated 3 November 2026
Here's a failure that's easy to miss. Your app calls SendEmail with a stored SES template, gets a message ID back, and moves on. The customer never gets the email. No exception, no bounce. The email just doesn't exist.
Preview before you get to CI
Switch between sample profiles, see each if branch in Gmail, Apple Mail, and Outlook frames, and publish to SES.
Open the editorAWS documents this behaviour: if you send an email with invalid personalization content, "Amazon SES might accept the message, but won't be able to deliver it" (SES Developer Guide). Rendering happens after the API call. So a template change or a data change can quietly break password resets, receipts, or invites.
This guide sets up four layers so that doesn't happen: fixtures, a render script, a CI job, and a production alert.
What makes an SES template fail to render
- A missing variable. Every variable in the template needs an exact, case-sensitive key in
TemplateData. AWS's own troubleshooting article shows the resulting event message:Attribute 'favoritecolor' is not present in the rendering data.(AWS re:Post knowledge center). Extra keys are fine. - A case mismatch.
{{firstName}}and"firstname"don't match. nullvalues. Developers report that a key set tonullfails the same way as a missing key. Send"",0, or[]instead.- Helpers SES doesn't have. SES supports Handlebars features such as nested attributes,
each,if, and inline partials (advanced personalization). Custom helpers such as comparison helpers aren't built in. See our SES Handlebars reference. - Malformed
TemplateData. It's a JSON object passed as a string, so escaping mistakes are common.
Layer 1: keep fixtures next to your templates
Give each template a folder with its content and one fixture per real-world case:
email-templates/
password-reset/
template.json # { "Subject": ..., "Html": ..., "Text": ... }
fixtures/
default.json
no-city.json # lookup failed, city is ""
receipt/
template.json
fixtures/
one-item.json
many-items.json
no-discount.json # the {{#if discount}} branch offWrite fixtures from your real payload builder output if you can (snapshot what your code sends). Hand-written fixtures drift. Cover every {{#if}} both ways, and every {{#each}} with one item, many items, and an empty list.
Layer 2: a render script that fails loudly
TestRenderEmailTemplate renders a stored template with the data you pass and returns the full MIME message, or an error (API reference). Two limits worth knowing: it can run at most once per second, and TemplateData can be up to 262,144 characters.
The CLI version, for a quick check:
aws sesv2 test-render-email-template \
--template-name password-reset \
--template-data file://email-templates/password-reset/fixtures/default.jsonFor CI, use a script that walks every fixture, respects the rate limit, and also checks the output for leftover {{ (a sign of a typo such as {{ firstName } that rendered as literal text):
// scripts/test-ses-templates.mjs
import { readdir, readFile } from "node:fs/promises";
import path from "node:path";
import { SESv2Client, TestRenderEmailTemplateCommand } from "@aws-sdk/client-sesv2";
const ses = new SESv2Client({ region: process.env.AWS_REGION });
const root = "email-templates";
const prefix = process.env.TEMPLATE_PREFIX ?? ""; // e.g. "staging-"
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
let failures = 0;
for (const name of await readdir(root)) {
const dir = path.join(root, name, "fixtures");
for (const file of await readdir(dir)) {
const data = await readFile(path.join(dir, file), "utf8");
JSON.parse(data); // fail fast on broken fixture JSON
try {
const res = await ses.send(new TestRenderEmailTemplateCommand({
TemplateName: prefix + name,
TemplateData: data,
}));
if (res.RenderedTemplate.includes("{{")) throw new Error("unrendered {{ in output");
console.log(`ok ${name}/${file}`);
} catch (err) {
failures++;
console.error(`FAIL ${name}/${file}: ${err.name}: ${err.message}`);
}
await sleep(1100); // TestRenderEmailTemplate: max 1 request per second
}
}
process.exit(failures ? 1 : 0);Note that TestRenderEmailTemplate renders a template that's already stored in SES. So in CI, first publish the changed templates to a staging name or a staging account (for example staging-password-reset with CreateEmailTemplate/UpdateEmailTemplate), then render. Never test against the production template you're about to replace.
Layer 3: run it on every pull request
A GitHub Actions job using OIDC, so no long-lived AWS keys sit in your repo:
# .github/workflows/ses-templates.yml
name: SES templates
on:
pull_request:
paths: ["email-templates/**"]
permissions:
id-token: write
contents: read
jobs:
render:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/ses-template-ci
aws-region: eu-west-1
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npm ci
- run: node scripts/publish-staging-templates.mjs # create/update staging-* names
- run: node scripts/test-ses-templates.mjs
env: { TEMPLATE_PREFIX: "staging-" }Give the CI role only what it needs: create, update, get, and test-render on templates, scoped to the staging names if you can. The IAM action names to check are ses:CreateEmailTemplate, ses:UpdateEmailTemplate, ses:GetEmailTemplate, and ses:TestRenderEmailTemplate. The role shouldn't need permission to send email.
Layer 4: a safety net in production
CI catches template changes. It can't catch your application sending bad data next Tuesday. For that, publish Rendering Failure events:
- Create an SNS topic, for example
ses-rendering-failures. - Add an event destination to the configuration set you send with, with the Rendering Failure event type, pointing at that topic. AWS recommends this setup for anyone sending personalized email (SES Developer Guide).
- Subscribe something that pages a human: email, a Slack webhook through a Lambda function, or your incident tool.
Each event includes eventType: "Rendering Failure" and a failure object with errorMessage and templateName (event contents), so the alert can name the template and the missing attribute:
{
"eventType": "Rendering Failure",
"failure": {
"errorMessage": "Attribute 'favoritecolor' is not present in the rendering data.",
"templateName": "ExampleTemplate"
}
}A good rule: any rendering failure on a security email (password reset, sign-in link, verification) should page someone straight away, because the user is stuck until it's fixed.
Checklist
- Every template has fixtures for each
ifbranch and eacheach(empty, one, many) - Fixtures come from real payload builder output, not hand-typed JSON
- Your code sends
""/0/[]instead ofnullor leaving keys out - Templates publish to staging names before test-render; production only after it passes
- CI uses OIDC and a role that can't send email
- Rendering Failure events go to SNS on every configuration set you send with
- Alerts name the template and the error message
FAQ
Does test-render-email-template send an email?
No. It returns the rendered MIME message, or an error, and nothing is delivered.
Can I test-render a template that isn't in SES yet?
No. It takes a template name, so the template has to exist. Publish to a staging name first.
Will an optional field inside {"{#if}"} fail when the key is missing?
Test it in your own account with a fixture that leaves the key out. The safest habit is to always send the key, with an empty value.
Why did my email render fine in a local Handlebars library but fail in SES?
SES supports a subset of Handlebars, and local emulators may differ too. Always do the final check with TestRenderEmailTemplate against SES itself.
Related: SES Handlebars reference · Amazon SES email templates guide