Amazon Simple Email Service
Developer Guide

Set Up a CloudWatch Event Destination for Amazon SES Event Publishing

An Amazon CloudWatch event destination represents an entity that publishes Amazon SES email sending events to CloudWatch. Because a CloudWatch event destination exists within a configuration set only, you must first create a configuration set and then add the event destination to the configuration set.

When you add a CloudWatch event destination to a configuration set, you must choose one or more CloudWatch dimensions that correspond to the message tags you use when you send your emails. Like message tags, a CloudWatch dimension is a name/value pair that helps you uniquely identify a metric. For example, you might have a message tag and a dimension called campaign that you use to identify your email campaign. When you publish your email sending events to CloudWatch, choosing your message tags and dimensions is important because these choices affect your CloudWatch billing and determine how you can filter your email sending event data in CloudWatch.

This section provides information to help you choose your dimensions, and then shows how to add a CloudWatch event destination to a configuration set.

Choosing CloudWatch Dimensions

When you choose your message tags and CloudWatch dimensions, keep the following in mind:

  • Auto-tags—Amazon SES automatically applies several auto-tags to the emails you send. To set up a CloudWatch dimension for an auto-tag, you must type the auto-tag name as the dimension name (such as ses:configuration-set) when you add the CloudWatch event destination to your configuration set. For a list of auto-tags and their descriptions, see How Event Publishing Works.

  • Price per metric—Although you can access basic email sending statistics across your entire AWS account in CloudWatch for free, any metrics that you collect using configuration sets are not free, because they are custom metrics. Each unique combination of email sending event type, CloudWatch dimension name, and CloudWatch dimension value creates a different custom metric in CloudWatch, and CloudWatch charges for each custom metric. For this reason, you might want to avoid choosing dimensions that can take many different values. For example, unless you are very interested in tracking your email sending events by "From" domain, you might not want to define a dimension for the Amazon SES auto-tag ses:from-domain because it can take many different values.

  • Metric filtering—If a metric has multiple dimensions, you cannot access the metric in CloudWatch based on each dimension separately. For that reason, think carefully before you add more than one dimension to a single CloudWatch event destination. For example, if you want metrics per campaign and per a combination of campaign and genre, you need to add two event destinations: one with only campaign as a dimension, and one with campaign and genre as dimensions.

  • Dimension value source—As an alternative to specifying your dimension values using Amazon SES-specific headers or a parameter to the API, you can also choose for Amazon SES to take the dimension values from your own MIME message headers. You might use this option if you are already using custom headers and you do not want to change your emails or your calls to the email sending API to collect metrics based on your header values. If you use your own MIME message headers for Amazon SES event publishing, the header names and values that you use for Amazon SES event publishing must be in ASCII. If you specify a non-ASCII header name or value for event publishing, the email sending call will still succeed, but the event metrics will not be emitted to Amazon CloudWatch.

For more information about CloudWatch concepts, see Amazon CloudWatch Concepts in the Amazon CloudWatch User Guide.

Adding a CloudWatch Event Destination

To add a CloudWatch event destination to a configuration set, you can use the Amazon SES console or the UpdateConfigurationSetEventDestination API.

To add a CloudWatch event destination to a configuration set (console)

  1. Sign in to the AWS Management Console and open the Amazon SES console at

  2. In the left navigation pane, choose Configuration Sets.

  3. Choose a configuration set from the configuration set list. If the list is empty, you must first create a configuration set.

  4. For Add Destination, choose Select a destination type, and then choose CloudWatch.

  5. For Name, type a name for the event destination.

  6. For Event types, select at least one event type to publish to the event destination:

    • Send – Your API call to Amazon SES was successful and Amazon SES will attempt to deliver the email.

    • Reject – Amazon SES initially accepted the email, but later rejected it because the email contained a virus.

    • Bounce – The recipient's mail server permanently rejected the email. This event corresponds to hard bounces. Soft bounces are only included when Amazon SES fails to deliver the email after retrying for a period of time.

    • Complaint – The recipient marked the email as spam.

    • Delivery – Amazon SES successfully delivered the email to the recipient's mail server.

    • Open – The recipient received the message and opened it in his or her email client.

    • Click – The recipient clicked one or more links contained in the email.

    • Rendering Failure – The email was not sent because of a template rendering issue. This event type only occurs when you send templated email using the SendTemplatedEmail or SendBulkTemplatedEmail API operations. This event type can occur when template data is missing, or when there is a mismatch between template parameters and data.

  7. Select Enabled.

  8. For Value Source, choose Message Tag if you want Amazon SES to get the value of the dimension from a message tag that you specified using an X-SES-MESSAGE-TAGS header or a parameter to the API, or choose Email Header if you want Amazon SES to get the value of the dimension from your own email headers.

  9. For Dimension Name, type a string to represent this email characteristic in CloudWatch.


    If you want to use an Amazon SES auto-tag, you must explicitly type the name of the auto-tag (such as ses:configuration-set) as the Dimension Name. For a list of auto-tags, see How Event Publishing Works.

  10. For Default Value, type a default value for the dimension.

  11. Choose Add Dimension to add dimensions, as needed.

  12. Choose Save.

  13. To exit the Edit Configuration Set page, use the back button of your browser.

For information about how to use the UpdateConfigurationSetEventDestination API to add a CloudWatch event destination, see the Amazon Simple Email Service API Reference.