Using templates to send personalized email with the Amazon SES API
You can use the CreateTemplate API operation to create email templates. These templates include a subject line, and the text and HTML parts of the email body. The subject and body sections may also contain unique values that are personalized for each recipient.
There are a few limits and other considerations when using these features:
-
You can create up to 10,000 email templates per Amazon SES account.
-
Each template can be up to 500 KB in size, including both the text and HTML parts.
-
You can include an unlimited number of replacement variables in each template.
-
You can send email to up to 50 destinations in each call to the
SendBulkTemplatedEmail
operation. A destination includes a list of recipients,including CC and BCC recipients. The number of destinations you can contact in a single call to the API may be limited by your account's maximum sending rate. For more information, see Managing your Amazon SES sending limits.
This section includes procedures for creating email templates and for sending personalized emails.
The procedures in this section assume that you've already installed and configured the AWS CLI. For more information about installing and configuring the AWS CLI, see the AWS Command Line Interface User Guide.
Part 1: Set up Rendering Failure event notifications
If you send an email that contains invalid personalization content, Amazon SES might accept the message, but won't be able to deliver it. For this reason, if you plan to send personalized email, you should configure Amazon SES to send Rendering Failure event notifications through Amazon SNS. When you receive a Rendering Failure event notification, you can identify which message contained the invalid content, fix the issues, and send the message again.
The procedure in this section is optional, but highly recommended.
To configure Rendering Failure event notifications
-
Create an Amazon SNS topic. For procedures, see Create a Topic in the Amazon Simple Notification Service Developer Guide.
-
Subscribe to the Amazon SNS topic. For example, if you want to receive Rendering Failure notifications by email, subscribe an email endpoint (that is, your email address) to the topic.
For procedures, see Subscribe to a Topic in the Amazon Simple Notification Service Developer Guide.
-
Complete the procedures in Set up an Amazon SNS event destination for event publishing to set up your configuration sets to publish Rendering Failure events to your Amazon SNS topic.
Part 2: Create an email template
In this section, you use the CreateTemplate API operation to create a new email template with personalization attributes.
This procedure assumes that you've already installed and configured the AWS CLI. For more information about installing and configuring the AWS CLI, see the AWS Command Line Interface User Guide.
To create the template
-
In a text editor, create a new file. Paste the following code into the file.
{ "Template": { "TemplateName": "MyTemplate", "SubjectPart": "Greetings, {{name}}!", "HtmlPart": "<h1>Hello {{name}},</h1><p>Your favorite animal is {{favoriteanimal}}.</p>", "TextPart": "Dear {{name}},\r\nYour favorite animal is {{favoriteanimal}}." } }
This code contains the following properties:
-
TemplateName – The name of the template. When you send the email, you refer to this name.
-
SubjectPart – The subject line of the email. This property may contain replacement tags. These tags use the following format:
{{tagname}}
. When you send the email, you can specify a value fortagname
for each destination.The preceding example includes two tags:
{{name}}
and{{favoriteanimal}}
. -
HtmlPart – The HTML body of the email. This property may contain replacement tags.
-
TextPart – The text body of the email. Recipients whose email clients don't display HTML email see this version of the email. This property may contain replacement tags.
-
-
Customize the preceding example to fit your needs, and then save the file as
mytemplate.json
. -
At the command line, type the following command to create a new template using the
CreateTemplate
API operation:aws ses create-template --cli-input-json file://mytemplate.json
Part 3: Sending the personalized email
After you create an email template, you can use it to send email. There are two API
operations that you can use to send emails using templates:
SendTemplatedEmail
, and SendBulkTemplatedEmail
. The
SendTemplatedEmail
operation is useful for sending a customized email
to a single destination (a collection of "To," "CC," and "BCC" recipients who will
receive the same email). The SendBulkTemplatedEmail
operation is useful for
sending unique emails to multiple destinations in a single call to the Amazon SES API. This
section provides examples of how to use the AWS CLI to send email using both of these
operations.
Sending templated email to a single destination
You can use the SendTemplatedEmail
operation to send an email to a
single destination. All of the recipients in the Destination
object
will receive the same email.
To send a templated email to a single destination
-
In a text editor, create a new file. Paste the following code into the file.
{ "Source":"Mary Major <mary.major@example.com>", "Template": "MyTemplate", "ConfigurationSetName": "ConfigSet", "Destination": { "ToAddresses": [ "alejandro.rosalez@example.com" ] }, "TemplateData": "{ \"name\":\"Alejandro\", \"favoriteanimal\": \"alligator\" }" }
This code contains the following properties:
-
Source – The email address of the sender.
-
Template – The name of the template to apply to the email.
-
ConfigurationSetName – The name of the configuration set to use when sending the email.
Note We recommend that you use a configuration set that is configured to publish Rendering Failure events to Amazon SNS. For more information, see Part 1: Set up Rendering Failure event notifications.
-
Destination – The recipient addresses. You can include multiple "To," "CC," and "BCC" addresses. When you use the
SendTemplatedEmail
operation, all recipients receive the same email. -
TemplateData – An escaped JSON string that contains key-value pairs. The keys correspond to the variables in the template (for example,
{{name}}
). The values represent the content that replaces the variables in the email.
-
-
Change the values in the code in the previous step to meet your needs, and then save the file as
myemail.json
. -
At the command line, type the following command to send the email:
aws ses send-templated-email --cli-input-json file://myemail.json
Sending templated email to multiple destinations
You can use the SendBulkTemplatedEmail
operation to send an email to
several destinations in a single call to the API. Amazon SES sends a unique email to the
recipient or recipients in each Destination
object.
To send a templated email to multiple destinations
-
In a text editor, create a new file. Paste the following code into the file.
{ "Source":"Mary Major <mary.major@example.com>", "Template":"MyTemplate", "ConfigurationSetName": "ConfigSet", "Destinations":[ { "Destination":{ "ToAddresses":[ "anaya.iyengar@example.com" ] }, "ReplacementTemplateData":"{ \"name\":\"Anaya\", \"favoriteanimal\":\"angelfish\" }" }, { "Destination":{ "ToAddresses":[ "liu.jie@example.com" ] }, "ReplacementTemplateData":"{ \"name\":\"Liu\", \"favoriteanimal\":\"lion\" }" }, { "Destination":{ "ToAddresses":[ "shirley.rodriguez@example.com" ] }, "ReplacementTemplateData":"{ \"name\":\"Shirley\", \"favoriteanimal\":\"shark\" }" }, { "Destination":{ "ToAddresses":[ "richard.roe@example.com" ] }, "ReplacementTemplateData":"{}" } ], "DefaultTemplateData":"{ \"name\":\"friend\", \"favoriteanimal\":\"unknown\" }" }
This code contains the following properties:
-
Source – The email address of the sender.
-
Template – The name of the template to apply to the email.
-
ConfigurationSetName – The name of the configuration set to use when sending the email.
Note We recommend that you use a configuration set that is configured to publish Rendering Failure events to Amazon SNS. For more information, see Part 1: Set up Rendering Failure event notifications.
-
Destinations – An array that contains one or more Destinations.
-
Destination – The recipient addresses. You can include multiple "To," "CC," and "BCC" addresses. When you use the
SendBulkTemplatedEmail
operation, all recipients within the sameDestination
object receive the same email. -
ReplacementTemplateData – A JSON object that contains key-value pairs. The keys correspond to the variables in the template (for example,
{{name}}
). The values represent the content that replaces the variables in the email.
-
-
DefaultTemplateData – A JSON object that contains key-value pairs. The keys correspond to the variables in the template (for example,
{{name}}
). The values represent the content that replaces the variables in the email. This object contains fallback data. If aDestination
object contains an empty JSON object in theReplacementTemplateData
property, the values in theDefaultTemplateData
property are used.
-
-
Change the values in the code in the previous step to meet your needs, and then save the file as
mybulkemail.json
. -
At the command line, type the following command to send the bulk email:
aws ses send-bulk-templated-email --cli-input-json file://mybulkemail.json