How do I troubleshoot email delivery failures with Amazon SES SendTemplatedEmail APIs?

Short description

When you use an email template, Amazon SES validates that the template data you send includes the required variables in the template. If the template data contains non-compliant variables or is missing variables, then Amazon SES can't deliver the email.

Resolution

Use Amazon SNS to set up Rendering Failure event notifications. Then, review the Rendering Failure event notifications to find out why Amazon SES didn't deliver an email when you use the SendTemplatedEmail API operation.

After you set up Rendering Failure event notifications, you receive an Amazon SNS notification when a delivery fails that's sent from an email template. The notification error message includes information about the template variable that led to the Rendering Failure.

For example, the following template contains the variables name and favoritecolor:

{  "Template": {
    "TemplateName": "ExampleTemplate",
    "SubjectPart": "Hello, {{name}}!",
    "HtmlPart": "<h1>Hello {{name}},</h1><p>Your favorite color is {{favoritecolor}}.</p>",
    "TextPart": "Dear {{name}},\r\nYour favorite color is {{favoritecolor}}."
  }
}

If you send the preceding template data, then Amazon SES can't deliver the email. This is because the favoritecolor variable is missing from the template.

Important: Including extra variables in the template such as favoritenumber, doesn't cause an error. However, all variables that you include in the template must have an exact case-sensitive counterpart in the template data.

Example template with correct variables:

"TemplateData": "{ \"name\":\"Jane\", \"favoritenumber\": \"10\" }"

Example Rendering Failure event notification:

{    "eventType": "Rendering Failure",
    "mail": {
        "timestamp": "2019-09-09T04:38:19.788Z",
        "source": "sender@example.com",
        "sourceArn": "arn:aws:ses:us-west-2:1234567890123:identity/sender@example.com",
        "sendingAccountId": "1234567890123",
        "messageId": "01010161a734a0eb-a706827a-3bda-490f-8eaa-63cf4b00d10c-000000",
        "destination": [
            "receiver@example.com"
        ],
        "headersTruncated": false,
        "tags": {
            "ses:configuration-set": [
                "RenderFailure"
            ]
        }
    },
    "failure": {
        "errorMessage": "Attribute 'favoritecolor' is not present in the rendering data.",
        "templateName": "ExampleTemplate"
    }
}

To avoid Rendering Failures, follow these best practices:

• Verify that the capitalization of variable names in your template data is correct Variable names in the template are case sensitive.
• Verify that your template data includes all the variables in the template.
• You must send the message from a verified email address or domain, and the maximum message size is 10 MB.

Related information

Using templates to send personalized email with the Amazon SES API

Why don't the emails that I send through Amazon SES get delivered?

Amazon SES delivery problems