Menu
Amazon Simple Email Service
Developer Guide

Sending Personalized Email Using 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 500KB 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, as well as CC and BCC recipients. Note that 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.

Part 1: Create an Email Template

The instructions in this section assume that you are using the AWS CLI, and that you configured it to interact with your AWS account. For more information about installing and configuring the AWS CLI, see the AWS Command Line Interface User Guide.

To create the template

  1. In a text editor, create a new file. Paste the following code into the file.

    Copy
    { "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 for tagname 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 do not display HTML email see this version of the email. This property may contain replacement tags.

  2. Customize the preceding example to fit your needs, and then save the file as mytemplate.json.

  3. 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 2: 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

  1. In a text editor, create a new file. Paste the following code into the file.

    Copy
    { "Source": "sender@example.com", "Template": "MyTemplate", "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.

    • Destination – The recipient addresses. You can include multiple "To," "CC," and "BCC" addresses. When you use the SendTemplatedEmail operation, all recipients will receive the same email.

    • TemplateData – 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.

  2. Customize the preceding example to meet your needs, and then save the file as myemail.json.

  3. At the command line, type the following command to create a new template: 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

  1. In a text editor, create a new file. Paste the following code into the file.

    Copy
    { "Source":"sender@example.com", "Template":"MyTemplate", "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.

    • 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 same Destination object will 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 a Destination object contains an empty JSON object in the ReplacementTemplateData property, the values in the DefaultTemplateData property are used.

  2. Customize the preceding example to meet your needs, and then save the file as mybulkemail.json.

  3. At the command line, type the following command to create a new template: aws ses send-bulk-templated-email --cli-input-json file://mybulkemail.json