Skip to content

Guide

Amazon SES template rendering failures: causes and fixes.

Last updated 11 November 2026

A templated email can be accepted by SES and never reach the recipient. This is a rendering failure. Here’s how to see it, what causes it, and how to stop it happening.

Find it before sending

Preview each condition and loop with sample data profiles before the template reaches SES.

Open the editor

What a rendering failure is

When you send with a template, SES combines the template with the data you pass. If that step fails, SES records a Rendering Failure event. AWS defines it this way: the email wasn’t sent because of a template rendering issue, which can occur when template data is missing or when there is a mismatch between template parameters and data (Monitor email sending using event publishing).

It only occurs with templated email, sent with SendEmail using template content or with SendBulkEmail.

Why you don’t see it

AWS states that if you send an email with invalid personalization content, SES might accept the message but won’t be able to deliver it (Using templates to send personalized email). Your send call returns successfully. The failure is reported as an event, and you receive events only when a configuration set is set up to publish them.

Turn on Rendering Failure events

AWS calls this optional but highly recommended. The steps from the SES developer guide:

  1. Create an Amazon SNS topic.
  2. Subscribe to the topic, for example with your email address.
  3. Add an SNS event destination to a configuration set, and include the Rendering Failure event type. In the API, the value is RENDERING_FAILURE (EventDestinationDefinition).
  4. Pass that configuration set name on every templated send:
{
  "FromEmailAddress": "Northwind <billing@northwind.example>",
  "Destination": { "ToAddresses": ["ada@example.com"] },
  "Content": {
    "Template": {
      "TemplateName": "order-receipt",
      "TemplateData": "{ \"firstName\": \"Ada\" }"
    }
  },
  "ConfigurationSetName": "transactional"
}

SNS is one option. SES can also publish events to Amazon CloudWatch, Amazon Data Firehose, and Amazon EventBridge.

Read the event

A Rendering Failure event has a failure object with two fields (event contents reference):

{
  "eventType": "Rendering Failure",
  "mail": { ... },
  "failure": {
    "templateName": "order-receipt",
    "errorMessage": "..."
  }
}
FieldDescription
templateNameThe name of the template used to send the email
errorMessageA message that provides more information about the rendering failure

The mail object in the same event describes the original email, including its destination, so you can tell which message failed.

Common causes

AWS names two causes:

  • Missing template data. The template uses a variable that the send call didn’t supply.
  • A mismatch between template parameters and data. The data you sent doesn’t line up with what the template refers to.

Two places where data commonly goes missing:

  • Bulk sends. In SendBulkEmail, a destination whose replacement data is an empty object uses the default template data instead. A variable that’s absent from the default is then absent for that destination.
  • Template edits. A new variable added to the template is missing from every send until your application supplies it.

Fix and resend

  1. Read templateName and errorMessage from the event.
  2. Render that template with the same data and see what comes back:
    aws sesv2 test-render-email-template \
      --template-name order-receipt \
      --template-data file://failing-data.json
  3. Either supply the missing data in your application, or change the template so it handles the missing value.
  4. Send the message again. AWS describes the same sequence: identify the message, fix the issue, and send again.

To change the template, see how to edit SES templates.

Prevent it

  • Wrap optional content in a condition. This is the pattern AWS shows for lists (Advanced email personalization):
    {{#if items}}
      <ul>
        {{#each items}}<li>{{name}}: {{price}}</li>{{/each}}
      </ul>
    {{else}}
      <p>No items on this order.</p>
    {{/if}}
  • Give bulk sends complete default data. Put a value for every variable in the default template data.
  • Test with incomplete data. Render the template with optional fields left out and with empty lists. See how to test SES templates.
  • Always send with the configuration set. A failure you’re told about is one you can fix.

Huskar Templates helps with the testing part. You preview a template against sample data profiles, such as a trial user and a paying customer, and see each condition and loop before you publish to SES. You can try it in your browser without an account. The SES Handlebars reference covers conditions and loops in detail.

FAQ

What is a Rendering Failure in Amazon SES?

An event SES records when an email wasn’t sent because of a template rendering issue. AWS says it can occur when template data is missing, or when there is a mismatch between template parameters and data. It only occurs when you send templated email.

Why did my SES templated email not arrive when the API call succeeded?

AWS documents that if you send an email with invalid personalization content, SES might accept the message but won’t be able to deliver it. The failure is reported as a Rendering Failure event, which you only receive if a configuration set publishes that event type.

How do I get notified of SES rendering failures?

Create a configuration set with an event destination that includes the RENDERING_FAILURE event type, for example an Amazon SNS topic, and pass that configuration set name when you send. AWS calls this step optional but highly recommended.

What does a Rendering Failure event contain?

The event has eventType set to Rendering Failure, the mail object describing the original email, and a failure object with two fields: templateName and errorMessage.