Using templates to send personalized email with the Amazon SES API (original) (raw)

In Amazon SES you can send templated email either by using a stored template or by using an inline template.

The following limits apply when using stored templates:

The following limit applies when using inline templates:

The following applies to both stored and inline templates:

This chapter includes procedures with examples for using both stored templates and inline templates.

Note

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.

(Optional) 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 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
  1. Create an Amazon SNS topic. For procedures, see Create a Topic in the Amazon Simple Notification Service Developer Guide.
  2. 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.
  3. 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.

(Optional) Part 2: Create an email template

If you intend on using a stored template, this section will show you how to use the CreateEmailTemplate SES v2 API operation to create the template. You can skip this step if you want to use an inline template.

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
  1. In a text editor, create a new file and paste the following code customizing it as you need.
{  
    "TemplateName": "MyTemplate",  
    "TemplateContent": {  
        "Subject": "Greetings, {{name}}!",  
        "Text": "Dear {{name}},\r\nYour favorite animal is {{favoriteanimal}}.",  
        "Html": "<h1>Hello {{name}},</h1><p>Your favorite animal is {{favoriteanimal}}.</p>"  
    }  
}

This code contains the following properties:

  1. Customize the preceding example to fit your needs, and then save the file asmytemplate.json.
  2. At the command line, type the following command to create a new template using the CreateEmailTemplate v2 API operation:
aws sesv2 create-email-template --cli-input-json file://mytemplate.json

Part 3: Sending the personalized email

You can use the following two SES v2 API operations to send emails using either_stored templates_ or inline templates:

This section provides examples of how to use the AWS CLI to send templated email using both of these send operations.

Sending templated email to a single destination object

You can use the SendEmail operation to send an email to one or more recipients defined in a single destination object. All of the recipients in theDestination object will receive the same email.

To send a templated email to a single destination object
  1. Depending on whether you want to use a stored template or inline template, select the respective code example to paste into a text editor, customizing it as you need.
    Stored template code example
    Notice that the template you created in the previous step,MyTemplate, is being referenced as the value for the TemplateName parameter.
{  
    "FromEmailAddress": "Mary Major <mary.major@example.com>",  
    "Destination": {  
        "ToAddresses": [  
            "alejandro.rosalez@example.com", "jimmy.jet@example.com"  
        ]  
    },  
    "Content": {  
        "Template": {  
            "TemplateName": "MyTemplate",  
            "TemplateData": "{ \"name\":\"Alejandro\", \"favoriteanimal\": \"alligator\" }"  
        }  
    },  
    "ConfigurationSetName": "ConfigSet"  
}

This code contains the following properties:

Note

We recommend that you use a configuration set that is configured to publish Rendering Failure events to Amazon SNS. For more information, see (Optional) Part 1: Set up Rendering Failure event notifications.
Inline template code example
Notice that the TemplateContent properties (that would normally be defined in a stored template), are being defined_inline_ along with theTemplateData property which makes this an_inline template_. 

{  
    "FromEmailAddress": "Mary Major <mary.major@example.com>",  
    "Destination": {  
        "ToAddresses": [  
            "alejandro.rosalez@example.com", "jimmy.jet@example.com"  
        ]  
    },  
    "Content": {  
        "Template": {  
            "TemplateContent": {  
                "Subject": "Greetings, {{name}}!",  
                "Text": "Dear {{name}},\r\nYour favorite animal is {{favoriteanimal}}.",  
                "Html": "<h1>Hello {{name}},</h1><p>Your favorite animal is {{favoriteanimal}}.</p>"  
            },  
            "TemplateData": "{ \"name\":\"Alejandro\", \"favoriteanimal\": \"alligator\" }"  
        }  
    },  
    "ConfigurationSetName": "ConfigSet"  
}

This code contains the following properties:

Note

We recommend that you use a configuration set that is configured to publish Rendering Failure events to Amazon SNS. For more information, see (Optional) Part 1: Set up Rendering Failure event notifications. 2. Customize the preceding example to fit your needs, and then save the file as myemail.json. 3. At the command line, type the following v2 API command to send the email: 

aws sesv2 send-email --cli-input-json file://myemail.json

Sending templated email to multiple destination objects

You can use the SendBulkEmail operation to send an email to multiple destination objects in a single call to the SES v2 API. SES sends a unique email to the recipient or recipients in each Destination object.

To send a templated email to multiple destination objects
  1. Depending on whether you want to use a stored template or inline template, select the respective code example to paste into a text editor, customizing it as you need.
    Stored template code example
    Notice that the template you created in the previous step,MyTemplate, is being referenced as the value for the TemplateName parameter.
{  
    "FromEmailAddress": "Mary Major <mary.major@example.com>",  
    "DefaultContent": {  
        "Template": {  
            "TemplateName": "MyTemplate",  
            "TemplateData": "{ \"name\":\"friend\", \"favoriteanimal\":\"unknown\" }"  
        }  
    },  
    "BulkEmailEntries": [  
        {  
            "Destination": {  
                "ToAddresses": [  
                    "anaya.iyengar@example.com"  
                ]  
            },  
            "ReplacementEmailContent": {  
                "ReplacementTemplate": {  
                    "ReplacementTemplateData": "{ \"name\":\"Anaya\", \"favoriteanimal\":\"angelfish\" }"  
                }  
            }  
        },  
        {  
            "Destination": {  
                "ToAddresses": [  
                    "liu.jie@example.com"  
                ]  
            },  
            "ReplacementEmailContent": {  
                "ReplacementTemplate": {  
                    "ReplacementTemplateData": "{ \"name\":\"Liu\", \"favoriteanimal\":\"lion\" }"  
                }  
            }  
        },  
        {  
            "Destination": {  
                "ToAddresses": [  
                    "shirley.rodriguez@example.com"  
                ]  
            },  
            "ReplacementEmailContent": {  
                "ReplacementTemplate": {  
                    "ReplacementTemplateData": "{ \"name\":\"Shirley\", \"favoriteanimal\":\"shark\" }"  
                }  
            }  
        },  
        {  
            "Destination": {  
                "ToAddresses": [  
                    "richard.roe@example.com"  
                ]  
            },  
            "ReplacementEmailContent": {  
                "ReplacementTemplate": {  
                    "ReplacementTemplateData": "{}"  
                }  
            }  
        }  
    ],  
    "ConfigurationSetName": "ConfigSet"  
}

This code contains the following properties:

Note

We recommend that you use a configuration set that is configured to publish Rendering Failure events to Amazon SNS. For more information, see (Optional) Part 1: Set up Rendering Failure event notifications.
Inline template code example
Notice that the TemplateContent properties (that would normally be defined in a stored template), are being defined_inline_ along with theTemplateData property which makes this an_inline template_. 

{  
    "FromEmailAddress": "Mary Major <mary.major@example.com>",  
    "DefaultContent": {  
        "Template": {  
            "TemplateContent": {  
                "Subject": "Greetings, {{name}}!",  
                "Text": "Dear {{name}},\r\nYour favorite animal is {{favoriteanimal}}.",  
                "Html": "<h1>Hello {{name}},</h1><p>Your favorite animal is {{favoriteanimal}}.</p>"  
            },  
            "TemplateData": "{ \"name\":\"friend\", \"favoriteanimal\":\"unknown\" }"  
        }  
    },  
    "BulkEmailEntries": [  
        {  
            "Destination": {  
                "ToAddresses": [  
                    "anaya.iyengar@example.com"  
                ]  
            },  
            "ReplacementEmailContent": {  
                "ReplacementTemplate": {  
                    "ReplacementTemplateData": "{ \"name\":\"Anaya\", \"favoriteanimal\":\"angelfish\" }"  
                }  
            }  
        },  
        {  
            "Destination": {  
                "ToAddresses": [  
                    "liu.jie@example.com"  
                ]  
            },  
            "ReplacementEmailContent": {  
                "ReplacementTemplate": {  
                    "ReplacementTemplateData": "{ \"name\":\"Liu\", \"favoriteanimal\":\"lion\" }"  
                }  
            }  
        },  
        {  
            "Destination": {  
                "ToAddresses": [  
                    "shirley.rodriguez@example.com"  
                ]  
            },  
            "ReplacementEmailContent": {  
                "ReplacementTemplate": {  
                    "ReplacementTemplateData": "{ \"name\":\"Shirley\", \"favoriteanimal\":\"shark\" }"  
                }  
            }  
        },  
        {  
            "Destination": {  
                "ToAddresses": [  
                    "richard.roe@example.com"  
                ]  
            },  
            "ReplacementEmailContent": {  
                "ReplacementTemplate": {  
                    "ReplacementTemplateData": "{}"  
                }  
            }  
        }  
    ],  
    "ConfigurationSetName": "ConfigSet"  
}

This code contains the following properties:

Note

We recommend that you use a configuration set that is configured to publish Rendering Failure events to Amazon SNS. For more information, see (Optional) Part 1: Set up Rendering Failure event notifications. 2. Change the values in the code in the previous step to meet your needs, and then save the file as mybulkemail.json. 3. At the command line, type the following v2 API command to send the bulk email: 

aws sesv2 send-bulk-email --cli-input-json file://mybulkemail.json