Skip to content

Guide

How to test and preview Amazon SES email templates.

Last updated 11 November 2026

SES can render a stored template with sample data and hand you the result without sending anything. Here’s how to use that, what data to try, and how to see the email the way a recipient would.

See it like an inbox

Preview SES templates with sample data in Gmail, Apple Mail, and Outlook frames before you publish.

Open the editor

Why test before sending

AWS warns 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). The send call succeeds, and the recipient gets nothing. Rendering the template first, with the data your application really sends, finds these problems before a customer does.

Render a template with the CLI

test-render-email-template takes a template name and a JSON string of replacement values:

aws sesv2 test-render-email-template \
  --template-name order-receipt \
  --template-data '{"firstName":"Ada","items":[{"name":"Team plan","price":"$120.00"}]}'

The response has one field:

{
    "RenderedTemplate": "..."
}

RenderedTemplate is the complete MIME message, rendered by applying your data to the template. To keep the sample data in a file and print only the message:

aws sesv2 test-render-email-template \
  --template-name order-receipt \
  --template-data file://sample-data.json \
  --query RenderedTemplate --output text

Render it with an SDK

Node.js:

import { SESv2Client, TestRenderEmailTemplateCommand } from '@aws-sdk/client-sesv2';

const ses = new SESv2Client({ region: 'us-east-1' });

const { RenderedTemplate } = await ses.send(new TestRenderEmailTemplateCommand({
  TemplateName: 'order-receipt',
  TemplateData: JSON.stringify({ firstName: 'Ada', items: [] }),
}));

console.log(RenderedTemplate);

Python:

import json
import boto3

ses = boto3.client('sesv2', region_name='us-east-1')

result = ses.test_render_email_template(
    TemplateName='order-receipt',
    TemplateData=json.dumps({'firstName': 'Ada', 'items': []}),
)

print(result['RenderedTemplate'])

TemplateData is a string, so serialize your object to JSON first.

What data to test with

One happy-path record isn’t enough. Render the template with each of these:

  • A full record. Every field present, with realistic lengths.
  • Optional fields left out. Check that each if block shows the right branch.
  • Empty lists. AWS’s own example shows that a recipient with no items gets an empty list from each unless you wrap it in a condition (Advanced email personalization).
  • Long values. Long names, long product titles, and large amounts.
  • Characters that matter in HTML. SES doesn’t escape HTML content when it renders the HTML part, so try values containing <, >, and & and confirm your application escapes them.

Check the subject and the text part as well as the HTML. An inline partial has to be defined in each part that uses it.

Limits and errors

ItemValue
Call rateNo more than once per second
TemplateData lengthUp to 262,144 characters
BadRequestExceptionThe input is invalid
NotFoundExceptionThe template doesn’t exist
TooManyRequestsExceptionToo many requests

Source: TestRenderEmailTemplate in the SES API v2 reference.

Send a test email

A rendered MIME message tells you the content is right. It doesn’t show how a mail client displays it. For that, send the template to your own address with SendEmail, and use a configuration set that publishes Rendering Failure events so a failed render is reported. See SES template rendering failures.

Preview visually

Huskar Templates shows an SES template with sample data as you edit it. You keep sample data profiles, such as a trial user and a paying customer, and switch between them to check each condition and loop. The preview has Gmail, Apple Mail, and Outlook frames, and nothing is published to SES until you choose to.

You can try the editor in your browser without an account. For the other template commands, see the SES template API and CLI reference.

FAQ

How do I preview an Amazon SES template?

Call TestRenderEmailTemplate with the template name and a JSON string of sample data, for example with aws sesv2 test-render-email-template. It returns the complete MIME message SES would build from that template and data.

Does test-render-email-template send an email?

No. AWS describes it as creating a preview of the MIME content of an email. It returns the rendered message in the response.

How often can I call TestRenderEmailTemplate?

No more than once per second, according to the SES API v2 reference. Calls above that return TooManyRequestsException.

How large can the test data be?

The TemplateData string can be up to 262,144 characters.