Simple Email Service - Developer Guide

Amazon Simple Email Service
Developer Guide
API Version 2010-12-01
Amazon Simple Email Service Developer Guide
Amazon Simple Email Service: Developer Guide

Copyright 2017 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any
manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other
trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to,
or sponsored by Amazon.
Table of Contents
What Is Amazon SES? .................................................................................................................. 1
Why use Amazon SES? ........................................................................................................ 1
Amazon SES and other AWS services ..................................................................................... 1
In this guide ......................................................................................................................... 2
Sending Email .............................................................................................................................. 3
How do I send emails using Amazon SES? .............................................................................. 3
How do I start? .................................................................................................................... 4
Concepts ............................................................................................................................. 5
Amazon SES and Deliverability ....................................................................................... 6
Email-Sending Process .................................................................................................. 9
Email Format and Amazon SES .................................................................................... 12
Quick Start ......................................................................................................................... 15
Step 1: Sign up for AWS .............................................................................................. 15
Step 2: Verify your email address .................................................................................. 15
Step 3: Send your first email ........................................................................................ 15
Step 4: Consider how you will handle bounces and complaints ........................................... 16
Step 5: Move out of the Amazon SES sandbox ............................................................... 16
Next steps .................................................................................................................. 16
Getting Started ................................................................................................................... 16
Using the Amazon SES Console ................................................................................... 16
Using Simple Mail Transfer Protocol (SMTP) ................................................................... 17
Using an AWS SDK .................................................................................................... 17
Before You Begin ........................................................................................................ 17
Send an Email Using the Console ................................................................................. 17
Send an Email Using SMTP ......................................................................................... 19
Send an Email Using an AWS SDK ............................................................................... 28
Setting up Email ................................................................................................................. 37
Signing up for AWS ..................................................................................................... 38
Verifying Email Addresses and Domains ......................................................................... 39
Getting Your AWS Access Keys .................................................................................... 46
Downloading an AWS SDK .......................................................................................... 46
Using a Custom MAIL FROM Domain ............................................................................ 46
Setting up SPF Records ............................................................................................... 53
Getting Your SMTP Credentials ..................................................................................... 54
Moving Out of the Sandbox .......................................................................................... 54
Sending Your Email ............................................................................................................. 55
Using the SMTP Interface ............................................................................................ 56
Using the API ............................................................................................................. 87
Authenticating Your Email .................................................................................................... 92
Authenticating Email with SPF ...................................................................................... 92
Authenticating Email with DKIM ..................................................................................... 93
Complying with DMARC ............................................................................................. 103
Monitoring Your Sending Activity .......................................................................................... 103
Monitoring Using the Console or API ............................................................................ 105
Monitoring Using Notifications ...................................................................................... 106
Monitoring Using Event Publishing ............................................................................... 127
Managing Your Sending Limits ............................................................................................ 192
Monitoring Your Sending Limits ................................................................................... 193
Increasing Your Sending Limits ................................................................................... 194
What Happens When You Reach Your Sending Limits .................................................... 195
Using Sending Authorization ............................................................................................... 196
Overview of Sending Authorization ............................................................................... 197
Sending Authorization Policies ..................................................................................... 199
Sending Authorization Policy Examples ......................................................................... 203
Identity Owner Tasks ................................................................................................. 207
iv
Delegate Sender Tasks ..............................................................................................

Using Dedicated IP Addresses ............................................................................................
Dedicated IP Use Cases ............................................................................................
Trade-offs Between Dedicated IPs and Shared IPs .........................................................
How to Request and Relinquish Dedicated IPs ...............................................................
How to Warm Up Dedicated IPs ..................................................................................
Testing Email Sending .......................................................................................................
Amazon SES and Security Protocols ....................................................................................
Email Sender to Amazon SES .....................................................................................
Amazon SES to Receiver ...........................................................................................
Best Practices ...................................................................................................................
Improving Deliverability ...............................................................................................
Obtaining and Maintaining Your Recipient List ...............................................................
Processing Bounces and Complaints ............................................................................
Using Multiple Accounts .............................................................................................
Troubleshooting .................................................................................................................
Delivery Problems .....................................................................................................
Problems with Received Emails ...................................................................................
Email Sending Errors .................................................................................................
Domain Verification Problems ......................................................................................
DKIM Problems .........................................................................................................
Notification Problems .................................................................................................
Removing an Email Address from the Suppression List ...................................................
Increasing Throughput ................................................................................................
SMTP Issues ............................................................................................................
SMTP Response Codes .............................................................................................
API Error Codes ........................................................................................................
Enforcement FAQs ....................................................................................................
IP Blacklist FAQ ........................................................................................................
Receiving Email ........................................................................................................................
Email-Receiving Concepts ..................................................................................................
Recipient-Based Control .............................................................................................
IP Address-Based Control ...........................................................................................
Email-Receiving Process ............................................................................................
Getting Started Receiving Email ..........................................................................................
Step 1: Before You Begin ...........................................................................................
Step 2: Verify Your Domain ........................................................................................
Step 3: Set up a Receipt Rule .....................................................................................
Step 4: Send an Email ...............................................................................................
Step 5: View the Received Email .................................................................................
Step 6: Clean Up ......................................................................................................
Setting Up Email Receiving .................................................................................................
Considering Your Use Case ........................................................................................
Verifying Your Domain ...............................................................................................
Publishing an MX Record ...........................................................................................
Giving Permissions ....................................................................................................
Creating IP Address Filters .........................................................................................
Creating a Receipt Rule Set ........................................................................................
Creating Receipt Rules ...............................................................................................
Managing Email Receiving ..................................................................................................
Managing Receipt Rule Sets .......................................................................................
Managing Receipt Rules .............................................................................................
Managing IP Address Filters .......................................................................................
Viewing Error Metrics .................................................................................................
Using Notifications .....................................................................................................
Controlling Access .....................................................................................................................
Creating IAM Policies for Access to Amazon SES ..................................................................
Restricting the Action .................................................................................................
v
213
219
219
219
220
222
224
226
226
227
227
227
228
228
229
229
230
231
231
233
235
236
236
237
238
240
242
245
257
259
259
259
260
261
261
261
262
265
269
269
273
273
273
275
276
276
278
279
279
290
291
293
295
296
297
307
307
308
Restricting Email Addresses ........................................................................................ 308

Restricting General API Usage .................................................................................... 309
Example IAM Policies for Amazon SES ................................................................................ 309
Allowing Full Access to All Amazon SES Actions ............................................................ 309
Allowing Access to Email-Sending Actions Only ............................................................. 310
Restricting the Time Period of Sending ......................................................................... 310
Restricting the Recipient Addresses ............................................................................. 310
Restricting the "From" Address .................................................................................... 311
Restricting the Display Name of the Email Sender .......................................................... 311
Restricting the Destination of Bounce and Complaint Feedback ........................................ 312
Logging API Calls ...................................................................................................................... 313
Amazon SES Information in CloudTrail ................................................................................. 313
Understanding Amazon SES Log File Entries ........................................................................ 314
Using Credentials ...................................................................................................................... 323
Using the API ........................................................................................................................... 326
Query API ........................................................................................................................ 326
Query Requests ........................................................................................................ 326
Request Authentication ............................................................................................... 329
GET and POST Examples .......................................................................................... 329
Query Responses ...................................................................................................... 330
Regions ................................................................................................................................... 332
Amazon SES Endpoints ..................................................................................................... 332
Email Sending Endpoints ............................................................................................ 332
Email Receiving Endpoints .......................................................................................... 333
Selecting a Region ............................................................................................................ 333
Amazon SES API ...................................................................................................... 333
Amazon SES SMTP Interface ..................................................................................... 333
Amazon SES Console ................................................................................................ 333
Sandbox and Sending Limit Increases .................................................................................. 334
Verification ........................................................................................................................ 334
Email Address Verification .......................................................................................... 334
Domain Verification .................................................................................................... 334
Easy DKIM Setup .............................................................................................................. 334
Suppression List ................................................................................................................ 335
Feedback Notifications ....................................................................................................... 335
SMTP Credentials ............................................................................................................. 335
Custom MAIL FROM Domains ............................................................................................ 335
Sending Authorization ........................................................................................................ 336
Email Receiving ................................................................................................................ 336
Limits ....................................................................................................................................... 337
Limits Related to Email Sending .......................................................................................... 337
Sending Limits .......................................................................................................... 337
Message Limits ......................................................................................................... 337
Sender and Recipient Limits ....................................................................................... 338
Limits Related to Email Sending Event Publishing .......................................................... 338
Amazon EC2-Related Limits ........................................................................................ 338
Limits Related to Email Receiving ........................................................................................ 339
General Limits ................................................................................................................... 339
Amazon SES API Limits ............................................................................................. 339
Resources ................................................................................................................................ 340
Appendix .................................................................................................................................. 342
Appendix: Header Fields .................................................................................................... 342
Appendix: Unsupported Attachment Types ............................................................................ 344
Document History ...................................................................................................................... 345

vi

Why use Amazon SES?
What Is Amazon SES?
Welcome to the Amazon Simple Email Service (Amazon SES) Developer Guide. Amazon SES is an
email platform that provides an easy, cost-effective way for you to send and receive email using your
own email addresses and domains.
For example, you can send marketing emails such as special offers, transactional emails such as order
confirmations, and other types of correspondence such as newsletters. When you use Amazon SES
to receive mail, you can develop software solutions such as email autoresponders, email unsubscribe
systems, and applications that generate customer support tickets from incoming emails.
You only pay for what you use, so you can send and receive as much or as little email as you like. For
service highlights, FAQs, and pricing information, go to the Amazon SES Detail Page.
Why use Amazon SES?

Building a large-scale email solution is often a complex and costly challenge for a business. You
must deal with infrastructure challenges such as email server management, network configuration,
and IP address reputation. Additionally, many third-party email solutions require contract and
price negotiations, as well as significant up-front costs. Amazon SES eliminates these challenges
and enables you to benefit from the years of experience and sophisticated email infrastructure
Amazon.com has built to serve its own large-scale customer base.
Amazon SES and other AWS services

Amazon SES integrates seamlessly with other AWS products. For example, you can:
Add email capabilities to any application that runs on an Amazon Elastic Compute Cloud (Amazon
EC2) instance by using the AWS SDKs or the Amazon SES API. If you want to send email through
Amazon SES from an Amazon EC2 instance, you can get started with Amazon SES for free.
Use AWS Elastic Beanstalk to create an email-enabled application such as a program that uses
Amazon SES to send a newsletter to customers.
Set up Amazon Simple Notification Service (Amazon SNS) to notify you of your emails that bounced,
produced a complaint, or were successfully delivered to the recipient's mail server. When you use
Amazon SES to receive emails, your email content can be published to Amazon SNS topics.
1

In this guide
Use the AWS Management Console to set up Easy DKIM, which is a way to authenticate your
emails. Although you can use Easy DKIM with any DNS provider, it is especially easy to set up when
you manage your domain with Amazon Route 53.
Control user access to your email sending by using AWS Identity and Access Management (IAM).
Store emails you receive in Amazon Simple Storage Service (Amazon S3).
Take action on your received emails by triggering AWS Lambda functions.
Use AWS Key Management Service (AWS KMS) to optionally encrypt the mail you receive in your
Amazon S3 bucket.
Use AWS CloudTrail to log Amazon SES API calls that you make using the console or the Amazon
SES API.
Publish your email sending events to Amazon CloudWatch or Amazon Kinesis Firehose. If you
publish your email sending events to Firehose, you can access them in Amazon Redshift, Amazon
Elasticsearch Service, or Amazon S3.
In this guide
This guide contains the following sections:
Section
Description
Sending Email (p. 3)
Describes how you can send email using Amazon SES.
Receiving Email (p. 259)
Describes how you can receive email using Amazon SES.
Controlling Access (p. 307)
Shows you how to use Amazon SES with AWS Identity

and Access Management (IAM) to specify which Amazon
SES API actions a user can perform on which Amazon SES
resources.
Logging API Calls (p. 313)
Provides a list of Amazon SES APIs that can be logged

using AWS CloudTrail.
Using Credentials (p. 323)
Explains the types of credentials that you might use with

Amazon SES, and when you might use them.
Using the API (p. 326)
Describes how to use the Amazon SES Query API.
Regions (p. 332)
Lists the Amazon SES SMTP and API endpoints for the
AWS regions in which Amazon SES is available, and
contains information you need to know when you use
Amazon SES endpoints in multiple regions.
Limits (p. 337)
Provides a list of limits within Amazon SES.
Resources (p. 340)
Lists resources that you may find useful as you work with
Amazon SES
Appendix (p. 342)
Provides supplementary information about header fields,

unsupported attachment types, and scripts.
For technical discussions about various Amazon SES topics, visit the Amazon SES Blog. To browse
and post questions, go to the Amazon SES Forum.

2

How do I send emails using Amazon SES?
Sending Email with Amazon SES

When you send an email, you are sending it through some type of outbound email server. That email
server might be provided by your Internet service provider (ISP), your company's IT department, or
you might have set it up yourself. The email server accepts your email content, formats it to comply
with email standards, and then sends the email out over the Internet. The email may pass through
other servers until it eventually reaches a receiver (an entity, such as an ISP, that receives the email
on behalf of the recipient). The receiver then delivers the email to the recipient. The following diagram
illustrates the basic email-sending process.
When you use Amazon SES, Amazon SES becomes your outbound email server. You can also keep
your existing email server and configure it to send your outgoing emails through Amazon SES so
that you don't have to change any settings in your email clients. The following diagram shows where
Amazon SES fits in to the email sending process.
A sender can generate the email content in different ways. A sender can create the email by using an
email client application, or use a program that automatically generates emails, like an application that
sends order confirmations in response to purchase transactions.
How do I send emails using Amazon SES?

There are several ways that you can send an email by using Amazon SES. You can use the Amazon
SES console, the Simple Mail Transfer Protocol (SMTP) interface, or you can call the Amazon SES
API.
Amazon SES consoleThis method is the quickest way to set up your system and send a couple
of test emails, but once you are ready to start your email campaign, you will use the console
3

How do I start?
primarily to monitor your sending activity. For example, you can quickly view the number of emails
that you have sent and the number of bounces and complaints that you have received.
SMTP InterfaceThere are two ways to access Amazon SES through the SMTP interface. The first
way, which requires no coding, is to configure any SMTP-enabled software to send email through
Amazon SES. For example, you can configure your existing email client or software program to
connect to the Amazon SES SMTP endpoint instead of your current outbound email server.
The second way is to use an SMTP-compatible programming language such as Java and access the
Amazon SES SMTP interface by using the language's built-in SMTP functions and data types.
Amazon SES APIYou can call the Amazon SES Query API directly through HTTPS, or you can
use the AWS Command Line Interface, the AWS Tools for Windows PowerShell, or an AWS SDK.
The AWS SDKs wrap the low-level functionality of the Amazon SES API with higher-level data types
and function calls that take care of the details for you. The AWS SDKs provide not only Amazon SES
operations, but also basic AWS functionality such as request authentication, request retries, and
error handling.
How do I start?
If you are a first-time user of Amazon SES, we recommend that you begin by reading the following
sections:
Amazon SES Quick Start (p. 15)Shows you how to get set up and send a test email as quickly
as possible.
Getting Started Sending Email with Amazon SES (p. 16)Shows you how to send an email by
using the Amazon SES console, the SMTP interface, and an AWS SDK. Examples are provided in
C#, Java, and PHP.
Amazon SES and Deliverability (p. 6)Explains email deliverability concepts that you should be
familiar with when you use Amazon SES.
Amazon SES Email-Sending Process (p. 9)Shows you what happens when you send an email
through Amazon SES.
Email Format and Amazon SES (p. 12)Reviews the format of emails and identifies the
information that you need to provide to Amazon SES.
Then you can learn about sending email with Amazon SES in more detail by reading the sections listed
in the following table:
Section
Description
Setting up Email (p. 37)
Shows you how to sign up for AWS, get your AWS access
keys, download an AWS SDK, verify email addresses or
domains, and move out of the Amazon SES sandbox.
Using the SMTP Interface (p. 56)
Shows you how to get your Amazon SES SMTP

credentials, connect to the Amazon SES SMTP endpoint,
and provides examples of how to configure email clients
and software packages to send email through Amazon
SES. Also explains how to configure your existing email
server to send all outgoing emails through Amazon SES.
Using the API (p. 87)
Shows you how to send formatted and raw emails by using

the Amazon SES API. Explains how to use non-standard
characters and send attachments by using the Multipurpose
Internet Mail Extensions (MIME) standard when you send
raw emails.
4

Concepts
Section
Description
Authenticating Your Email (p. 92)
Shows you how to use DKIM with Amazon SES to show

ISPs that you own the domain you are sending from.
Monitoring Your Sending

Activity (p. 103)
Shows you how to view your usage statistics (such as

the number of deliveries, bounces, and complaints) and
sending limits by using the Amazon SES console or by
calling the Amazon SES API. Also shows you how to
receive bounce and complaint notifications by email, and
how to receive bounce, complaint, and delivery notifications
by setting up Amazon SNS notifications.
Managing Your Sending

Limits (p. 192)
Explains the two Amazon SES sending limits (sending

quota and maximum send rate), how to increase them, and
the errors you receive when you try to exceed them.
Improving Deliverability (p. 227)
Provides tips about how to improve the percentage of

emails that reach your recipients' inboxes. These include
monitoring your sending activity and taking preventative
measures to keep your bounce and complaint statistics low.
Using Sending Authorization (p. 196)
Shows you how to authorize other users to send emails

from your identities on your behalf.
Using Dedicated IP
Addresses (p. 219)
Helps you decide whether to use shared IP addresses

or lease dedicated IP addresses for your Amazon SES
sending.
Testing Email Sending (p. 224)
Explains how to use the Amazon SES mailbox simulator

to simulate common email scenarios without affecting
your sending statistics such as your bounce and complaint
metrics. The scenarios you can test are successful delivery,
bounce, complaint, out-of-the-office (OOTO), and address
on the suppression list.
Troubleshooting (p. 229)
Explains common causes of delivery problems and

provides descriptions of common Amazon SES exceptions
and SMTP response codes.
Amazon SES Email-Sending Concepts

The following sections contain fundamental information about how Amazon SES sends your mail.
Amazon SES and Deliverability (p. 6)
Amazon SES Email-Sending Process (p. 9)
Email Format and Amazon SES (p. 12)
5

Amazon SES and Deliverability

You want your recipients to read your emails, find them valuable, and not label them as spam. In other
words, you want to maximize email deliverabilitythe percentage of your emails that arrive in your
recipients' inboxes. This topic reviews email deliverability concepts that you should be familiar with
when you use Amazon SES.
To maximize email deliverability, you need to understand email delivery issues, proactively take
steps to prevent them, stay informed of the status of the emails that you send, and then improve your
email-sending program, if necessary, to further increase the likelihood of successful deliveries. The
following sections review the concepts behind these steps and how Amazon SES helps you through
the process.
Understand Email Delivery Issues

In most cases, your messages are delivered successfully to recipients who expect them. In some
cases, however, a delivery might fail, or a recipient might not want to receive the mail that you are
sending. Bounces, complaints, and the suppression list are related to these delivery issues and are
described in the following sections.
Bounce
If your recipient's receiver (for example, an ISP) fails to deliver your message to the recipient, the
receiver bounces the message back to Amazon SES. Amazon SES then notifies you of the bounced
6

email through email or through Amazon Simple Notification Service (Amazon SNS), depending
on how you have your system set up. For more information, see Monitoring Using Amazon SES
Notifications (p. 106).
There are hard bounces and soft bounces, as follows:
Hard bounce A persistent email delivery failure. For example, the mailbox does not exist.
Amazon SES does not retry hard bounces, with the exception of DNS lookup failures. We strongly
recommend that you do not make repeated delivery attempts to email addresses that hard bounce.
Soft bounce A temporary email delivery failure. For example, the mailbox is full, there are too
many connections (also called throttling), or the connection times out. Amazon SES retries soft
bounces multiple times. If the email still cannot be delivered, then Amazon SES stops retrying it.
Amazon SES notifies you of hard bounces and soft bounces that will no longer be retried. However,
only hard bounces count toward your bounce rate and the bounce metric that you retrieve using the
Amazon SES console or the GetSendStatistics API.
Bounces can also be synchronous or asynchronous. A synchronous bounce occurs while the email
servers of the sender and receiver are actively communicating. An asynchronous bounce occurs when
a receiver initially accepts an email message for delivery and then subsequently fails to deliver it to the
recipient.
Complaint
Most email client programs provide a button labeled "Mark as Spam," or similar, which moves the
message to a spam folder, and forwards it to the ISP. Additionally, most ISPs maintain an abuse
address (e.g., [email protected]), where users can forward unwanted email messages and request
that the ISP take action to prevent them. In both of these cases, the recipient is making a complaint.
If the ISP concludes that you are a spammer, and Amazon SES has a feedback loop set up with the
ISP, then the ISP will send the complaint back to Amazon SES. When Amazon SES receives such a
complaint, it forwards the complaint to you either by email or by using an Amazon SNS notification,
depending on how you have your system set up. For more information, see Monitoring Using Amazon
SES Notifications (p. 106). We recommend that you do not make repeated delivery attempts to email
addresses that generate complaints.
Suppression List
The Amazon SES suppression list is a list of recipient email addresses that have recently caused a
hard bounce for any Amazon SES customer. If you try to send an email through Amazon SES to an
address that is on the suppression list, the call to Amazon SES succeeds, but Amazon SES treats
the email as a hard bounce instead of attempting to send it. Like any hard bounce, suppression list
bounces count towards your sending quota and your bounce rate. An email address can remain on the
suppression list for up to 14 days. If you are sure that the email address that you're trying to send to
is valid, you can submit a suppression list removal request. For more information, see Removing an
Email Address from the Amazon SES Suppression List (p. 236).
Be Proactive
One of the biggest issues with email on the Internet is unsolicited bulk email, or spam. ISPs take
considerable measures to prevent their customers from receiving spam. Correspondingly, Amazon
SES takes proactive steps to decrease the likelihood that ISPs consider your email to be spam.
Amazon SES uses verification, authentication, sending limits, and content filtering. Amazon SES also
maintains a trusted reputation with ISPs and requires you to send high-quality email. Amazon SES
does some of those things for you automatically (like content filtering); in other cases, it provides the
tools (like authentication), or guides you in the right direction (sending limits). The following sections
provide more information about each concept.
7

Verification
Unfortunately, it's possible for a spammer to falsify an email header and spoof the originating email
address so that it appears as though the email originated from a different source. To maintain trust
between ISPs and Amazon SES, Amazon SES needs to ensure that its senders are who they
say they are. You are therefore required to verify all email addresses from which you send emails
through Amazon SES to protect your sending identity. You can verify email addresses by using the
Amazon SES console or by using the Amazon SES API. You can also verify entire domains. For
more information, see Verifying Email Addresses in Amazon SES (p. 39) and Verifying Domains in
Amazon SES (p. 41).
If your account is still in the Amazon SES sandbox, you also need to verify all recipient addresses
except for addresses provided by the Amazon SES mailbox simulator. For information about getting
out of the sandbox, see Moving Out of the Amazon SES Sandbox (p. 54). For more information
about the mailbox simulator, see Testing Amazon SES Email Sending (p. 224).
Authentication
Authentication is another way that you can indicate to ISPs that you are who you say you are. When
you authenticate an email, you provide evidence that you are the owner of the account and that
your emails have not been modified in transit. In some cases, ISPs refuse to forward email that is
not authenticated. Amazon SES supports two methods of authentication: Sender Policy Framework
(SPF) and DomainKeys Identified Mail (DKIM). For more information, see Authenticating Your Email in
Amazon SES (p. 92).
Sending Limits
If an ISP detects sudden, unexpected spikes in the volume or rate of your emails, the ISP might
suspect you are a spammer and block your emails. Therefore, every Amazon SES account has a set
of sending limits to regulate the number of email messages that you can send and the rate at which
you can send them. These sending limits help you to gradually ramp up your sending activity to protect
your trustworthiness with ISPs.
Amazon SES has two sending limits: a sending quota (the maximum number of messages you can
send in a 24-hour period) and a maximum send rate (the maximum number of emails that Amazon
SES can accept from your account per second, although the actual rate at which Amazon SES accepts
your messages might be less than the maximum send rate). If you are a brand-new user, Amazon SES
lets you send a small amount of email each day. If the mail that you send is acceptable to ISPs, this
limit will gradually increase. Over time, your sending limits will steadily increase so that you can send
larger quantities of email at faster rates. You can also file an SES Sending Limits Increase case to get
your quotas increased if you need them to ramp up more quickly.
For more information about sending limits and how to increase them, see Managing Your Amazon SES
Sending Limits (p. 192).
Content Filtering
Many ISPs use content filtering to determine if incoming emails are spam. Content filters look for
questionable content and block the email if the email fits the profile of spam. Amazon SES uses
content filters also. When your application sends a request to Amazon SES, Amazon SES assembles
an email message on your behalf and then scans the message header and body to determine if they
contain content that ISPs might construe as spam. If your messages look like spam to the content
filters that Amazon SES uses, your reputation with Amazon SES will be negatively affected. If a
message is infected with a virus, it is rejected by Amazon SES entirely.
Reputation
When it comes to email sending, reputationa measure of confidence that an IP address, email
address, or sending domain is not the source of spamis important. Amazon SES maintains a strong
reputation with ISPs so that ISPs deliver your emails to your recipients' inboxes. Similarly, you need
8

Email-Sending Process
to maintain a trusted reputation with Amazon SES. You build your reputation with Amazon SES by
sending high-quality content. When you send high-quality content, your reputation becomes more
trusted over time and Amazon SES increases your sending limits. Excessive bounces and complaints
negatively impact your reputation and can cause Amazon SES to lower your sending limits or terminate
your Amazon SES account.
One way to help maintain your reputation is to use the mailbox simulator when you test your system,
instead of sending to email addresses that you have created yourself. Emails to the mailbox simulator
do not count toward your bounce and complaint metrics. For more information about the mailbox
simulator, see Testing Amazon SES Email Sending (p. 224).
High-Quality Email
High-quality email is email that recipients find valuable and want to receive. Value means different
things to different recipients and can come in the form of offers, order confirmations, receipts,
newsletters, etc. Ultimately, your deliverability rests on the quality of the emails that you send because
ISPs block emails that they find to be low quality (spam). For more information about how to send highquality email, see Improving Deliverability with Amazon SES (p. 227) and the Amazon Simple Email
Service Email Sending Best Practices whitepaper.
Stay Informed
Whether your deliveries fail, your recipients complain about your emails, or Amazon SES successfully
delivers an email to a recipient's mail server, Amazon SES helps you to track down the issue by
providing notifications and by enabling you to easily monitor your usage statistics.
Notifications
When an email bounces, the ISP notifies Amazon SES, and Amazon SES notifies you. Amazon SES
notifies you of hard bounces and soft bounces that Amazon SES will no longer retry. Many ISPs also
forward complaints, and Amazon SES sets up complaint feedback loops with the major ISPs so you
don't have to. Amazon SES can notify you of bounces, complaints, and successful deliveries in two
ways: you can set your account up to receive notifications through Amazon SNS, or you can receive
notifications by email (bounces and complaints only). For more information, see Monitoring Using
Amazon SES Notifications (p. 106).
Usage Statistics
Amazon SES provides usage statistics so that you can view your failed deliveries to determine and
resolve the root causes. You can view your usage statistics by using the Amazon SES console or by
calling the Amazon SES API. You can view how many deliveries, bounces, complaints, and virusinfected rejected emails you have, and you can also view your sending limits to ensure that you stay
within them.
Improve Your Email-Sending Program

If you are getting large numbers of bounces and complaints, it's time to reassess your email-sending
strategy. Remember that excessive bounces, complaints, and attempts to send low-quality email
constitute abuse and put your AWS account at risk of termination. Ultimately, you need to be sure that
you use Amazon SES to send high-quality emails and to only send emails to recipients who want to
receive them. For more information, see Improving Deliverability with Amazon SES (p. 227) and the
Amazon Simple Email Service Email Sending Best Practices whitepaper.
Amazon SES Email-Sending Process

This topic describes what happens when you send an email with Amazon SES, and the various
outcomes that can occur after the email is sent. The following figure is a high-level overview of the
sending process:
9

1.
A client application, acting as an email sender, makes a request to Amazon SES to send email to
one or more recipients.
2.
If the request is valid, Amazon SES accepts the email and sends it over the Internet to the
recipient's receiver. Once the message is passed to Amazon SES, it is usually sent immediately,
with the first delivery attempt normally occurring within milliseconds.
3.
At this point, there are different possibilities. For example:

a.
b.
c.
The ISP successfully delivers the message to the recipient's inbox.

The recipient's email address does not exist, so the ISP sends a bounce notification to
Amazon SES. Amazon SES then forwards the notification to the sender.
The recipient receives the message but considers it to be spam and registers a complaint with
the ISP. The ISP, which has a feedback loop set up with Amazon SES, sends the complaint to
Amazon SES, which then forwards it to the sender.
The following sections review the individual possible outcomes after a sender sends an email request
to Amazon SES and after Amazon SES sends an email message to the recipient.
After a Sender Sends an Email Request to Amazon SES

When the sender makes a request to Amazon SES to send an email, the call may succeed or fail. The
following sections describe what happens in each case.
Successful Sending Request

If the request to Amazon SES succeeds, Amazon SES returns a success response to the sender.
This message includes the message ID, a string of characters that uniquely identifies the request.
You can use the message ID to identify the sent email or to track problems encountered during
sending. Amazon SES then assembles an email message based on the request parameters, scans the
message for questionable content and viruses and then sends it out over the Internet using Simple Mail
Transfer Protocol (SMTP). Your message is usually sent immediately; the first delivery attempt typically
occurs within milliseconds.
Note
If Amazon SES successfully accepts the sender's request and then an Amazon SES content
filter finds that the message contains a virus, Amazon SES drops the message and notifies
the sender by email.
Failed Sending Request

If the sender's email-sending request to Amazon SES fails, Amazon SES responds to the sender with
an error and drops the email. The request could fail for several reasons. For example, the request may
not be formatted properly or the email address may not have been verified by the sender.
10

The method through which you can determine if the request has failed depends on how you call
Amazon SES. The following are examples of how errors and exceptions are returned:
If you are calling Amazon SES through the Query (HTTPS) API (SendEmail or SendRawEmail),
the actions will return an error. For more information, see the Amazon Simple Email Service API
Reference.
If you are using an AWS SDK for a programming language that uses exceptions, the call to Amazon
SES will throw a MessageRejectedException. (The name of the exception may vary slightly
depending on the SDK.)
If you are using the SMTP interface, then the sender receives an SMTP response code, but how the
error is conveyed depends on the sender's client. Some clients may display an error code; others
may not.
For information about errors that can occur when you send an email with Amazon SES, see Amazon
SES Email Sending Errors (p. 231).
After Amazon SES Sends an Email

If the sender's request to Amazon SES succeeds, then Amazon SES sends the email and one of the
following outcomes occurs:
Successful delivery and the recipient does not object to the emailThe email is accepted
by the ISP, and the ISP delivers the email to the recipient. A successful delivery is shown in the
following figure.
Hard bounceThe email is rejected by the ISP because of a persistent condition or rejected by
Amazon SES because the email address is on the Amazon SES suppression list. An email address
is on the Amazon SES suppression list if it has recently caused a hard bounce for any Amazon SES
customer. A hard bounce with an ISP can occur because the recipient's address is invalid. A hard
bounce notification is sent from the ISP back to Amazon SES, which notifies the sender through
email or through Amazon Simple Notification Service (Amazon SNS), depending on the sender's
setup. Amazon SES notifies the sender of suppression list bounces by the same means. The path of
a hard bounce from an ISP is shown in the following figure.
Soft bounceThe ISP cannot deliver the email to the recipient because of a temporary condition,
such as the ISP is too busy to handle the request or the recipient's mailbox is full. A soft bounce can
also occur if the domain does not exist. The ISP sends a soft bounce notification back to Amazon
SES, or, in the case of a nonexistent domain, Amazon SES cannot find an email server for the
domain. In either case, Amazon SES retries the email for an extended period of time. If Amazon
SES cannot deliver the email in that time period, it sends you a bounce notification through email
or through Amazon SNS. If Amazon SES can deliver the email to the recipient during a retry, the
delivery is successful. A soft bounce is shown in the following figure. In this case, Amazon SES
retries sending the email, and the ISP is eventually able to deliver it to the recipient.

11

Email Format and Amazon SES
ComplaintThe email is accepted by the ISP and delivered to the recipient, but the recipient
considers the email to be spam and clicks a button such as "Mark as spam" in his or her email client.
If Amazon SES has a feedback loop set up with the ISP, then a complaint notification is sent to
Amazon SES, which forwards the complaint notification to the sender. Most ISPs do not provide
the email address of the recipient who submitted the complaint, so the complaint notification from
Amazon SES provides the sender a list of recipients who might have sent the complaint, based on
the recipients of the original message and the ISP from which Amazon SES received the complaint.
The path of a complaint is shown in the following figure.
Auto responseThe email is accepted by the ISP, and the ISP delivers it to the recipient. The ISP
then sends an automatic response such as an out-of-the-office (OOTO) message to Amazon SES.
Amazon SES forwards the auto response notification to the sender. An auto response is shown in
the following figure.
Make sure that your Amazon SES-enabled program does not retry sending messages that generate
an auto response.
Tip
You can use the Amazon SES mailbox simulator to test a successful delivery, bounce,
complaint, OOTO, or what happens when an address is on the suppression list. For more
information, see Testing Amazon SES Email Sending (p. 224).

When a client makes a request to Amazon SES, Amazon SES constructs an email message compliant
with the Internet Message Format specification (RFC 5322). An email consists of a header, a body, and
an envelope, as described below.
HeaderContains routing instructions and information about the message. Examples are the
sender's address, the recipient's address, the subject, and the date. The header is analogous to the
information at the top of a postal letter, though it can contain many other types of information, such
as the format of the message.
BodyContains the text of the message itself.
EnvelopeContains the actual routing information that is communicated between the email client
and the mail server during the SMTP session. This email envelope information is analogous to the
information on a postal envelope. The routing information of the email envelope is usually the same
as the routing information in the email header, but not always. For example, when you send a blind
carbon copy (BCC), the actual recipient address (derived from the envelope) is not the same as the
"To" address that is displayed in the recipient's email client, which is derived from the header.
12

The following is a simple example of an email. The header is followed by a blank line and then the
body of the email. The envelope isn't shown because it is communicated between the client and the
mail server during the SMTP session, rather than a part of the email itself.
Received: from abc.smtp-out.amazonses.com (123.45.67.89) by in.example.com

(87.65.43.210); Fri, 17 Dec 2010 14:26:22
From: "Andrew" <[email protected]>;
To: "Bob" <[email protected]>
Date: Fri, 17 Dec 2010 14:26:21 -0800
Subject: Hello
Message-ID: <[email protected]>
Accept-Language: en-US
Content-Language: en-US
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
Hello, I hope you are having a good day.
-Andrew
The following sections review email headers and bodies and identify the information that you need to
provide when you use Amazon SES.
Email Header
There is one header per email message. Each line of the header contains a field followed by a colon
followed by a field body. When you read an email in an email client, the email client typically displays
the values of the following header fields:
ToThe email addresses of the message's recipients.
CCThe email addresses of the message's carbon copy recipients.
FromThe email address from which the email is sent.
SubjectA summary of the message topic.
DateThe time and date the email is sent.
There are many additional header fields that provide routing information and describe the content of
the message. Email clients typically do not display these fields to the user. For a full list of the header
fields that Amazon SES accepts, see Appendix: Header Fields (p. 342). When you use Amazon SES,
you particularly need to understand the difference between "From," "Reply-To," and "Return-Path"
header fields. As noted previously, the "From" address is the email address of the message sender,
whereas "Reply-To" and "Return-Path" are as follows:
Reply-ToThe email address to which replies will be sent. By default, replies are sent to the original
sender's email address.
Return-PathThe email address to which message bounces and complaints should be sent.
"Return-Path" is sometimes called "envelope from," "envelope sender," or "MAIL FROM."
Note
When you use Amazon SES, we recommend that you always set the "Return-Path"
parameter so that you can be aware of bounces and take corrective action if they occur.
To easily match a bounced message with its intended recipient, you can use Variable Envelope Return
Path (VERP). With VERP, you set a different "Return-Path" for each recipient, so that if the message
13

bounces back, you automatically know which recipient it bounced from, rather than having to open the
bounce message and parse it.
Email Body
The email body contains the text of the message. The body can be sent in the following formats:
HTMLIf the recipient's email client can interpret HTML, the body can include formatted text and
hyperlinks
Plain textIf the recipient's email client is text-based, the body must not contain any nonprintable
characters.
Both HTML and plain textWhen you use both formats to send the same content in a single
message, the recipient's email client decides which to display, based upon its capabilities.
If you are sending an email message to a large number of recipients, then it makes sense to send
it in both HTML and text. Some recipients will have HTML-enabled email clients, so that they can
click embedded hyperlinks in the message. Recipients using text-based email clients will need you to
include URLs that they can copy and open using a web browser.
Email Information You Need to Provide to Amazon SES

When you send an email with Amazon SES, the email information you need to provide depends on
how you call Amazon SES. You can provide a minimal amount of information and have Amazon SES
take care of all of the formatting for you. Or, if you want to do something more advanced like send an
attachment, you can provide the raw message yourself. The following sections review what you need
to provide when you send an email by using the Amazon SES API, the Amazon SES SMTP interface,
or the Amazon SES console.
Amazon SES API

If you call the Amazon SES API directly, you call either the SendEmail or the SendRawEmail API.
The amount of information you need to provide depends on which API you call.
The SendEmail API requires you to provide only a source address, destination address, message
subject, and a message body. You can optionally provide "Reply-To" addresses. When you call this
API, Amazon SES automatically assembles a properly formatted multi-part Multipurpose Internet
Mail Extensions (MIME) email message optimized for display by email client software. For more
information, see Sending Formatted Email Using the Amazon SES API (p. 88).
The SendRawEmail API provides you the flexibility to format and send your own raw email message
by specifying headers, MIME parts, and content types. SendRawEmail is typically used by advanced
users. You need to provide the body of the message and all header fields that are specified as
required in the Internet Message Format specification (RFC 5322). For more information, see
Sending Raw Email Using the Amazon SES API (p. 88).
If you use an AWS SDK to call the Amazon SES API, you provide the information listed above to the
corresponding functions (for example, SendEmail and SendRawEmail for Java).
For more information about sending email using the Amazon SES API, see Using the Amazon SES
API to Send Email (p. 87).
Amazon SES SMTP Interface

When you access Amazon SES through the SMTP interface, your SMTP client application assembles
the message, so the information you need to provide depends on the application you are using. At a
minimum, the SMTP exchange between a client and a server requires a source address, a destination
14

Quick Start
address, and message data. If you are using the SMTP interface and have feedback forwarding
enabled, then your bounces, complaints, and delivery notifications are sent to the "MAIL FROM"
address. Any "Reply-To" address that you specify is not used.
For more information about sending email using the Amazon SES SMTP interface, see Using the
Amazon SES SMTP Interface to Send Email (p. 56).
Amazon SES Console

When you send an email by using the Amazon SES console, the amount of information you need to
provide depends on whether you choose to send a formatted or raw email.
To send a formatted email, you need to provide a source address, a destination address, a message
subject, and a message body. Amazon SES automatically assembles a properly formatted multi-part
MIME email message optimized for display by email client software. You can also specify a reply-to
and a return path field.
To send a raw email, you provide the source address, a destination address, and the message
content, which must contain the body of the message and all header fields that are specified as
required in the Internet Message Format specification (RFC 5322).
Amazon SES Quick Start

This procedure leads you through the steps to sign up for AWS, verify your email address, send your
first email, consider how you will handle bounces and complaints, and move out of the Amazon Simple
Email Service (Amazon SES) sandbox.
Use this procedure if you:
Are just experimenting with Amazon SES.
Want to send some test emails without doing any programming.
Want to get set up in as few steps as possible.
Step 1: Sign up for AWS

Before you can use Amazon SES, you need to sign up for AWS. When you sign up for AWS, your
account is automatically signed up for all AWS services.
For instructions, see Signing up for AWS (p. 38).
Step 2: Verify your email address

Before you can send email from your email address through Amazon SES, you need to show Amazon
SES that you own the email address by verifying it.
For instructions, see Verifying Email Addresses in Amazon SES (p. 39).
Step 3: Send your first email

You can send an email simply by using the Amazon SES console. As a new user, your account is in a
test environment called the sandbox, so you can only send email to and from email addresses that you
have verified.
For instructions, see Send an Email Using the Amazon SES Console (p. 17).
15

Step 4: Consider how you will
handle bounces and complaints
Step 4: Consider how you will handle bounces and

complaints
Before the next step, you need to think about how you will handle bounces and complaints. If you are
sending to a small number of recipients, your process can be as simple as examining the bounce and
complaint feedback that you receive by email, and then removing those recipients from your mailing
list.
For more information, see Processing Bounces and Complaints (p. 228).
Step 5: Move out of the Amazon SES sandbox

To be able to send emails to unverified email addresses and to raise the number of emails you can
send per day and how fast you can send them, your account needs to be moved out of the sandbox.
This process involves opening an SES Sending Limits Increase case in Support Center.
For more information about the sandbox restrictions and how to apply to move out of the sandbox, see
Moving Out of the Amazon SES Sandbox (p. 54).
Next steps
After you send a few test emails to yourself, use the Amazon SES mailbox simulator for further
testing because emails to the mailbox simulator do not count towards your sending quota or your
bounce and complaint rates. For more information on the mailbox simulator, see Testing Amazon
SES Email Sending (p. 224).
Monitor your sending activity, such as the number of emails that you have sent and the number that
have bounced or received complaints. For more information, see Monitoring Your Amazon SES
Sending Activity (p. 103).
Verify entire domains so that you can send email from any email address in your domain without
verifying addresses individually. For more information, see Verifying Domains in Amazon
SES (p. 41).
Increase the chance that your emails will be delivered to your recipients' inboxes instead of junk
boxes by authenticating your emails. For more information, see Authenticating Your Email in
Amazon SES (p. 92).
Getting Started Sending Email with Amazon SES

This getting started tutorial provides step-by-step instructions for you to set up Amazon Simple Email
Service (Amazon SES) and send an email. First, review the information in Before You Begin with
Amazon SES (p. 17). Then, send an email in one of the following ways. You can also watch our
Getting Started with Amazon SES video.
For information about Amazon SES email pricing, see the Amazon SES Pricing page.
Using the Amazon SES Console

Use this method if you want to get started sending test emails through Amazon SES with minimal
setup. When you are ready to start your production email sending campaign, you will want to move
16

Using Simple Mail Transfer Protocol (SMTP)
on to one of the other sending methods and use the Amazon SES console primarily to monitor your
sending activity.
To start this tutorial, go to Send an Email Using the Amazon SES Console (p. 17).
Using Simple Mail Transfer Protocol (SMTP)

Use this method if you want to send email through the Amazon SES SMTP interface with or without
programming as follows:
Enable an application to send email through Amazon SES by using a programming language that
supports SMTP. Examples are provided in C#, Java, and PHP. To start this tutorial, go to Send an
Email by Accessing the Amazon SES SMTP Interface Programmatically (p. 19).
Set up your mail server to forward mail to Amazon SES, or configure your email client or SMTPenabled software package to send email through Amazon SES. Examples are provided for Postfix,
Sendmail, and Exim mail servers as well as email client Microsoft Outlook and issue-tracking
software Jira. To start this tutorial, go to Configuring Your Existing Email Server or SMTP-Enabled
Application to Send Email Through Amazon SES (p. 28).
For introductory information on both SMTP sending methods, see Send an Email Through Amazon
SES Using SMTP (p. 19).
Using an AWS SDK

Use this method to call the Amazon SES API using libraries that handle the details of the underlying
Amazon SES Query interface. Examples are provided in C#, Java, and PHP. To start this tutorial, go to
Send an Email Through Amazon SES Using an AWS SDK (p. 28).
Before You Begin with Amazon SES

Before you get started, you need to set up Amazon SES. Whether you send an email by using the
Amazon SES console, the SMTP interface, or the Amazon SES API, you need to:
Sign up for AWSBefore you can use Amazon SES or other AWS services, you need to create an
AWS account. For information, see Signing up for AWS (p. 38).
Verify your email address or domain To send emails using Amazon SES, you always need
to verify your "From" address to show that you own it. If you are in the sandbox, you also need to
verify your "To" addresses. You can verify email addresses or entire domains. For information, see
Verifying Email Addresses and Domains in Amazon SES (p. 39).
This list contains the setup tasks that are mandatory for all email sending methods. Additional setup
tasks that are specific to the email sending method are given in the corresponding getting started
section. To see a complete list of all setup tasks, see Setting up Email with Amazon SES (p. 37).
Send an Email Using the Amazon SES Console

The easiest way to send an email with Amazon SES is to use the Amazon SES console. Because
the console requires you to manually enter information, you will typically only use it to send a few test
17

Send an Email Using the Console
emails. After you get started with Amazon SES, you will want to send your emails using either the
Amazon SES SMTP interface or API, but the console is still useful for monitoring your sending activity.
Important
In this getting started tutorial, you send an email to yourself so that you can check to see if
you received it. For further experimentation or load testing, use the Amazon SES mailbox
simulator. Emails that you send to the mailbox simulator do not count toward your sending
quota or your bounce and complaint rates. For more information, see Testing Amazon SES
Email Sending (p. 224).
Before you follow these steps, make sure you review the setup instructions in Before You Begin with
Amazon SES (p. 17).
To send an email message from the Amazon SES console

1.
Sign in to the AWS Management Console and open the Amazon SES console at Amazon SES
console. If you are not currently signed into your AWS account, this link will take you to a sign-in
page. After you sign in, you will be directed to the Amazon SES console.
2.
In the Navigation pane of the Amazon SES console, under Identity Management, choose Email
Addresses to view the email address that you verified in Verifying Email Addresses in Amazon
SES (p. 39).
3.
In the list of identities, select the checkbox of an email address that you have verified.
4.
Choose Send a Test Email.
5.
In the Send Test Email dialog box, choose the Email Format. The two choices are as follows:
FormattedThis is the simplest option. Choose this if you simply want to type the text of your
message into the Body text box. When you send the email, Amazon SES will put the text into
email format for you.
RawChoose this option if you want to send a more complex message, such as a message
that includes HTML or an attachment. Because of this flexibility, you will need to format the
message as described in Sending Raw Email Using the Amazon SES API (p. 88) yourself,
and then paste the entire formatted message, including the headers, into the Body text box.
You can use the following example, which contains HTML, to send a test email using the Raw
email format. Copy and paste this message in its entirety into the Body text box. Ensure that
there is not a blank line between the MIME-Version header and the Content-Type header,
because that would cause the email to be formatted as plain text instead of HTML.
Subject: Amazon SES Raw Email Test
MIME-Version: 1.0
Content-Type: text/html
<!DOCTYPE html>
<html>
<body>
<h1>This text should be large, because it is formatted as a header in
HTML.</h1>
<p>Here is a formatted link: <a href="http://docs.aws.amazon.com/
ses/latest/DeveloperGuide/Welcome.html">Amazon Simple Email Service
Developer Guide</a>.</p>
</body>
</html>
6.
In the Send Test Email dialog box, fill out the rest of the fields. If you are still in the Amazon SES
sandbox, make sure that you have verified the address in the To field. For more information, see
Verifying Email Addresses in Amazon SES (p. 39).
7.
Choose Send Test Email.

18

Send an Email Using SMTP
8.
Sign in to the email client of the address you sent the email to. You will find the message that you
sent.
Send an Email Through Amazon SES Using SMTP

To send an email using the Amazon SES SMTP interface, you can use an SMTP-enabled
programming language, email server, or application. Before you start, review the instructions in Before
You Begin with Amazon SES (p. 17). You also need to obtain the following additional information:
Your Amazon SES SMTP username and password, which enable you to connect to the Amazon
SES SMTP endpoint. To get your Amazon SES SMTP username and password, see Obtaining Your
Amazon SES SMTP Credentials (p. 57).
Important
Your SMTP credentials are different from your AWS credentials. For more information about
credentials, see Using Credentials With Amazon SES (p. 323).
The Amazon SES SMTP hostname, which is email-smtp.us-east-1.amazonaws.com (for region
us-east-1), email-smtp.us-west-2.amazonaws.com (for region us-west-2), or email-smtp.euwest-1.amazonaws.com (for region eu-west-1).
The Amazon SES SMTP interface port number, which depends on the connection method. For more
information, see Connecting to the Amazon SES SMTP Endpoint (p. 61).
After you have obtained your SMTP credentials, you can connect to the Amazon SES SMTP endpoint
and start sending email. This getting started tutorial shows you how to send email through the Amazon
SES SMTP interface by using the following methods:
Send an Email by Accessing the Amazon SES SMTP Interface Programmatically (p. 19)
Configuring Your Existing Email Server or SMTP-Enabled Application to Send Email Through
Amazon SES (p. 28)
For more information about the Amazon SES SMTP interface, see Using the Amazon SES SMTP
Interface to Send Email (p. 56).
Send an Email by Accessing the Amazon SES SMTP Interface

Programmatically
You can access the Amazon SES SMTP interface by using an SMTP-enabled programming language.
You provide the Amazon SES SMTP hostname and port number along with your SMTP credentials
and then use the programming language's generic SMTP functions to send the email.
Review Send an Email Through Amazon SES Using SMTP (p. 19) and then select one of the
following tutorials:
Send an Email Through the Amazon SES SMTP Interface with C# (p. 19)
Send an Email Through the Amazon SES SMTP Interface with Java (p. 22)
Send an Email Through the Amazon SES SMTP Interface with PHP (p. 26)
Send an Email Through the Amazon SES SMTP Interface with C#

The following procedure shows you how to use Microsoft Visual Studio to create a console application
and modify the C# code to send an email through Amazon SES. The process to create a new project
based on a project template that is similar across Microsoft Visual Studio editions, but we'll go through
the procedure using Microsoft Visual Studio Professional 2012.
19

Before you perform the following procedure, complete the setup tasks described in Before You Begin
with Amazon SES (p. 17) and Send an Email Through Amazon SES Using SMTP (p. 19).
Important
To send an email using the Amazon SES SMTP interface with C#

1.
2.
Create a console project in Visual Studio by performing the following steps:

a.
Open Microsoft Visual Studio.
b.
Choose File, choose New, and then choose Project.
c.
In the New Project dialog box, in the left pane, expand Installed, expand Templates, and
then expand Visual C#.
d.
Under Visual C#, choose Windows.
e.
Choose Console Application.
f.
In the Name field, type AmazonSESSample. The dialog box should look similar to the
following figure.
g. Choose OK.
In your Visual Studio project, replace the entire contents of Program.cs with the following code:
using System;
namespace AmazonSESSample
{
class Program
{
static void Main(string[] args)
{
20

const String FROM = "[email protected]";

your "From" address. This address must be verified.
const String TO = "[email protected]";
"To" address. If your account is still in the
// Replace with
// Replace with a
// sandbox, this
address must be verified.

const String SUBJECT = "Amazon SES test (SMTP interface
accessed using C#)";
const String BODY = "This email was sent through the Amazon
SES SMTP interface by using C#.";
// Supply your SMTP credentials below. Note that your SMTP
credentials are different from your AWS credentials.
const String SMTP_USERNAME = "YOUR_SMTP_USERNAME"; // Replace
with your SMTP username.
const String SMTP_PASSWORD = "YOUR_SMTP_PASSWORD"; // Replace
with your SMTP password.
// Amazon SES SMTP host name. This example uses the US West
(Oregon) region.
const String HOST = "email-smtp.us-west-2.amazonaws.com";
// The port you will connect to on the Amazon SES SMTP
endpoint. We are choosing port 587 because we will use
// STARTTLS to encrypt the connection.
const int PORT = 587;
// Create an SMTP client with the specified host name and
port.
using (System.Net.Mail.SmtpClient client = new
System.Net.Mail.SmtpClient(HOST, PORT))
{
// Create a network credential with your SMTP user name
and password.
client.Credentials = new
System.Net.NetworkCredential(SMTP_USERNAME, SMTP_PASSWORD);
// Use SSL when accessing Amazon SES. The SMTP session
will begin on an unencrypted connection, and then
// the client will issue a STARTTLS command to upgrade to
an encrypted connection using SSL.
client.EnableSsl = true;
// Send the email.
try
{
Console.WriteLine("Attempting to send an email through
the Amazon SES SMTP interface...");
client.Send(FROM, TO, SUBJECT, BODY);
Console.WriteLine("Email sent!");
}
catch (Exception ex)
{
Console.WriteLine("The email was not sent.");
Console.WriteLine("Error message: " + ex.Message);
}
}

21

Console.Write("Press any key to continue...");

Console.ReadKey();
}
}
}
3.
In Program.cs, replace the following email addresses with your own values:
Important
The email addresses are case-sensitive. Make sure that the addresses are exactly the
same as the ones you verified.
[email protected] with your "From" email address. You must verify this
address before you run this program. For more information, see Verifying Email Addresses and
Domains in Amazon SES (p. 39).
[email protected] with your "To" email address. If your account is still in
the sandbox, you must verify this address before you use it. For more information, see Moving
Out of the Amazon SES Sandbox (p. 54).
4.
In Program.cs, replace the following SMTP credentials with the values that you obtained in
Obtaining Your Amazon SES SMTP Credentials (p. 57):
Important
Your SMTP credentials are different from your AWS credentials. For more information
about credentials, see Using Credentials With Amazon SES (p. 323).
YOUR_SMTP_USERNAMEReplace with your SMTP username. Note that your SMTP
username credential is a 20-character string of letters and numbers, not an intelligible name.
YOUR_SMTP_PASSWORDReplace with your SMTP password.
5.
(Optional) If you want to use an Amazon SES SMTP endpoint in a region other than US West
(Oregon), you need to change HOST in Program.cs to the endpoint you want to use. For a list of
Amazon SES endpoints, see Regions and Amazon SES (p. 332).
6.
Save Program.cs.
7.
To build the project, choose Build and then choose Build Solution.
8.
To run the program, choose Debug and then choose Start Debugging.
9.
Review the program's console output to verify that the sending was successful. (You should see
"Email sent!")
10. Log into the email client of the recipient address. You will find the message that you sent.
Send an Email Through the Amazon SES SMTP Interface with Java
This example uses Eclipse IDE for Java EE Developers and the JavaMail API to send email through
Amazon SES using the SMTP interface. The JavaMail API is included in the Java EE Platform and is
available as an optional package for use with the Java SE Platform. If you do not have the JavaMail
API installed, install it from JavaMail.
Important
This tutorial requires JavaMail 1.5 or above.
Before you perform the following procedure, complete the setup tasks described in Before You Begin
with Amazon SES (p. 17) and Send an Email Through Amazon SES Using SMTP (p. 19).
Important
22

To send an email using the Amazon SES SMTP interface with Java
1.
Create a project in Eclipse by performing the following steps:

a.
Open Eclipse.
b.
In Eclipse, choose File, choose New, and then choose Java Project.
c.
In the Create a Java Project dialog box, type a project name and then choose Next.
d.
In the Java Settings dialog box, choose the Libraries tab.
e.
Choose Add External JARs.
f.
Browse to your installation of JavaMail, choose mail.jar, and then choose Open. The Java
Settings dialog box should now look similar to the following figure:
g.
In the Java Settings dialog box, choose Finish.
2.
In Eclipse, in the Package Explorer window, expand your project.
3.
Under your project, right-click the src directory, choose New, and then choose Class.
4.
In the New Java Class dialog box, in the Name field, type AmazonSESSample and then choose
Finish.
5.
Replace the entire contents of AmazonSESSample.java with the following code:

import java.util.Properties;
import javax.mail.*;
import javax.mail.internet.*;
public class AmazonSESSample {
static final String FROM = "[email protected]";
static final String TO = "[email protected]";
// Replace with
// Replace with a
// sandbox, this

23

static final String BODY = "This email was sent through the Amazon SES
SMTP interface by using Java.";
static final String SUBJECT = "Amazon SES test (SMTP interface
accessed using Java)";
// Supply your SMTP credentials below. Note that your SMTP credentials
are different from your AWS credentials.
static final String SMTP_USERNAME = "YOUR_SMTP_USERNAME"; // Replace
with your SMTP username.
static final String SMTP_PASSWORD = "YOUR_SMTP_PASSWORD"; // Replace
with your SMTP password.
// Amazon SES SMTP host name. This example uses the US West (Oregon)
region.
static final String HOST = "email-smtp.us-west-2.amazonaws.com";
// The port you will connect to on the Amazon SES SMTP endpoint. We
are choosing port 25 because we will use
// STARTTLS to encrypt the connection.
static final int PORT = 25;
public static void main(String[] args) throws Exception {
// Create a Properties object to contain connection configuration
information.
Properties props = System.getProperties();
props.put("mail.transport.protocol", "smtps");
props.put("mail.smtp.port", PORT);
// Set properties indicating that we want to use STARTTLS to encrypt
the connection.
// The SMTP session will begin on an unencrypted connection, and then
the client
// will issue a STARTTLS command to upgrade to an encrypted
connection.
props.put("mail.smtp.auth", "true");
props.put("mail.smtp.starttls.enable", "true");
props.put("mail.smtp.starttls.required", "true");
// Create a Session object to represent a mail session with the
specified properties.
Session session = Session.getDefaultInstance(props);
// Create a message with the specified information.
MimeMessage msg = new MimeMessage(session);
msg.setFrom(new InternetAddress(FROM));
msg.setRecipient(Message.RecipientType.TO, new
InternetAddress(TO));
msg.setSubject(SUBJECT);
msg.setContent(BODY,"text/plain");
// Create a transport.
Transport transport = session.getTransport();
// Send the message.
try
{

24

System.out.println("Attempting to send an email through the

Amazon SES SMTP interface...");
// Connect to Amazon SES using the SMTP username and password
you specified above.
transport.connect(HOST, SMTP_USERNAME, SMTP_PASSWORD);
// Send the email.
transport.sendMessage(msg, msg.getAllRecipients());
System.out.println("Email sent!");
}
catch (Exception ex) {
System.out.println("The email was not sent.");
System.out.println("Error message: " + ex.getMessage());
}
finally
{
// Close and terminate the connection.
transport.close();
}
}
}
6.
In AmazonSESSample.java, replace the following email addresses with your own values:
Important
7.
In AmazonSESSample.java, replace the following SMTP credentials with the values that you
obtained in Obtaining Your Amazon SES SMTP Credentials (p. 57):
Important
Your SMTP credentials are different from your AWS credentials. For more information
about credentials, see Using Credentials With Amazon SES (p. 323).
YOUR_SMTP_USERNAMEReplace with your SMTP username credential. Note that your
SMTP username credential is a 20-character string of letters and numbers, not an intelligible
name.
YOUR_SMTP_PASSWORDReplace with your SMTP password.
8.
(Optional) If you want to use an Amazon SES SMTP endpoint in a region other than US West
(Oregon), you need to change HOST in AmazonSESSample.java to the endpoint you want to use.
For a list of Amazon SES endpoints, see Regions and Amazon SES (p. 332).
9.
Save AmazonSESSample.java.
10. To build the project, choose Project and then choose Build Project. (If this option is disabled,
then you may have automatic building enabled.)
11. To start the program and send the email, choose Run and then choose Run again.
12. Review the program's console output to verify that the sending was successful. (You should see
"Email sent!")
25

Send an Email Through the Amazon SES SMTP Interface with PHP
This example uses the PHP Extension and Application Repository (PEAR) to send email through
Amazon SES using the SMTP interface.
Important
In this tutorial, you send an email to yourself so that you can check to see if you received
it. For further experimentation or load testing, use the Amazon SES mailbox simulator.
Emails that you send to the mailbox simulator do not count toward your sending quota or
your bounce and complaint rates. For more information, see Testing Amazon SES Email
Sending (p. 224).
Prerequisites
Before you begin, perform the following tasks:
Verify your email address with Amazon SES Before you can send an email with Amazon SES,
you must verify that you own the sender's email address. If your account is still in the Amazon SES
sandbox, you must also verify the recipient email address. The easiest way to verify email addresses
is by using the Amazon SES console. For more information, see Verification Procedures (p. 40).
Get your SMTP credentialsYou need an Amazon SES SMTP user name and password to
access the Amazon SES SMTP interface. Your SMTP credentials are not the same as your AWS
credentials. You can find your SMTP credentials by going to the SMTP Settings page of the Amazon
SES console. For more information about SMTP credentials, see Obtaining Your Amazon SES
SMTP Credentials (p. 57).
Install PHPPHP is available at http://php.net/downloads.php. After you install PHP, add the path
to PHP in your environment variables so that you can run PHP from any command prompt.
Install the PEAR package managerThe PEAR package manager, which is available at https://
pear.php.net/manual/en/installation.getting.php, will enable you to download the required PEAR
packages.
Install the PEAR Mail and Net_SMTP packages The PEAR Mail package is available at http://
pear.php.net/package/Mail, and the PEAR Net_SMTP package is available at https://pear.php.net/
package/Net_SMTP.
Procedure
The following procedure shows how to send an email through the Amazon SES with PHP.
To send an email using the Amazon SES SMTP interface with PHP
1.
Create a file named amazon-ses-smtp-sample.php. Open the file with a text editor and paste in the
following code:
<?php
// Replace [email protected] with your "From" address.
// This address must be verified with Amazon SES.
define('SENDER', '[email protected]');
// Replace [email protected] with a "To" address. If your account
// is still in the sandbox, this address must be verified.
define('RECIPIENT', '[email protected]');
// Replace smtp_username with your Amazon SES SMTP user name.
define('USERNAME','smtp_username');
// Replace smtp_password with your Amazon SES SMTP password.
define('PASSWORD','smtp_password');
26

// If you're using Amazon SES in a region other than US West (Oregon),

// replace email-smtp.us-west-2.amazonaws.com with the Amazon SES SMTP
// endpoint in the appropriate region.
define('HOST', 'email-smtp.us-west-2.amazonaws.com');
// The port you will connect to on the Amazon SES SMTP endpoint.
define('PORT', '587');
// Other message information
define('SUBJECT','Amazon SES test (SMTP interface accessed using PHP)');
define('BODY','This email was sent through the Amazon SES SMTP interface
by using PHP.');
require_once 'Mail.php';
$headers = array (
'From' => SENDER,
'To' => RECIPIENT,
'Subject' => SUBJECT);
$smtpParams = array (
'host' => HOST,
'port' => PORT,
'auth' => true,
'username' => USERNAME,
'password' => PASSWORD
);
// Create an SMTP client.
$mail = Mail::factory('smtp', $smtpParams);
// Send the email.
$result = $mail->send(RECIPIENT, $headers, BODY);
if (PEAR::isError($result)) {
echo("Email not sent. " .$result->getMessage() ."\n");
} else {
echo("Email sent!"."\n");
}
?>
2.
In amazon-ses-smtp-sample.php, replace the following with your own values:

[email protected] with an email address that you have verified with Amazon
SES. For more information, see Verifying Email Addresses and Domains (p. 39). Email
addresses in Amazon SES are case-sensitive. Make sure that the address you enter is exactly
the same as the one you verified.
[email protected] with the address of the recipient. If your account is still in
Out of the Amazon SES Sandbox (p. 54). Make sure that the address you enter is exactly the
same as the one you verified.
smtp_usernameReplace with your SMTP user name credential, which you obtained from
the SMTP Settings page of the Amazon SES console. This is not the same as your AWS
access key ID. Note that your SMTP user name credential is a 20-character string of letters and
numbers, not an intelligible name.
27

Send an Email Using an AWS SDK
smtp_passwordReplace with your SMTP password, which you obtained from the SMTP
Settings page of the Amazon SES console. This is not the same as your AWS secret access
key.
(Optional) email-smtp.us-west-2.amazonaws.comIf you want to use an Amazon SES
SMTP endpoint in a region other than US West (Oregon), replace this with the Amazon SES
SMTP endpoint in the region you want to use. For a list of Amazon SES SMTP endpoints, see
Regions and Amazon SES (p. 332).
3.
Save amazon-ses-smtp-sample.php.
4.
To run the program, open a command prompt in the same directory as amazon-ses-smtpsample.php, and enter php amazon-ses-smtp-sample.php.
5.
Review the output. If the sending succeeded, you will see "Email sent!"
6.
Log in to the email client of the recipient address. You will find the message that you sent.
Configuring Your Existing Email Server or SMTP-Enabled

Application to Send Email Through Amazon SES
You can configure your mail server, email client, or email sending software package to send messages
through Amazon SES without any programming.
First, read Send an Email Through Amazon SES Using SMTP (p. 19). Then review one of the
following topics, which show you how to configure a mail server to forward mail to Amazon SES:
Integrating Amazon SES with Postfix (p. 69)
Integrating Amazon SES with Sendmail (p. 72)
Integrating Amazon SES with Exim (p. 83)
For information about how to configure Microsoft Outlook, an email client, to send email through
Amazon SES, see Configuring Email Clients to Send Through Amazon SES (p. 62).
For information about how to configure Jira, an issue-tracking software package, to send email through
Amazon SES, see Sending Email Through Amazon SES From Software Packages (p. 66).
Send an Email Through Amazon SES Using an

AWS SDK
To send an email using the Amazon SES API, you can use the Query interface directly, or you can
use an AWS SDK to handle low-level details such as assembling and parsing HTTP requests and
responses.
Before you send email using an AWS SDK, review the instructions in Before You Begin with Amazon
SES (p. 17). For this tutorial, you also need to:
Download an AWS SDKDownload and install an AWS SDK for either .NET or Java. For more
information, see Downloading an AWS SDK (p. 46).
Get your AWS credentialsTo access Amazon SES programmatically, you need your AWS
access keys. For more information, see Getting Your AWS Access Keys (p. 46).
After you have installed the appropriate SDK and retrieved your AWS credentials, you can send an
email through Amazon SES using one of the following examples:
Send an Email Through Amazon SES Using the AWS SDK for .NET (p. 29)
28

Send an Email Through Amazon SES Using the AWS SDK for Java (p. 32)
Send an Email Through Amazon SES Using the AWS SDK for PHP (p. 35)
Send an Email Through Amazon SES Using the AWS SDK

for .NET
The following procedure shows you how to use Microsoft Visual Studio and AWS Toolkit for Visual
Studio to create an AWS SDK project and modify the C# code to send an email through Amazon SES.
The process to create a new project based on a project template is similar across Microsoft Visual
Studio editions, but we'll go through the procedure using Microsoft Visual Studio Professional 2012.
Before you begin this procedure, complete the setup tasks described in Before You Begin with Amazon
SES (p. 17) and Send an Email Through Amazon SES Using an AWS SDK (p. 28).
Important
To send an email using the AWS SDK for .NET v.2

1.
Create an AWS project in Visual Studio by performing the following steps:

a.
Open Visual Studio.
b.
Choose File, choose New, and then choose Project.
c.
In the New Project dialog box, in the left pane, expand Installed, expand Templates, and
then expand Visual C#.
d.
Under Visual C#, choose AWS.
e.
Choose AWS Empty Project.
f.
In the Name field, type AmazonSESSample. The dialog box should look similar to the
following figure.
g.
Choose OK.
29

2.
In the AWS Access Credentials dialog box, select an existing account or enter the following
information:
Display NameType a name that identifies your account. Next time you create an AWS
project in Visual Studio, you will be able to select this account so you do not have to enter the
information again.
Access Key IDEnter the AWS access key ID that you obtained in Getting Your AWS Access
Keys (p. 46).
Secret Access KeyEnter the AWS secret access key that you obtained in Getting Your AWS
Access Keys (p. 46).
Account Number(Optional) Enter your AWS account number. To find your AWS account
number, go to the Security Credentials page in the AWS Management Console and choose
Account Identifiers. (If you are not logged into your AWS account, this link will take you to an
AWS account sign-in page first.) At the bottom of the page, under Account Identifiers, you will
see your AWS Account ID.
Default RegionSelect the AWS region of the Amazon SES endpoint you want to connect
to. Note that your sandbox status, sending limits, and Amazon SES identity-related settings
are specific to a given AWS region, so be sure to select an AWS region in which you set up
Amazon SES. For a list of AWS regions that Amazon SES supports, see Regions and Amazon
SES (p. 332).
3.
Choose OK.
4.
In your Visual Studio project, replace the entire contents of Program.cs with the following code:
using
using
using
using
System;
System.Collections.Generic;
Amazon.SimpleEmail;
Amazon.SimpleEmail.Model;
namespace AmazonSESSample
{
class Program
{
public static void Main(string[] args)
{
30

const String FROM = "[email protected]"; // Replace with

const String TO = "[email protected]"; // Replace with a
// sandbox, this address must be verified.
const String SUBJECT = "Amazon SES test (AWS SDK for .NET)";
const String BODY = "This email was sent through Amazon SES by
using the AWS SDK for .NET.";
// Construct an object to contain the recipient address.
Destination destination = new Destination();
destination.ToAddresses = (new List<string>() { TO });
// Create the subject and body of the message.
Content subject = new Content(SUBJECT);
Content textBody = new Content(BODY);
Body body = new Body(textBody);
// Create a message with the specified subject and body.
Message message = new Message(subject, body);
// Assemble the email.
SendEmailRequest request = new SendEmailRequest(FROM,
destination, message);
// Choose the AWS region of the Amazon SES endpoint you want
to connect to. Note that your sandbox
// status, sending limits, and Amazon SES identity-related
settings are specific to a given
// AWS region, so be sure to select an AWS region in which you
set up Amazon SES. Here, we are using
// the US West (Oregon) region. Examples of other regions that
Amazon SES supports are USEast1
// and EUWest1. For a complete list, see http://
docs.aws.amazon.com/ses/latest/DeveloperGuide/regions.html
Amazon.RegionEndpoint REGION = Amazon.RegionEndpoint.USWest2;
// Instantiate an Amazon SES client, which will make the
service call.
AmazonSimpleEmailServiceClient client = new
AmazonSimpleEmailServiceClient(REGION);
// Send the email.
try
{
Console.WriteLine("Attempting to send an email through
Amazon SES by using the AWS SDK for .NET...");
client.SendEmail(request);
Console.WriteLine("Email sent!");
}
{
Console.WriteLine("The email was not sent.");
Console.WriteLine("Error message: " + ex.Message);
}
Console.Write("Press any key to continue...");
Console.ReadKey();
31

}
}
}
5.
In Program.cs, replace the following with your own values:
Important
REGIONSet this to the AWS region of the Amazon SES endpoint you want to connect to.
Note that your sandbox status, sending limits, and Amazon SES identity-related settings are
specific to a given AWS region, so be sure to select an AWS region in which you set up Amazon
SES. In this example, we are using the US West (Oregon) region. Examples of other regions
that Amazon SES supports are USEast1 and EUWest1. For a complete list of AWS regions that
Amazon SES supports, see Regions and Amazon SES (p. 332).
6.
7.
Save Program.cs.
To build the project, choose Build and then choose Build Solution.
8.
9.
To run the program, choose Debug and then choose Start Debugging.
Review the program's console output to verify that the sending was successful. (You should see
"Email sent!")
Send an Email Through Amazon SES Using the AWS SDK for
Java
The following procedure shows you how to use Eclipse IDE for Java EE Developers and AWS Toolkit
for Eclipse to create an AWS SDK project and modify the Java code to send an email through Amazon
SES. It retrieves your AWS credentials from environment variables.
Before you begin this procedure, complete the setup tasks described in Before You Begin with Amazon
SES (p. 17) and Send an Email Through Amazon SES Using an AWS SDK (p. 28).
Important
To send an email using the AWS SDK for Java

1.
2.
3.
Create an environment variable called AWS_ACCESS_KEY_ID and set it to your AWS access key
ID. The procedure for setting environment variables depends on your operating system. Your AWS
access key ID will look something like: AKIAIOSFODNN7EXAMPLE.
Create an environment variable called AWS_SECRET_ACCESS_KEY and set it to your AWS
secret access key. Your AWS secret access key will look something like: wJalrXUtnFEMI/
K7MDENG/bPxRfiCYEXAMPLEKEY.
Create an AWS Java Project in Eclipse by performing the following steps:
32

a.
Open Eclipse.
b.
In Eclipse, choose File, choose New, and then choose AWS Java Project. If you do not see
AWS Java Project as an option, try selecting Other.
c.
In the Create an AWS Java Project dialog box, type a project name.
d.
Choose Finish.
4.
In Eclipse, in the Package Explorer window, expand your project.
5.
Under your project, right-click the src directory, choose New, and then choose Class.
6.
In the Java Class dialog box, in the Name field, type AmazonSESSample and then choose Finish.
7.
Replace the entire contents of AmazonSESSample.java with the following code:
import
import
import
import
java.io.IOException;
com.amazonaws.services.simpleemail.*;
com.amazonaws.services.simpleemail.model.*;
com.amazonaws.regions.*;
public class AmazonSESSample {

static final String FROM = "[email protected]"; // Replace with your
"From" address. This address must be verified.
static final String TO = "[email protected]"; // Replace with a
// sandbox, this
static final String BODY = "This email was sent through Amazon SES by
using the AWS SDK for Java.";
static final String SUBJECT = "Amazon SES test (AWS SDK for Java)";
public static void main(String[] args) throws IOException {

// Construct an object to contain the recipient address.
Destination destination = new Destination().withToAddresses(new
String[]{TO});
// Create the subject and body of the message.
Content subject = new Content().withData(SUBJECT);
Content textBody = new Content().withData(BODY);
Body body = new Body().withText(textBody);
// Create a message with the specified subject and body.
Message message = new
Message().withSubject(subject).withBody(body);
33

// Assemble the email.

SendEmailRequest request = new
SendEmailRequest().withSource(FROM).withDestination(destination).withMessage(message);
try
{
System.out.println("Attempting to send an email through Amazon
SES by using the AWS SDK for Java...");
// Instantiate an Amazon SES client, which will make the
service call. The service call requires your AWS credentials.
// Because we're not providing an argument when instantiating
the client, the SDK will attempt to find your AWS credentials
// using the default credential provider chain. The first
place the chain looks for the credentials is in environment variables
// AWS_ACCESS_KEY_ID and AWS_SECRET_KEY.
// For more information, see http://docs.aws.amazon.com/sdkfor-java/v1/developer-guide/credentials.html
AmazonSimpleEmailServiceClient();
// Choose the AWS region of the Amazon SES endpoint you want
to connect to. Note that your sandbox
// status, sending limits, and Amazon SES identity-related
settings are specific to a given AWS
// region, so be sure to select an AWS region in which you set
up Amazon SES. Here, we are using
// the US West (Oregon) region. Examples of other regions that
Amazon SES supports are US_EAST_1
// and EU_WEST_1. For a complete list, see http://
docs.aws.amazon.com/ses/latest/DeveloperGuide/regions.html
Region REGION = Region.getRegion(Regions.US_WEST_2);
client.setRegion(REGION);
// Send the email.
client.sendEmail(request);
}
{
System.out.println("The email was not sent.");
System.out.println("Error message: " + ex.getMessage());
}
}
}
8.
In AmazonSESSample.java, replace the following with your own values:
Important
34

REGIONSet this to the AWS region of the Amazon SES endpoint you want to connect to.
Note that your sandbox status, sending limits, and Amazon SES identity-related settings are
specific to a given AWS region, so be sure to select an AWS region in which you set up Amazon
SES. In this example, we are using the US West (Oregon) region. Examples of other regions
that Amazon SES supports are US_EAST_1 and EU_WEST_1. For a complete list of AWS
regions that Amazon SES supports, see Regions and Amazon SES (p. 332).
9.
Save AmazonSESSample.java.
10. To build the project, choose Project and then choose Build Project. (If this option is disabled, you
may have automatic building enabled.)
11. To start the program and send the email, choose Run and then choose Run again.
12. Review the program's console output to verify that the sending was successful. (You should see
"Email sent!")
Send an Email Through Amazon SES Using the AWS SDK for
PHP
This topic shows how to use the AWS SDK for PHP to send an email through Amazon SES.
Important
In this tutorial, you send an email to yourself so that you can check to see if you received
it. For further experimentation or load testing, use the Amazon SES mailbox simulator.
Emails that you send to the mailbox simulator do not count toward your sending quota or
your bounce and complaint rates. For more information, see Testing Amazon SES Email
Sending (p. 224).
Prerequisites
Before you begin, perform the following tasks:
Verify your email address with Amazon SESBefore you can send an email with Amazon SES,
you must verify that you own the sender's email address. If your account is still in the Amazon SES
sandbox, you must also verify the recipient email address. The easiest way to verify email addresses
is by using the Amazon SES console. For more information, see Verification Procedures (p. 40).
Get your AWS credentialsYou need an AWS access key ID and AWS secret access key to
access Amazon SES using an SDK. You can find your credentials by using the Security Credentials
page of the AWS Management Console. For more information about credentials, see Using
Credentials With Amazon SES (p. 323).
Install PHPPHP is available at http://php.net/downloads.php. This tutorial requires PHP version
5.5 or higher. After you install PHP, add the path to PHP in your environment variables so that you
can run PHP from any command prompt.
Install the AWS SDK for PHP version 3.xFor download and installation instructions, see the
AWS SDK for PHP documentation.
Procedure
The following procedure shows how to send an email through Amazon SES using the AWS SDK for
PHP.
To send an email through Amazon SES using the AWS SDK for PHP
1.
Set up your AWS credentials by creating the following environment variables. For alternate ways
to set up your AWS credentials, see the AWS SDK for PHP documentation.
35

Note
The procedure for creating environment variables depends on your operating system.
2.
a.
Create an environment variable called AWS_ACCESS_KEY_ID and set it to your AWS access
key ID. Your AWS access key ID will look something like: AKIAIOSFODNN7EXAMPLE.
b.
Create an environment variable called AWS_SECRET_ACCESS_KEY and set it to your AWS

secret access key. Your AWS secret access key will look something like: wJalrXUtnFEMI/
K7MDENG/bPxRfiCYEXAMPLEKEY.
Create a file named amazon-ses-sample.php. Open the file with a text editor and paste in the
following code:
<?php
// Replace path_to_sdk_inclusion with the path to the SDK as described in
// http://docs.aws.amazon.com/aws-sdk-php/v3/guide/getting-started/basicusage.html
define('REQUIRED_FILE','path_to_sdk_inclusion');
// Replace [email protected] with your "From" address.
// This address must be verified with Amazon SES.
define('SENDER', '[email protected]');
// Replace [email protected] with a "To" address. If your account
// is still in the sandbox, this address must be verified.
define('RECIPIENT', '[email protected]');
// Replace us-west-2 with the AWS region you're using for Amazon SES.
define('REGION','us-west-2');
define('SUBJECT','Amazon SES test (AWS SDK for PHP)');
define('BODY','This email was sent with Amazon SES using the AWS SDK for
PHP.');
require REQUIRED_FILE;
use Aws\Ses\SesClient;
$client = SesClient::factory(array(
'version'=> 'latest',
'region' => REGION
));
$request = array();
$request['Source'] = SENDER;
$request['Destination']['ToAddresses'] = array(RECIPIENT);
$request['Message']['Subject']['Data'] = SUBJECT;
$request['Message']['Body']['Text']['Data'] = BODY;
try {
$result = $client->sendEmail($request);
$messageId = $result->get('MessageId');
echo("Email sent! Message ID: $messageId"."\n");
} catch (Exception $e) {
echo("The email was not sent. Error message: ");
echo($e->getMessage()."\n");
}

36

Setting up Email
?>
3.
In amazon-ses-sample.php, replace the following with your own values:

path_to_sdk_inclusionReplace with the path required to include the AWS SDK for PHP in
the program. For more information, see the AWS SDK for PHP documentation.
[email protected] with an email address that you have verified with Amazon
SES. For more information, see Verifying Email Addresses and Domains (p. 39). Email
addresses in Amazon SES are case-sensitive. Make sure that the address you enter is exactly
the same as the one you verified.
[email protected] with the address of the recipient. If your account is still in
Out of the Amazon SES Sandbox (p. 54). Make sure that the address you enter is exactly the
same as the one you verified.
(Optional) us-west-2If you want to use Amazon SES in a region other than US West
(Oregon), replace this with the region you want to use. For a list of regions in which Amazon
SES is available, see Regions and Amazon SES (p. 332).
4.
Save amazon-ses-sample.php.
5.
To run the program, open a command prompt in the same directory as amazon-ses-sample.php,
and enter php amazon-ses-sample.php.
6.
Review the output. If the sending succeeded, you will see "Email sent!"
Note
If you encounter a "cURL error 60: SSL certificate problem" error when you run the
program, download the latest CA bundle as described in the AWS SDK for PHP
documentation. Then, in amazon-ses-sample.php, add the following lines to the
SesClient::factory array, replace path_of_certs with the path to the CA bundle
you downloaded, and re-run the program.
'http' => [
'verify' => 'path_of_certs\ca-bundle.crt'
]
7.
Log in to the email client of the recipient address. You will find the message that you sent.
Setting up Email with Amazon SES

To set up email with Amazon Simple Email Service (Amazon SES), you need to perform the following
tasks:
Before you can access Amazon SES or other AWS services, you need to set up an AWS account.
For more information, see Signing up for AWS (p. 38).
Before you send email through Amazon SES, you need to verify that you own the "From" address. If
your account is still in the Amazon SES sandbox, you also need to verify your "To" addresses. You
can verify email addresses or entire domains. For more information, see Verifying Email Addresses
and Domains in Amazon SES (p. 39).
The following tasks are optional depending on what you want to do:
If you want to access Amazon SES through the Amazon SES API, whether by the Query (HTTPS)
interface or indirectly through an AWS SDK, the AWS Command Line Interface or the AWS Tools for
Windows PowerShell, you need to obtain your AWS access keys. For more information, see Getting
Your AWS Access Keys (p. 46).
37

Signing up for AWS
If you want to call the Amazon SES API without handling the low-level details of the Query interface,
you can use an AWS SDK. For more information, see Downloading an AWS SDK (p. 46).
If you want to access Amazon SES through its SMTP interface, you need to obtain your SMTP user
name and password. Your SMTP credentials are different from your AWS credentials. For more
information, see Getting Your SMTP Credentials for Amazon SES (p. 54).
When you first sign up for Amazon SES, your account is in the Amazon SES sandbox. In the
sandbox, you can send emails using the same email-sending methods as any other Amazon SES
user, except that you can only send 200 emails per 24-hour period at a maximum rate of one
email per second, and you can only send emails to addresses you have verified. To increase your
sending limits and to send email to unverified email addresses, see Moving Out of the Amazon SES
Sandbox (p. 54).
If you want your emails to pass Domain-based Message Authentication, Reporting and Conformance
(DMARC) authentication based on Sender Policy Framework (SPF), configure your identity to send
from a custom MAIL FROM domain as described in Using a Custom MAIL FROM Domain (p. 46).
Signing up for AWS

You need to create an AWS account before you can use Amazon SES or other AWS services. When
you create an AWS account, AWS automatically signs up your account for all services. You are
charged only for the services that you use.
Note
If you will be sending your emails from an Amazon EC2 instance either directly or through
AWS Elastic Beanstalk, you can get started with Amazon SES for free. For more information,
see Amazon SES Pricing.
When you first sign up for AWS, your Amazon SES sending is in the Amazon SES sandbox. In the
sandbox, you have full access to the Amazon SES API and SMTP interface. However, the following
restrictions are in effect:
You can only send emails to the Amazon SES mailbox simulator and to email addresses or domains
that you have verified. For more information, see Verifying Email Addresses and Domains in Amazon
SES (p. 39).
You can send a maximum of 200 messages per 24-hour period.
You can send a maximum of one message per second.
For information about moving out of the sandbox, see Moving Out of the Amazon SES
Sandbox (p. 54).
To create an AWS account

1.
Go to https://aws.amazon.com/ses, and choose Sign up now.
2.
Follow the on-screen instructions.
Note
Even if your account is out of the Amazon SES sandbox, you still need to verify your "From"
address to confirm that you own it.

38

Verifying Email Addresses and Domains
Verifying Email Addresses and Domains in Amazon

SES
Before you can send an email using Amazon SES, you must verify each email address (or the domain
of the email address) that you will use as a "From", "Source", "Sender", or "Return-Path" address to
prove that you own it. If your account is still in the Amazon SES sandbox, you also need to verify any
email addresses that you send emails to except for email addresses provided by the Amazon SES
mailbox simulator. You can verify an email address or domain by using the Amazon SES console or by
using the Amazon SES API.
Email address and domain verification status for each AWS region is separate. For more information,
see the verification procedures in the following sections.
For information about verifying email addresses, see Verifying Email Addresses in Amazon
SES (p. 39).
For information about verifying entire domains, see Verifying Domains in Amazon SES (p. 41).
Verifying Email Addresses in Amazon SES

Amazon SES requires that you verify your email address or domain, to confirm that you own it and
to prevent others from using it. This section discusses verifying individual email addresses. For
information about domain verification, see Verifying Domains in Amazon SES (p. 41).
Overview
With the exception of addresses containing labels (see below), you must verify each email address
(or the domain of the email address) that you will use as a "From", "Source", "Sender", or "ReturnPath" address for your messages. Until your account is out of the Amazon SES sandbox, you must
also verify the email address of every recipient except for the recipients provided by the Amazon SES
mailbox simulator. For more information about the mailbox simulator, see Testing Amazon SES Email
Sending (p. 224). For more information about moving out of the sandbox, see Moving Out of the
Amazon SES Sandbox (p. 54).
Important notes about email address verification are as follows:
The entire email address is case-sensitive. For example, if you verify [email protected], you
cannot send emails from [email protected] unless you verify [email protected] also.
(Domain verification, however, is case-insensitive. For more information, see Verifying Domains in
Amazon SES (p. 41).)
If you individually verify an email address and you also verify the domain of that address, the verified
identity settings (such as DKIM and feedback notifications) of the email address override the domainlevel settings. For example, if you verify example.com and [email protected], and you have
DKIM enabled for example.com but not enabled for [email protected], then emails you send
from [email protected] will not be DKIM-signed.
Amazon SES has endpoints in multiple AWS regions, and email address verification status is
separate for each AWS region. You must complete the email address verification process for each
sender in the AWS region(s) you want to use. For information about using Amazon SES in multiple
AWS regions, see Regions and Amazon SES (p. 332).
You can verify as many as 1,000 identities (domains and email addresses, in any combination) per
AWS account.
Verifying an email address also allows you to set the "From" and "Return-Path" address to any
address formed by adding a label to the verified address. Addresses that contain labels are of the
form [email protected], with user-specified text between the plus sign (+) and the at sign
(@).
39

For example, if you verify [email protected], you can also send email from user
[email protected], [email protected], and so on. This makes it
possible to support Variable Envelope Return Path (VERP) the use of a different return
path for each recipient. For more information about VERP, see http://en.wikipedia.org/wiki/
Variable_envelope_return_path.
When you verify an unlabeled address, then you are essentially verifying all addresses that
are formed by adding a label to the verified address. The opposite, however is not true.
Verifying an email address that already contains a label does not allow you to send from
other addresses. For example, verifying [email protected] does not allow
you to send from [email protected], [email protected], or andrew
[email protected].
If you want to use the SendRawEmail API action to send a message that contains a "Sender"
header, then you must first verify the email address or domain in that header. For more information,
see About Email Header Fields (p. 88).
Verification Procedures
The following procedures show how to use the Amazon SES console to verify and view email
addresses.
To verify an email address

1.
Go to your email address list in the Amazon SES console, or follow these instructions to navigate
to it:
a.
Sign in to the AWS Management Console and open the Amazon SES console at https://
console.aws.amazon.com/ses/.
b.
In the navigation pane, under Identity Management, choose Email Addresses.
2.
Choose Verify a New Email Address.
3.
In the Verify a New Email Address dialog box, type your email address in the indicated field, and
then choose Verify This Email Address.
4.
In your email client, open the message from Amazon SES asking you to confirm that you are the
owner of this email address.
5.
Click the link in the message.
Note
The link in the verification message expires 24 hours after your original verification
request.
40

6.
7.
The status of the email address in the Amazon SES console will change from "pending
verification" to "verified".
You can now use Amazon SES to send email from this address. To send a test email, check the
box next to the verified email address, and then choose Send a Test Email.
To view your verified email addresses

1.
to it:
a.
b.
2.
In the list of verified email addresses, you can expand one or more email addresses to view the
details.
To remove verified email addresses

1.
to it:
a.
b.
2.
Check the box beside each email address that you want to remove, and then choose Remove.
Using the Amazon SES API

You can also manage verified email addresses with the Amazon SES API. The following actions are
available:
VerifyEmailIdentity
ListIdentities
DeleteIdentity
GetIdentityVerificationAttributes
Note
The API actions above are preferable to the following older API actions, which are deprecated
as of the May 15, 2012 release of Domain Verification.
VerifyEmailAddress
ListVerifiedEmailAddresses
DeleteVerifiedEmailAddress
You can use these API actions to write a customized front-end application for email address
verification. For a complete description of the API actions related to email verification, go to the
Amazon Simple Email Service API Reference.
Verifying Domains in Amazon SES

Amazon SES requires that you verify your email address or domain, to confirm that you own it and to
prevent others from using it. When you verify an entire domain, you are verifying all email addresses
from that domain, so you don't need to verify email addresses from that domain individually. For
41

example, if you verify the domain example.com, you can send email from [email protected],
[email protected], or any other user at example.com.
You can manage your verified domains by using the Amazon SES console or the Amazon SES API.
For a complete description of API actions related to domain verification, go to the Amazon Simple
Email Service API Reference. This section, which demonstrates the actions using the Amazon SES
console, contains the following topics:
Verifying a Domain With Amazon SES (p. 42)
Viewing Your Domains Verified With Amazon SES (p. 44)
Removing a Domain Verified With Amazon SES (p. 44)
Amazon SES Domain Verification Revocation (p. 44)
Amazon SES Domain Verification TXT Records (p. 45)
Important notes about domain verification are as follows:
Amazon SES has endpoints in multiple AWS regions, and domain verification applies to each AWS
region separately. You must perform the entire domain verification procedure for each region in
which you want to send from a given domain. If you want to verify the same domain in multiple
regions and your DNS provider does not allow you to have multiple TXT records with the same
name, see the workarounds in Common Domain Verification Problems (p. 234).
If you verify a domain with Amazon SES, you can send from any subdomain of that domain without
specifically verifying the subdomain. For example, if you verify example.com, you do not need to
verify a.example.com or a.b.example.com. As specified in RFC 1034, each DNS label can have up
to 63 characters and the whole domain name must not exceed a total length of 255 characters.
If you verify a domain, subdomain(s), and/or email address(es) that share a root domain, the verified
identity settings (such as feedback notifications and Easy DKIM) apply at the most granular level you
verified. That is:
Verified email address settings override verified domain settings.
Verified subdomain settings override verified domain settings, with lower-level subdomain settings
overriding higher-level subdomain settings.
For example, assume you verify [email protected], a.b.example.com, b.example.com, and
example.com. These are the verified identity settings that will be used in the following scenarios:
Emails sent from [email protected] (an address that is not specifically verified) will use the
settings for example.com.
Emails sent from [email protected] (an address that is specifically verified) will use the
settings for [email protected].
Emails sent from [email protected] (an address that is not specifically verified) will use the
settings for b.example.com.
Domain names are case-insensitive. If you verify example.com, you can send from EXAMPLE.com
also.
You can verify as many as 1,000 identities (domains and email addresses, in any combination) per
AWS account.
Verifying a Domain With Amazon SES

The following procedure shows you how to verify a domain using the Amazon SES console. If you want
to use the Amazon SES API instead, see the Amazon Simple Email Service API Reference.
To verify a domain
1.
Go to your verified domain list in the Amazon SES console, or follow these instructions to
navigate to it:
42

a.
b.
In the navigation pane, under Identity Management, choose Domains.
2.
Choose Verify a New Domain.
3.
In the Verify a New Domain dialog box, enter the domain name. If you want to set up DKIM
signing for this domain, select the Generate DKIM Settings option. (For information about DKIM
signing, see Authenticating Email with DKIM in Amazon SES (p. 93).) Choose Verify This
Domain.
4.
In the Verify a New Domain dialog box, you will see a Domain Verification Record Set
containing a Name, a Type, and a Value. (This information will also be available by choosing the
domain name after you close the dialog box.)
To complete domain verification, add a TXT record with the displayed Name and Value to your
domain's DNS server. For information about Amazon SES TXT records and general guidance
about how to add a TXT record to a DNS server, see Amazon SES Domain Verification TXT
Records (p. 45). In particular:
If your DNS provider does not allow underscores in record names, you can omit _amazonses
from the Name.
To help you easily identify this record within your domain's DNS settings, you can optionally
prefix the Value with amazonses:
Some DNS providers automatically append the domain name to DNS record names. To avoid
duplication of the domain name, you can add a period to the end of the domain name in the
DNS record. This indicates that the record name is fully qualified and the DNS provider need not
append an additional domain name.
5.
If Amazon Route 53 provides the DNS service for the domain that you are verifying, and you are
signed in to the AWS Management Console under the same account that you use for Amazon
Route 53, then Amazon SES will give you the option of updating your DNS server immediately
from within the Amazon SES console. If you are not using Amazon Route 53, Amazon SES needs
to verify that a TXT record with the specified Name and Value have been added to your domain's
DNS server. This may take up to 72 hours.

43

When verification is complete, the domain's status in the Amazon SES console will change from
"pending verification" to "verified," and you will receive a confirmation success email from Amazon
SES to the email address associated with your AWS account.
6.
You can now use Amazon SES to send email from any address in the verified domain. To send a
test email, check the box next to the verified domain, and then choose Send a Test Email.
If the DNS settings are not correctly updated, you will receive a domain verification failure email from
Amazon SES, and the domain will display a status of "failed" in the Domains tab. If this happens, read
our troubleshooting page at Amazon SES Domain Verification Problems (p. 233). When you have
verified that your TXT record is correctly in place, choose the "retry" link next to the "failed" status
notification. This will reinitiate the domain verification process.
Viewing Your Domains Verified With Amazon SES

To view your verified domains, follow the procedure below.
To view your verified domains

1.
2.
Go to your verified domain list in the Amazon SES console, or follow these instructions to navigate
to it:
a.
b.
In the list of verified domains, you can expand one or more domains to view the details.
Removing a Domain Verified With Amazon SES

To remove a verified domain, follow the procedure below.
To remove a verified domain

1.
to it:
a.
b.
2.
Check the box beside each domain that you want to remove, and then choose Remove.
3.
You will no longer be able to send email from the removed domain.
Amazon SES Domain Verification Revocation

Amazon SES periodically reviews domain verification status, and revokes verification in cases where
it is no longer valid. If Amazon SES is unable to detect the TXT record information required to confirm
ownership of a domain, you will receive an Amazon SES Domain Verification REVOCATION
WARNING email from Amazon SES.
If you restore the TXT record information to your domain's DNS server within 72 hours, you will receive
an Amazon SES Domain Verification REVOCATION CANCELLATION email from Amazon SES.
Note
You can review the required TXT record information in the Amazon SES console by using the
following instructions. In the navigation pane, under Identity Management, choose Domains.

44

In the list of domains, choose (not just expand) the domain to display the domain verification
settings, which include the TXT record name and value.
If you do not restore the TXT record information to your domain's DNS server within 72 hours, you will
receive an Amazon SES Domain Verification REVOCATION email from Amazon SES, the domain
will be removed from the list of Verified Senders on the Domains tab, and you will no longer be able
to send from the domain.
To reverify a domain for which verification has been revoked, you must restart the verification
procedure from the beginning, just as if the revoked domain were an entirely new domain.
Amazon SES Domain Verification TXT Records

Your domain is associated with a set of Domain Name System (DNS) records that you manage
through your DNS provider. A TXT record is a type of DNS record that provides additional information
about your domain. Each TXT record consists of a name and a value.
When you initiate domain verification using the Amazon SES console or API, Amazon SES gives you
the name and value to use for the TXT record. For example, if your domain is example.com, the TXT
record settings that Amazon SES generates will look similar to the following example:
Name
Type
Value
_amazonses.example.com
TXT
pmBGN/7MjnfhTKUZ06Enqq1PeG
Add a TXT record to your domain's DNS server using the specified Name and Value. Amazon SES
domain verification is complete when Amazon SES detects the existence of the TXT record in your
domain's DNS settings.
If your DNS provider does not allow DNS record names to contain underscores, you
can omit _amazonses from the Name. In that case, for the preceding example, the TXT
record name would be example.com instead of _amazonses.example.com. To make the
record easier to recognize and maintain, you can also optionally prefix the Value with
amazonses:. In the previous example, the value of the TXT record would therefore be
amazonses:pmBGN/7MjnfhTKUZ06Enqq1PeGUaOkw8lGhcfwefcHU=.
Note
Amazon SES previously allowed TXT record names to contain amazonses without an
underscore. If you have already verified a domain and your TXT record contains amazonses
without an underscore, your domain will continue to be verified; there is no action required on
your part. However, any new domains that you verify will require that amazonses in the TXT
record name is either preceded by an underscore, or _amazonses is removed from the TXT
record name entirely.
You can find troubleshooting information and instructions on how to check your domain verification
settings in Amazon SES Domain Verification Problems (p. 233).
Adding a TXT Record to Your Domain's DNS Server

The procedure for adding TXT records to your domain's DNS server depends on who provides your
DNS service. Your DNS provider might be Amazon Route 53 or another domain name registrar such
as GoDaddy. Although we cannot provide specific instructions about how to add TXT records to your
domain's DNS server, here is the general procedure DNS providers typically use.
To add a TXT record to your domain's DNS server (general procedure)

1.
Go to your DNS provider's website. If you are not sure which DNS provider serves your domain,
try looking it up by using a free Whois service.
45

Getting Your AWS Access Keys
2.
Sign in to your domain's account.
3.
4.
Find the page for updating your domain's DNS records. This page often has a name such as DNS
Records, DNS Zone File, Advanced DNS, or something similar.
Locate the TXT records for your domain.
5.
Add a TXT record with the name and value provided by Amazon SES.
Important
Some DNS providers automatically append the domain name to the end of
DNS records. Adding a record that already contains the domain name (such as
_amazonses.example.com) might result in the duplication of the domain name (such as
_amazonses.example.com.example.com). To avoid duplication of the domain name, add
a period to the end of the domain name in the DNS record. This will indicate to your DNS
provider that the record name is fully qualified (that is, no longer relative to the domain
name), and prevent the DNS provider from appending an additional domain name.
6.
Save your changes. DNS record updates can take up to 48 hours to take effect, but they often
take effect much sooner. You can verify that the TXT record is correctly published by using the
procedure in How to Check Domain Verification Settings (p. 233).
Getting Your AWS Access Keys

After you've signed up for Amazon SES, you'll need to obtain your AWS access keys if you want to
access Amazon SES through the Amazon SES API, whether by the Query (HTTPS) interface directly
or indirectly through an AWS SDK, the AWS Command Line Interface, or the AWS Tools for Windows
PowerShell. AWS access keys consist of an access key ID and a secret access key.
For information about getting your AWS access keys, see AWS Security Credentials in the AWS
General Reference.
Downloading an AWS SDK

If you want to call the Amazon SES API without having to handle low-level details like assembling raw
HTTP requests, you can use an AWS SDK. The AWS SDKs provide functions and data types that
encapsulate the functionality of Amazon SES and other AWS services.
To download an AWS SDK, go to the appropriate link listed above. The prerequisites and installation
instructions for each SDK are listed on the corresponding page.
Note
The getting started section of this developer guide provides examples of how to send an email
by using the AWS SDKs for .NET, Java, and PHP. For more information, see Send an Email
Through Amazon SES Using an AWS SDK (p. 28).
To see a list of all the AWS SDKs, go to Sample Code and Libraries.
Using a Custom MAIL FROM Domain with Amazon

SES
When an email is sent, it has two addresses that indicate its source: a "From" address provided by
the email header, and a MAIL FROM address (sometimes called the envelope sender, envelope from,
bounce address, or Return Path) that the sending mail server specifies to the receiving mail server to
indicate the source of the message. When recipients view an email in their inbox, they see the email's
"From" address. In contrast, the MAIL FROM address, which is used by mail servers to return bounce
messages and other error notifications, is typically only viewable by recipients if they inspect the
email's headers in the raw message source. Amazon SES sets the MAIL FROM domain to a default
value unless you choose to use your own.
46

Using a Custom MAIL FROM Domain
Why Use a Custom MAIL FROM Domain?

By default, messages that you send through Amazon SES use amazonses.com (or a subdomain
of that) as the MAIL FROM domain. Sender Policy Framework (SPF) authentication successfully
validates these messages because the default MAIL FROM domain matches the sending mail server,
Amazon SES. Although this level of authentication is enough for many senders, you might want to set
the MAIL FROM domain to a domain that you own to enable your emails to authenticate with Domainbased Message Authentication, Reporting and Conformance (DMARC) through SPF, which requires
an additional check for SPF domain alignment. DMARC enables a sender's domain to indicate, using a
DNS record, that its emails are protected by SPF, DomainKeys Identified Mail (DKIM), or both.
There are two ways to achieve DMARC validation: using SPF and using DKIM. Unless you use your
own MAIL FROM domain, you cannot achieve DMARC validation using SPF because that validation
requires the domain in the "From" address to match the MAIL FROM domain. By using your own MAIL
FROM domain, you have the flexibility to use SPF, DKIM, or both to achieve DMARC validation. For
more information, see Authenticating Email with SPF (p. 92).
Choosing a MAIL FROM Domain

If you choose to use your own MAIL FROM domain with Amazon SES, your MAIL FROM domain must
comply with the following requirements:
The MAIL FROM domain must be a subdomain of the verified identity (email address or domain)
from which you will send your emails. For example, bounce.example.com is a valid MAIL FROM
domain for the [email protected] email address or example.com domain.
You must not use the MAIL FROM domain in a "From" address ("From", "Return Path", or "Source")
unless you ensure that your setup is such that email feedback forwarding will never forward
feedback to the MAIL FROM domain. This is to prevent feedback loops that would cause you to not
receive feedback. If you must use the MAIL FROM domain in a "From" address, either disable email
feedback forwarding and receive your bounces through Amazon SNS notifications, or ensure that
your MAIL FROM domain is not the destination for the feedback. To determine the destination of
email forwarding feedback, see Email Feedback Forwarding Destination (p. 109).
The MAIL FROM domain must not be a domain that you use to receive emails.
Setup Process
To set the MAIL FROM domain for a verified identity, you configure the verified identity using the
Amazon SES console or API and publish an MX record (and optionally, an SPF record) to your MAIL
FROM domain's DNS server. If at any point you want to return to using the default Amazon SES MAIL
FROM domain, you can remove your MAIL FROM domain from the verified identity's settings. These
procedures are described in the following sections:
Setting a MAIL FROM Domain (p. 47)
Removing a MAIL FROM Domain (p. 50)
Editing a MAIL FROM Domain (p. 51)
For a description of custom MAIL FROM domain setup states, see MAIL FROM Domain Setup
States (p. 53).
Setting a MAIL FROM Domain with Amazon SES

This topic contains an overview of the custom MAIL FROM setup process, and then walks you through
the procedure using the Amazon SES console.
47

Note
You can use the same MAIL FROM address in multiple AWS regions. For more information,
see Regions and Amazon SES (p. 332).
Overview of the Setup Process

Setting up a MAIL FROM domain for a verified identity consists of the following three steps:
1.
You use the Amazon SES console or API to configure the identity to use a MAIL FROM domain
that you specify.
2.
You publish an MX record to the DNS server of the MAIL FROM domain. Amazon SES provides
you with this record during the setup process. For example, if you are configuring identity
example.com to use the MAIL FROM domain bounce.example.com in the US West (Oregon)
region, Amazon SES will provide you with the following MX record settings:
Name
Type
Value
bounce.example.com
MX
10 feedbacksmtp.uswest-2.amazonses.com
The endpoint in the record value depends on the AWS region. For a list of feedback endpoints for
all AWS regions, see Custom MAIL FROM Domains (p. 335).
3.
(Optional) If you want your emails to pass Sender Policy Framework (SPF) checks, you must
publish an SPF record to the DNS server of the custom MAIL FROM domain. Amazon SES
provides you with this record during the setup process. The SPF record for MAIL FROM domain
bounce.example.com would have the following settings:
Name
Type
Value
bounce.example.com
TXT
"v=spf1 include:amazonses.com all"
For further details on setting up SPF records, see Authenticating Email with SPF in Amazon
SES (p. 92).
Setup Procedure Details

The following procedures show how to use the Amazon SES console to configure a verified email
address or domain to send emails using a specified MAIL FROM domain. If you want to use the
Amazon SES API instead, see the SetIdentityMailFromDomain API in the Amazon Simple Email
Service API Reference.
To configure a verified email address to use a specified MAIL FROM domain

1.
Go to your verified email address list in the Amazon SES console, or follow these instructions to
navigate to it:
a.
2.
b. In the navigation pane, under Identity Management, choose Email Addresses.
In the verified email address list, confirm that the status of the email address for which you want to
set the MAIL FROM domain is verified. If the status is failure, choose retry and then click the link
within the verification email you receive in your email client. Otherwise, choose the email address
and continue this procedure.
48

3.
In the details pane of the verified email address, expand MAIL FROM Domain.
4.
Choose Set MAIL FROM Domain.
5.
In the Set MAIL FROM Domain dialog box, type the name of the MAIL FROM domain that you
want to use. Note that this must be a subdomain of the domain of the verified email address.
6.
Later in this procedure, you must publish an MX record to the DNS server of the custom MAIL
FROM domain. Here, for Behavior if MX record not found, choose what you want Amazon SES
to do if it cannot successfully read that record when you send an email. You have the following
options:
Use default Amazon SES valueIf the custom MAIL FROM domain's MX record is not set
up correctly, Amazon SES will use the default MAIL FROM domain (amazonses.com or a
subdomain of amazonses.com).
Reject messageIf the custom MAIL FROM domain's MX record is not set up correctly,
Amazon SES will return a MailFromDomainNotVerified error and not send the email.
7.
8.
Next, you must publish an MX record to the DNS server of the custom MAIL FROM domain.
Important
To successfully set up a custom MAIL FROM domain with Amazon SES, you must
publish exactly one MX record to the DNS server of your MAIL FROM domain. If the MAIL
FROM domain has multiple MX records, the custom MAIL FROM setup with Amazon
SES will fail.
9.
a.
If Amazon Route 53 provides the DNS service for your MAIL FROM domain, and you are
Route 53, then choose Publish Records Using Route 53 if you want to publish the MX
record and/or SPF record from within the Amazon SES console.
b.
If your MAIL FROM domain does not use Amazon Route 53, then you must publish the
displayed MX record to the MAIL FROM domain's DNS server yourself. The procedure for
adding an MX record to your domain's DNS server depends on who provides your DNS
service; please see the documentation for your DNS service. After Amazon SES detects the
record, emails you send from this verified email address will use the specified MAIL FROM
domain. Until then, Amazon SES will either use the default MAIL FROM domain or reject the
message, depending on the preferences you specified earlier in this procedure. Amazon SES
can take up to 72 hours to detect your MX record.
(Optional) If you want Sender Policy Framework (SPF) checks to succeed, you must publish an
SPF record to your MAIL FROM domain's DNS server to show receiving mail servers that you
have authorized Amazon SES to send email on behalf of your domain. For more information, see
Authenticating Email with SPF in Amazon SES (p. 92).
To configure a verified domain to use a specified MAIL FROM domain

1.
Go to your verified domain list in the Amazon SES console, or follow these instructions to
navigate to it:
a.
b.
2.
In the verified domain list, confirm that the status of the domain for which you want to set
the MAIL FROM domain is verified. If the status is failure, choose retry and then add the
displayed TXT record to your DNS server, as described in Amazon SES Domain Verification TXT
Records (p. 45). Otherwise, choose the domain and continue this procedure.
3.
In the details pane of the verified domain, expand MAIL FROM Domain.
4.

49

5.
In the Set MAIL FROM Domain dialog box, type the name of the MAIL FROM domain that you
want to use. Note that this must be a subdomain of the verified domain.
6.
Later in this procedure, you must publish an MX record to the verified domain's DNS server. Here,
for Behavior if MX record not found, choose what you want Amazon SES to do if it cannot
successfully read that record when you send an email. You have the following options:
Use default Amazon SES valueIf the custom MAIL FROM domain's MX record is not set
up correctly, Amazon SES will use the default MAIL FROM domain (amazonses.com or a
subdomain of amazonses.com).
Reject messageIf the custom MAIL FROM domain's MX record is not set up correctly,
Amazon SES will return a MailFromDomainNotVerified error and not send the email.
7.
8.
Next, you must publish an MX record to the DNS server of the custom MAIL FROM domain.
Important
To successfully set up a custom MAIL FROM domain with Amazon SES, you must
publish exactly one MX record to the DNS server of your MAIL FROM domain. If the MAIL
FROM domain has multiple MX records, the custom MAIL FROM setup with Amazon
SES will fail.
9.
a.
b.
If your MAIL FROM domain does not use Amazon Route 53, then you must publish the
displayed MX record to the MAIL FROM domain's DNS server yourself. The procedure for
adding an MX record to your domain's DNS server depends on who provides your DNS
service; please see the documentation for your DNS service. After Amazon SES detects the
record, emails you send from this verified domain will use the specified MAIL FROM domain.
Until then, Amazon SES will either use the default MAIL FROM domain or reject the message,
depending on the preferences you specified earlier in this procedure. Amazon SES can take
up to 72 hours to detect your MX record.
(Optional) If you want Sender Policy Framework (SPF) checks to succeed, you must publish an
SPF record to your MAIL FROM domain's DNS server to show receiving mail servers that you
have authorized Amazon SES to send email on behalf of your domain. For more information, see
Authenticating Email with SPF in Amazon SES (p. 92).
Removing a MAIL FROM Domain with Amazon SES

If you want to use the default Amazon SES MAIL FROM domain, you can remove the custom MAIL
FROM domain configuration from the verified identity.
The following procedures show how to use the Amazon SES console to remove a custom MAIL FROM
domain from the configuration of a verified email address or domain. If you want to use the Amazon
SES API instead, see the SetIdentityMailFromDomain API in the Amazon Simple Email Service
API Reference.
To remove a custom MAIL FROM domain from the configuration of a verified email
address
1.
navigate to it:
a.
b.

50

2.
In the verified email address list, choose the verified email address for which you want to remove
the custom MAIL FROM domain.
3.
4.
Choose Remove MAIL FROM Domain.
5.
Choose Yes, Remove MAIL FROM Domain.
6.
(Optional) Log in to your DNS service and remove the MX record that you published when you set
up the MAIL FROM domain with Amazon SES.
7.
(Optional) Remove the SPF record that you published when you set up the custom MAIL FROM
domain with Amazon SES.
To remove a custom MAIL FROM domain from the configuration of a verified domain
1.
to it:
a.
b.
2.
In the verified domain list, choose the verified domain for which you want to remove the custom
MAIL FROM domain.
3.
4.
Choose Remove MAIL FROM Domain.
5.
Choose Yes, Remove MAIL FROM Domain.
6.
(Optional) Log in to your DNS service and remove the MX record that you published when you set
up the MAIL FROM domain with Amazon SES.
7.
(Optional) Remove the SPF record that you published when you set up the custom MAIL FROM
domain with Amazon SES.
Editing a MAIL FROM Domain with Amazon SES

The following procedures show how to use the Amazon SES console to edit the custom MAIL FROM
domain configuration of a verified email address or domain. If you want to use the Amazon SES
API instead, see the SetIdentityMailFromDomain API in the Amazon Simple Email Service API
Reference.
To edit the MAIL FROM configuration of a verified email address

1.
navigate to it:
a.
b.
2.
In the verified email address list, choose the email address for which you want to configure the
MAIL FROM domain.
3.
4.
Choose Edit MAIL FROM Domain.
5.
In the Edit MAIL FROM Domain dialog box, edit the settings and then choose Save MAIL FROM
Domain.
6.
If you changed the MAIL FROM domain name when you edited the settings, you must publish an
MX record to the DNS server of the new MAIL FROM domain.
51

7.
a.
b.
If your domain does not use Amazon Route 53, then you must publish the displayed MX
record to the MAIL FROM domain's DNS server yourself. The procedure for adding an MX
record to your domain's DNS server depends on who provides your DNS service; please
see the documentation for your DNS service. After Amazon SES detects the record, emails
you send from this verified email address will use the specified MAIL FROM domain. Until
then, Amazon SES will either use the default MAIL FROM domain or reject the message,
depending on the preferences you specified earlier in this procedure. Amazon SES can take
up to 72 hours to detect your MX record.
(Optional) If you changed the MAIL FROM domain name and you want Sender Policy Framework
(SPF) checks to succeed, you must publish an SPF record to your MAIL FROM domain's DNS
server to show receiving mail servers that you have authorized Amazon SES to send email on
behalf of your domain. For more information, see Authenticating Email with SPF in Amazon
SES (p. 92).
To edit the MAIL FROM configuration of a verified domain

1.
to it:
a.
b.
2.
In the verified domain list, choose the domain for which you want to configure the MAIL FROM
domain.
3.
4.
Choose Edit MAIL FROM Domain.
5.
In the Edit MAIL FROM Domain dialog box, edit the settings and then choose Save MAIL FROM
Domain.
6.
If you changed the MAIL FROM domain name when you edited the settings, you must publish an
MX record to the DNS server of the new MAIL FROM domain.
7.
a.
b.
If your domain does not use Amazon Route 53, then you must publish the displayed MX
record to the MAIL FROM domain's DNS server yourself. The procedure for adding an MX
record to your domain's DNS server depends on who provides your DNS service; please see
the documentation for your DNS service. After Amazon SES detects the record, emails you
send from this verified domain will use the specified MAIL FROM domain. Until then, Amazon
SES will either use the default MAIL FROM domain or reject the message, depending on the
preferences you specified earlier in this procedure. Amazon SES can take up to 72 hours to
detect your MX record.
(Optional) If you changed the MAIL FROM domain name and you want Sender Policy Framework
(SPF) checks to succeed, you must publish an SPF record to your MAIL FROM domain's DNS
server to show receiving mail servers that you have authorized Amazon SES to send email on
behalf of your domain. For more information, see Authenticating Email with SPF in Amazon
SES (p. 92).

52

Setting up SPF Records
MAIL FROM Domain Setup States with Amazon SES

After you configure an identity to use a custom MAIL FROM domain, the state of the setup is "pending"
while Amazon SES attempts to detect the required MX record in your DNS settings. The state then
changes depending on whether Amazon SES detects the MX record. The following table describes the
email-sending behavior, and the Amazon SES actions associated with each state. Each time the state
changes, Amazon SES sends a notification to the email address associated with your AWS account.
State
Email Sending Behavior
Amazon SES
Actions
Pending
Uses custom MAIL FROM fallback setting
Amazon SES
attempts to detect
the required
MX record for
72 hours. If
unsuccessful, the
state changes to
"Failed".
Success
Uses custom MAIL FROM domain
Amazon SES
continuously
checks that the
required MX
record is in place.
TemporaryFailure
Amazon SES
attempts to detect
the required
MX record for
72 hours. If
unsuccessful, the
state changes
to "Failed"; if
successful, the
state changes to
"Success".
Failed
Amazon SES no
longer attempts
to detect the
required MX
record. To use
a custom MAIL
FROM domain,
you must restart
the setup process
in Setting a
MAIL FROM
Domain (p. 47).
Setting up SPF Records for Amazon SES

An SPF record indicates to ISPs that you have authorized Amazon SES to send mail for your domain.
When you use Amazon SES, your decision about whether to publish an SPF record depends on
whether you only require your email to pass an SPF check by the receiving mail server, or if you
want your email to comply with the additional requirements needed to pass Domain-based Message
53

Getting Your SMTP Credentials
Authentication, Reporting and Conformance (DMARC) authentication based on SPF. For more
information, see Authenticating Email with SPF in Amazon SES (p. 92).
Getting Your SMTP Credentials for Amazon SES

To use the Amazon SES SMTP interface, you must first create an SMTP user name and password. To
get your SMTP Credentials, see Obtaining Your Amazon SES SMTP Credentials (p. 57).
Important
Your SMTP user name and password are not the same as your AWS access key ID and
secret access key. Do not attempt to use your AWS credentials to authenticate yourself to the
Amazon SES SMTP endpoint. For more information about credentials, see Using Credentials
With Amazon SES (p. 323).
Moving Out of the Amazon SES Sandbox

To help protect our customers from fraud and abuse and to help you establish your trustworthiness to
ISPs and email recipients, we do not immediately grant unlimited Amazon SES usage to new users.
New users are initially placed in the Amazon SES sandbox. In the sandbox, you have full access to
all Amazon SES email-sending methods and features so that you can test and evaluate the service;
however, the following restrictions are in effect:
You can only send mail to the Amazon SES mailbox simulator and to verified email addresses and
domains.
You can only send mail from verified email addresses and domains.
You can send a maximum of 200 messages per 24-hour period.
Amazon SES can accept a maximum of one message from your account per second.
To remove the restriction on recipient addresses and increase your sending limits, you need to open a
case in Support Center by using the following instructions.
To move out of the Amazon SES sandbox

1.
Sign in to the AWS Management Console.
2.
Open an SES Sending Limits Increase case. To navigate to case creation, you can go to Support
Center, choose Create Case, choose Service Limit Increase, and then select SES Sending
Limits as the limit type.
3.
In the form, provide the following information:

Region: Select the AWS region for which you are requesting a sending limit increase. Note that
your Amazon SES sandbox status and sending limits are separate for each AWS region. For
more information, see Regions and Amazon SES (p. 332).
Limit: Select Desired Daily Sending Quota or Desired Maximum Send Rate. Sending limits are
described in Managing Your Amazon SES Sending Limits (p. 192).
Note
The rate at which Amazon SES accepts your messages might be less than the
maximum send rate.
New limit value:Enter the amount you are requesting. Be sure to only request the amount
you think you'll need. Keep in mind that you are not guaranteed to receive the amount
you request, and the higher the limit you request, the more justification you will need to be
considered for that amount.
Mail type: Select Transactional, System Notifications, Subscription, Marketing, or Other.
Website URL. Provide a link to your website. Although it isn't required, we highly recommend
that you provide one if you have it, because it helps us evaluate your request.
54

Sending Your Email
My email-sending complies with the AWS Service Terms and AWS Acceptable Use Policy
(AUP). Select Yes or No.
I only send to recipients who have specifically requested my mail. Select Yes or No. For
tips on how to send high-quality mail and keep your recipient list clean, see Obtaining and
Maintaining Your Recipient List (p. 228) and the Amazon Simple Email Service Email Sending
Best Practices whitepaper.
I have a process to handle bounces and complaints. Select Yes or No. For information
on how to monitor and handle bounces and complaints, see Processing Bounces and
Complaints (p. 228).
Use Case Description. Explain your situation in as much detail as possible. For example,
describe the type of emails you are sending and how email-sending fits into your business.
The more information you can provide that indicates that you are sending high-quality emails to
recipients who want and expect it, the more likely we are to approve your request. The higher
the limit value you are requesting, the more detail you should provide.
We will respond to the case after reviewing your request. Please allow one business day for
processing. If you are granted a sending limit increase, then you have also been moved out of the
sandbox and no longer need to verify your "To" addresses.
The following are three ways to determine whether you have moved out of the sandbox:
The correspondence in your SES Sending Limits Increase case indicates that your request has been
granted.
You can successfully use Amazon SES to send an email message from your verified email address
to an unverified address that you own. If you receive a MessageRejected error instead, stating that
your email address is not verified, then you are still in the sandbox.
The Amazon SES console shows that your sending quota is higher than 200 messages per 24-hour
period. To learn more, see Monitoring Your Amazon SES Sending Limits (p. 193).
Once you are out of the sandbox, you no longer have to verify "To" addresses or domains; however,
you must still verify any additional "From" or "Return-Path" addresses or domains. Over time, Amazon
SES will gradually increase your sending limits, or you can open another SES Sending Limits Increase
case if the gradual increase does not meet your needs. For more information, see Managing Your
Amazon SES Sending Limits (p. 192).
Sending Your Email with Amazon SES

You can send an email with Amazon Simple Email Service (Amazon SES) by using the Amazon
SES console, the Amazon SES Simple Mail Transfer Protocol (SMTP) interface, or the Amazon SES
API. You typically use the console to send test emails and manage your sending activity. To send
bulk emails, you use either the SMTP interface or the API. For information about Amazon SES email
pricing, see Amazon SES Pricing.
If you want to use an SMTP-enabled software package, application, or programming language to
send email through Amazon SES, or integrate Amazon SES with your existing mail server, use the
Amazon SES SMTP interface. For more information, see Using the Amazon SES SMTP Interface to
Send Email (p. 56).
If you want to call Amazon SES by using raw HTTP requests, use the Amazon SES API. For more
information, see Using the Amazon SES API to Send Email (p. 87).
Before you send emails, see Setting up Email with Amazon SES (p. 37).
55

Using the SMTP Interface
Important
When you send an email to multiple recipients (recipients are "To", "CC", and "BCC"
addresses) and the call to Amazon SES fails, the entire email is rejected and none of the
recipients will receive the intended email. We therefore recommend that you send an email to
one recipient at a time.
Using the Amazon SES SMTP Interface to Send

Email
To send production email through Amazon SES, you can use the Simple Mail Transfer Protocol
(SMTP) interface or the Amazon SES API. For more information about the Amazon SES API, see
Using the Amazon SES API to Send Email (p. 87). This section describes the SMTP interface.
Amazon SES sends email using the SMTP, the most common email protocol on the Internet. You
can send email through Amazon SES by using a variety of SMTP-enabled programming languages
and software to connect to the Amazon SES SMTP interface. This section explains how to get your
Amazon SES SMTP credentials, how to send email by using the SMTP interface, and how to configure
several pieces of software and mail servers to use Amazon SES for email sending.
Note
For solutions to common problems that you might encounter when you use Amazon SES
through its SMTP interface, see Amazon SES SMTP Issues (p. 238).
To send email using the Amazon SES SMTP interface, you will need the following:
An AWS account. For more information, see Signing up for AWS (p. 38).
The SMTP interface hostname (i.e., endpoint). For a list of Amazon SES SMTP endpoints, see
Connecting to the Amazon SES SMTP Endpoint (p. 61).
The SMTP interface port number. The port number varies with the connection method. For more
An SMTP user name and password. You can use the same set of SMTP credentials in all AWS
regions.
Important
Your SMTP user name and password are not identical to your AWS access keys or the
credentials you use to log into the Amazon SES console. For information about how to
generate your SMTP user name and password, see Obtaining Your Amazon SES SMTP
Credentials (p. 57).
Client software that can communicate using Transport Layer Security (TLS). For more information,
see Connecting to the Amazon SES SMTP Endpoint (p. 61).
An email address that you have verified with Amazon SES. For more information, see Verifying
Email Addresses and Domains in Amazon SES (p. 39).
Higher sending limits, if you want to send large quantities of email. For more information, see
Managing Your Amazon SES Sending Limits (p. 192).
Then, you can send email by doing the following:
To configure an email client to send email through Amazon SES, including an example for Microsoft
Outlook, see Configuring Email Clients to Send Through Amazon SES (p. 62).
56

To configure SMTP-enabled software to send email through the Amazon SES SMTP interface,
including an example for issue-tracking software Jira, see Sending Email Through Amazon SES
From Software Packages (p. 66).
To program an application to send email through Amazon SES, see Sending Email Through Amazon
SES From Your Application (p. 67).
To configure your existing email server to send all of your outgoing mail through Amazon SES, see
Integrating Amazon SES with Your Existing Email Server (p. 67).
To interact with the Amazon SES SMTP interface using the command line, which can be useful
for testing, see Using the Command Line to Send Email Through the Amazon SES SMTP
Interface (p. 85).
For a list of SMTP response codes, see SMTP Response Codes Returned by Amazon SES (p. 240).
Email Information to Provide

When you access Amazon SES through the SMTP interface, your SMTP client application assembles
the message, so the information you need to provide depends on the application you are using. At a
minimum, the SMTP exchange between a client and a server requires a source address, a destination
address, and message data.
If you are using the SMTP interface and have feedback forwarding enabled, then your bounces,
complaints, and delivery notifications are sent to the "MAIL FROM" address. Any "Reply-To" address
that you specify is not used.
Obtaining Your Amazon SES SMTP Credentials

You need an Amazon SES SMTP user name and password to access the Amazon SES SMTP
interface. You can use the same set of SMTP credentials in all AWS regions.
Important
Your SMTP user name and password are not the same as your AWS access key ID and
secret access key. Do not attempt to use your AWS credentials to authenticate yourself
against the SMTP endpoint. For more information about credentials, see Using Credentials
With Amazon SES (p. 323).
There are two ways to generate your SMTP credentials. You can either use the Amazon SES console
or you can generate your SMTP credentials from your AWS credentials.
Use the Amazon SES console to generate your SMTP credentials if:
You want to get your SMTP credentials using the simplest method.
You do not need to automate SMTP credential generation using code or a script.
Generate your SMTP credentials from your AWS credentials if:
You have an existing AWS Identity and Access Management (IAM) user that you created using
the IAM interface and you want that user to be able to send emails using the Amazon SES SMTP
interface.
You want to automate SMTP credential generation using code or a script.
For information on each method, see Obtaining Amazon SES SMTP Credentials Using the Amazon
SES Console (p. 58) and Obtaining Amazon SES SMTP Credentials by Converting AWS
57

Obtaining Amazon SES SMTP Credentials Using the Amazon SES Console
When you generate SMTP credentials by using the Amazon SES console, the Amazon SES console
creates an IAM user with the appropriate policies to call Amazon SES and provides you with the SMTP
credentials associated with that user.
Note
An IAM user can create Amazon SES SMTP credentials, but the IAM user's policy must give
them permission to use IAM itself, because Amazon SES SMTP credentials are created
through IAM. If the IAM user tries to create Amazon SES SMTP credentials using the console
and they don't have IAM permissions, they will get an error that says " not authorized to
perform iam:ListUsers" In that case, the root account owner needs to modify the IAM user's
policy to allow them to access the following IAM actions: "iam:ListUsers", "iam:CreateUser",
"iam:CreateAccessKey", and "iam:PutUserPolicy".
To create your SMTP credentials

1.
2.
In the navigation pane, choose SMTP Settings.
3.
In the content pane, choose Create My SMTP Credentials.
4.
In the Create User for SMTP dialog box, you will see that an SMTP user name has been filled in
for you. You can accept this suggested user name or enter a different one. To proceed, choose
Create.
5.
Choose Show User SMTP Credentials. Your SMTP credentials will be displayed on the screen;
copy them and store them in a safe place. You can also choose Download Credentials to
download a file that contains your credentials.
Important
This is the only time that you will be able to view your SMTP credentials! We strongly
advise you to download these credentials and refrain from sharing them with others.
6.
Choose Close Window.

58

If you want to delete your SMTP credentials, go to the IAM console at https://
console.aws.amazon.com/iam/ and delete the IAM user name that corresponds with your SMTP
credentials. To learn more, go to the Using IAM guide.
If you want to change your SMTP password, go to the IAM console and delete your existing IAM user,
and then go to the Amazon SES console to re-generate your SMTP credentials.
Obtaining Amazon SES SMTP Credentials by Converting AWS Credentials

If you have an IAM user that you set up using the IAM interface, you can derive the user's Amazon
SES SMTP credentials from their AWS credentials.
Important
Do not use temporary AWS credentials to derive SMTP credentials. The Amazon SES SMTP
interface does not support SMTP credentials that have been generated from temporary
security credentials.
To enable the IAM user to send email using the Amazon SES SMTP interface, you need to do the
following two steps:
Derive the user's SMTP credentials from their AWS credentials using the algorithm provided in this
section. Because you are starting from AWS credentials, the SMTP username will be the same as
the AWS access key ID, so you just need to generate the SMTP password.
Important
If you generate SMTP credentials using the Amazon SES console, the SMTP username is
not the same as the AWS access key ID. The SMTP username and the AWS access key
ID are only the same if you generate the SMTP password programmatically, as described in
this section.
Apply the following policy to the IAM user:
{ "Statement": [{
"Effect":"Allow",
"Action":"ses:SendRawEmail",
"Resource":"*"
}]}
For more information about using Amazon SES with IAM, see Controlling Access to Amazon
SES (p. 307).
Note
Although you can generate Amazon SES SMTP credentials for any existing IAM user, we
recommend for security reasons that you create a separate IAM user for the AWS credentials
that you will use to generate the SMTP password. For information about why it is good
practice to create users for specific purposes, go to IAM Best Practices.
The following pseudocode shows the algorithm that converts an AWS Secret Access Key to an
Amazon SES SMTP password.
key = AWS Secret Access Key;
message = "SendRawEmail";
versionInBytes = 0x02;
signatureInBytes = HmacSha256(message, key);
signatureAndVer = Concatenate(versionInBytes, signatureInBytes);
smtpPassword = Base64(signatureAndVer);
The following is an example Java implementation that converts an AWS Secret Access Key to an
Amazon SES SMTP password. Before you run the program, put the AWS Secret Access Key of
59

the IAM user into an environment variable called AWS_SECRET_ACCESS_KEY. The output of
the program is the SMTP password. That password, along with the SMTP username (which, if you
generate the SMTP password programmatically, is the same as the AWS access key ID) are the user's
Amazon SES SMTP credentials.
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
public class SesSmtpCredentialGenerator {
private static final String KEY_ENV_VARIABLE =
"AWS_SECRET_ACCESS_KEY"; // Put your AWS secret access key in this
environment variable.
private static final String MESSAGE = "SendRawEmail"; // Used to
generate the HMAC signature. Do not modify.
private static final byte VERSION = 0x02; // Version number. Do not
modify.
public static void main(String[] args) {
// Get the AWS secret access key from environment variable
AWS_SECRET_ACCESS_KEY.
String key = System.getenv(KEY_ENV_VARIABLE);
if (key == null)
{
System.out.println("Error: Cannot find environment variable
AWS_SECRET_ACCESS_KEY.");
System.exit(0);
}
// Create an HMAC-SHA256 key from the raw bytes of the AWS
secret access key.
SecretKeySpec secretKey = new SecretKeySpec(key.getBytes(),
"HmacSHA256");
try {
// Get an HMAC-SHA256 Mac instance and initialize it
with the AWS secret access key.
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(secretKey);
// Compute the HMAC signature on the input data bytes.
byte[] rawSignature = mac.doFinal(MESSAGE.getBytes());
// Prepend the version number to the signature.
byte[] rawSignatureWithVersion = new
byte[rawSignature.length + 1];
byte[] versionArray = {VERSION};
System.arraycopy(versionArray, 0,
rawSignatureWithVersion, 0, 1);
System.arraycopy(rawSignature, 0,
rawSignatureWithVersion, 1, rawSignature.length);
// To get the final SMTP password, convert the HMAC
signature to base 64.
String smtpPassword =
DatatypeConverter.printBase64Binary(rawSignatureWithVersion);
System.out.println(smtpPassword);

60

}
catch (Exception ex) {
System.out.println("Error generating SMTP password: " +
ex.getMessage());
}
}
}
Connecting to the Amazon SES SMTP Endpoint

The following table shows the Amazon SES SMTP endpoints for the regions in which Amazon SES is
available.
Region name
SMTP endpoint
US East (N. Virginia)
email-smtp.us-east-1.amazonaws.com
US West (Oregon)
email-smtp.us-west-2.amazonaws.com
EU (Ireland)
email-smtp.eu-west-1.amazonaws.com
The Amazon SES SMTP endpoint requires that all connections be encrypted using Transport Layer
Security (TLS). (Note that TLS is often referred to by the name of its predecessor protocol, SSL.)
Amazon SES supports two mechanisms for establishing a TLS-encrypted connection: STARTTLS
and TLS Wrapper. Check the documentation for your software to determine whether it supports
STARTTLS, TLS Wrapper, or both.
If your software does not support STARTTLS or TLS Wrapper, you can use the open source stunnel
program to set up an encrypted connection (called a "secure tunnel"), then use the secure tunnel to
connect to the Amazon SES SMTP endpoint.
Important
Amazon Elastic Compute Cloud (Amazon EC2) throttles email traffic over port 25 by default.
To avoid timeouts when sending email through the SMTP endpoint from EC2, use a different
port (587 or 2587) or fill out a Request to Remove Email Sending Limitations to remove the
throttle.
STARTTLS
STARTTLS is a means of upgrading an unencrypted connection to an encrypted connection. There are
versions of STARTTLS for a variety of protocols; the SMTP version is defined in RFC 3207.
To set up a STARTTLS connection, the SMTP client connects to the Amazon SES SMTP endpoint
on port 25, 587, or 2587, issues an EHLO command, and waits for the server to announce that it
supports the STARTTLS SMTP extension. The client then issues the STARTTLS command, initiating
TLS negotiation. When negotiation is complete, the client issues an EHLO command over the new
encrypted connection, and the SMTP session proceeds normally.
TLS Wrapper
TLS Wrapper (also known as SMTPS or the Handshake Protocol) is a means of initiating an encrypted
connection without first establishing an unencrypted connection. With TLS Wrapper, the Amazon SES
SMTP endpoint does not perform TLS negotiation: it is the client's responsibility to connect to the
endpoint using TLS, and to continue using TLS for the entire conversation. TLS Wrapper is an older
protocol, but many clients still support it.
To set up a TLS Wrapper connection, the SMTP client connects to the Amazon SES SMTP endpoint
on port 465 or 2465. The server presents its certificate, the client issues an EHLO command, and the
SMTP session proceeds normally.
61

Secure Tunnel
If your software does not support STARTTLS or TLS Wrapper, you can set up a secure tunnel to allow
your software to communicate with the Amazon SES SMTP endpoint. As this option is most commonly
used by mail server administrators, details are given under Integrating Amazon SES with Your Existing
Email Server (p. 67).
Configuring Email Clients to Send Through Amazon SES

After you obtain your SMTP user name and password (p. 57), you can send email through Amazon
SES. You can use any email client application that supports SMTP and can connect to an SMTP
endpoint using Transport Layer Security (TLS).
The following procedure shows how to configure one such client, Microsoft Outlook 2013, to send
email through the Amazon SES SMTP interface. If you are using a different email client, follow the
instructions provided by the client vendor, and use the settings described in the following procedure.
To configure Microsoft Outlook 2013 for sending via Amazon SES

1.
In Microsoft Outlook, choose File, and then choose Info.
2.
Choose Add Account.
3.
In the Add Account dialog box, choose Manual setup or additional server types, and then
choose Next.
4.
Under Choose Service, choose POP or IMAP, and then choose Next.
5.
Under POP and IMAP Account Settings, fill in the following fields:
a.
Your Name Type your name.
b.
Email Address Type the email address from which you will send emails. You must verify
this email address or domain (p. 39). The email address is case-sensitive. Make sure that
the address is exactly the same as the one you verified.
c.
Account TypeChoose POP3.
d.
Incoming mail server Type none. (Even though you are setting up Amazon SES for
outgoing email only, this field is required.)
e.
Outgoing mail server (SMTP)Type the SMTP endpoint for the outgoing mail server.
For a list of Amazon SES SMTP endpoints, see Connecting to the Amazon SES SMTP
Endpoint (p. 61). For example, if you use the Amazon SES endpoint in the US West
(Oregon) Region, the outgoing mail server is email-smtp.us-west-2.amazonaws.com.
f.
User Name Type none. (You will configure your credentials later in this procedure.)

62

6.
Choose More Settings.
7.
In the Internet E-mail Settings dialog box, choose the Outgoing Server tab and fill in the
following fields:
a.
My outgoing server (SMTP) requires authenticationCheck this box.
b.
Log on usingChoose this option.
c.
User NameEnter your SMTP user name credential, which is the string of letters and
numbers you obtained using the procedure in Obtaining Your Amazon SES SMTP
Important
Your SMTP user name (p. 57) is not the same as your AWS access key ID.
d.
Password Enter your SMTP password, which is the string of letters and numbers you
obtained using the procedure in Obtaining Your Amazon SES SMTP Credentials (p. 57).
Important
Your SMTP password (p. 57) is not the same as your AWS secret access key.
e.
Remember PasswordSelect this box.

63

8.
Choose the Advanced tab, and then fill in the following fields.
Note
This example shows a typical configuration. For alternative configurations, see
Connecting to the Amazon SES SMTP Endpoint (p. 61). The Outlook-encrypted
connection type labeled TLS corresponds to STARTTLS (p. 61), and the Outlookencrypted connection type labeled SSL corresponds to TLS Wrapper (p. 61).
a.
Outgoing server (SMTP) Type 587.
b.
Use the following type of encrypted connection Choose TLS.

64

9.
Choose OK.
10. On the Add Account page, choose Test Account Settings. This lets you test your setup by
having Outlook send an email through Amazon SES.
Note
Because you are using Amazon SES as your outgoing email server only, the Log onto
incoming mail server test is expected to fail. The Send test e-mail test should pass.
11. If the test message that Outlook sends through Amazon SES arrives successfully, clear the Test
Account Settings by clicking the Next button check box (because the test will fail without
setting up incoming email) and then choose Next.
12. Choose Next, and then choose Finish.
13. You set up Amazon SES for email sending only. To ensure that the account is not set up to
receive messages using Amazon SES, you must disable mail retrieval for the account by using the
following steps.
a.
In Microsoft Outlook, choose the Send/Receive tab.
b.
On the Send/Receive tab, choose Send/Receive Groups, and then choose Define Send/
Receive Groups.
c.
In the Send/Receive Groups dialog box, choose Edit.
d.
In the Accounts section on the left, choose the account you just created for sending mail
through Amazon SES.
e.
Under Account Options, clear Receive mail items.
f.
Choose OK, and then choose Close.

65

Sending Email Through Amazon SES From Software

Packages
There are a number of commercial and open source software packages that support sending email via
SMTP. Here are some examples:
Blogging platforms
RSS aggregators
List management software
Workflow systems
You can configure any such SMTP-enabled software to send email through the Amazon SES SMTP
interface. For instructions on how to configure SMTP for a particular software package, see the
documentation for that software.
The following procedure shows how to set up Amazon SES sending in JIRA, a popular issue-tracking
solution. With this configuration, JIRA can notify users via email whenever there is a change in the
status of a software issue.
To Configure JIRA to Send Email Using Amazon SES

1.
Using your web browser, log in to JIRA with administrator credentials.
2.
In the browser window, choose Administration.
3.
On the System menu, choose Mail.
4.
On the Mail administration page, choose Mail Servers.
5.
Choose Configure new SMTP mail server.
6.
On the Add SMTP Mail Server form, fill in the following fields:
a.
NameA descriptive name for this server.
b.
From addressThe address from which email will be sent. You will need to verify this
email address with Amazon SES before you can send from it. For more information about
verification, see Verifying Email Addresses and Domains in Amazon SES (p. 39).
c.
Email prefixA string that JIRA prepends to each subject line prior to sending.
d.
ProtocolChoose SMTP.
Note
If you cannot connect to Amazon SES using this setting, try SECURE_SMTP.
e.
Host NameSee Connecting to the Amazon SES SMTP Endpoint (p. 61) for a
list of Amazon SES SMTP endpoints. For example, if you want to use the Amazon
SES endpoint in the US West (Oregon) region, the host name would be email-smtp.uswest-2.amazonaws.com.
f.
SMTP Port25, 587, or 2587 (to connect using STARTTLS), or 465 or 2465 (to connect
using TLS Wrapper).
g.
TLSSelect this check box.
h.
UsernameYour SMTP username.
i.
PasswordYour SMTP password.
Settings for TLS Wrapper are shown below.

66

7.
Choose Test Connection. If the test email that JIRA sends through Amazon SES arrives
successfully, then your configuration is complete.
Sending Email Through Amazon SES From Your Application

Many programming languages support sending email using SMTP. This capability might be built into
the programming language itself, or it might be available as an add-on, plug-in, or library. You can take
advantage of this capability by sending email through Amazon SES from within application programs
that you write.
For examples in C# and Java, see Send an Email by Accessing the Amazon SES SMTP Interface
Programmatically (p. 19) in the Getting Started section.
Integrating Amazon SES with Your Existing Email Server

If you currently administer your own email server, you can use the Amazon SES SMTP endpoint to
send all of your outgoing email to Amazon SES. There is no need to modify your existing email clients
and applications; the changeover to Amazon SES will be transparent to them.
Several mail transfer agents (MTAs) support sending email through SMTP relays. This section
provides general guidance on how to configure some popular MTAs to send email using Amazon SES
SMTP interface.
To configure Postfix to send email through Amazon SES, see Integrating Amazon SES with
Postfix (p. 69).
To configure Sendmail to send email through Amazon SES, see Integrating Amazon SES with
Sendmail (p. 72).
To configure Microsoft Exchange to send email through Amazon SES, see Integrating Amazon SES
with Microsoft Exchange (p. 77).
To configure Microsoft Windows Server's IIS SMTP server to send email through Amazon SES, see
Integrating Amazon SES with Microsoft Windows Server IIS SMTP (p. 82).
To configure Exim to send email through Amazon SES, see Integrating Amazon SES with
Exim (p. 83).

67

Security (TLS). If you want to use TLS Wrapper but your MTA does not support TLS Wrapper, you
can set up a "secure tunnel" to provide TLS Wrapper support. For more information, see Setting Up a
Secure Tunnel to Connect to Amazon SES (p. 68).
Setting Up a Secure Tunnel to Connect to Amazon SES

Security (TLS). If you want to use TLS Wrapper to connect to the Amazon SES SMTP endpoint, but
your MTA does not support TLS Wrapper, you can set up a "secure tunnel" to provide TLS Wrapper
support. One way to do this is by using the open source stunnel program. Note that stunnel is intended
to be used for port 465, the SSL port, only.
Important
Some MTAs have native support for TLS Wrapper, while others do not. Check the
documentation for your mail server to determine whether it supports TLS Wrapper. If it
supports TLS Wrapper, then you do not need to set up a secure tunnel.
These instructions were tested on a 64-bit Amazon EC2 instance using the following Amazon Machine
Image (AMI), which is based on Red Hat:
Amazon Linux AMI 2014.09.2 (HVM) (ami-146e2a7c).
To launch an Amazon EC2 instance, which includes selecting an AMI, see Amazon Machine Images
(AMIs).
To set up a secure tunnel to the Amazon SES US West (Oregon) endpoint using stunnel
1.
Download and install the stunnel software. For information, go to http://www.stunnel.org.
2.
If you are using Ubuntu Linux, stunnel may require a certificate. To generate the certificate, go to
the /etc/stunnel directory and at a command prompt, type the following:
sudo openssl req -new -out mail.pem -keyout mail.pem -nodes -x509 -days
365
3.
Open or create a file called /etc/stunnel/stunnel.conf.
4.
To configure the secure tunnel, add the following lines to stunnel.conf. For the accept line, specify
a port number that is outside the range of reserved ports and is not currently being used. For this
example, we will use port 2525 for this purpose.
These instructions assume that you want to use Amazon SES in the US West (Oregon)
AWS region. If you want to use a different region, replace the instance of email-smtp.uswest-2.amazonaws.com in these instructions with the SMTP endpoint of the desired region. For a
list of SMTP endpoints, see Regions and Amazon SES (p. 332).
Important
Be sure to include delay = yes, which delays the DNS look-up until it is needed.
Otherwise, the stunnel connection may fail.
[smtp-tls-wrapper]
accept = 2525
client = yes
connect = email-smtp.us-west-2.amazonaws.com:465
delay = yes
5.
If you are using stunnel version 4.36 or lower, add this additional line to stunnel.conf:
68

sslVersion = TLSv1
6.
If you are using Ubuntu Linux, add this additional line to stunnel.conf:
cert = /etc/stunnel/mail.pem
7.
Save stunnel.conf.
8.
At a command prompt, issue the following command to start stunnel:

sudo stunnel /etc/stunnel/stunnel.conf
9.
At a command prompt, type the following command to verify that the tunnel has been created.
We are using port 2525 for this example; if you have specified a different port number, modify the
command accordingly.
telnet localhost 2525
Integrating Amazon SES with Postfix

Postfix was created as an alternative to the widely used Sendmail MTA. For information about Postfix,
go to http://www.postfix.org.
Image (AMI), which is based on Red Hat:
Amazon Linux AMI 2014.09.2 (HVM) (ami-146e2a7c).
(AMIs).
Prerequisites
Before you perform one of the following procedures, verify the following:
You have uninstalled Sendmail (if you are not sure how to switch between Sendmail and Postfix).
You have installed Postfix.
You are able to successfully send an email using Postfix without Amazon SES.
You have verified your "From" address and, if your account is still in the sandbox, you have also
verified your "To" addresses. For more information, see Verifying Email Addresses in Amazon
SES (p. 39).
(Optional) If you are sending email through Amazon SES from an Amazon EC2 instance, you may
need to assign an Elastic IP Address to your Amazon EC2 instance for the receiving ISP to accept
your email. For more information, see Amazon EC2 Elastic IP Addresses.
(Optional) If you are sending email through Amazon SES from an Amazon EC2 instance, you
can fill out a Request to Remove Email Sending Limitations to remove the additional sending limit
restrictions that are applied to port 25 by default.
To configure integration with the Amazon SES US West (Oregon) endpoint using
STARTTLS
1.
On your mail server, open the main.cf file. On many systems, this file resides in the /etc/postfix
folder.
Important
AWS region. If you want to use a different region, replace all instances of email-smtp.usAPI Version 2010-12-01
69

west-2.amazonaws.com in these instructions with the SMTP endpoint of the desired

region. For a list of SMTP endpoints, see Regions and Amazon SES (p. 332).
2.
Add the following lines to the main.cf file.

relayhost = [email-smtp.us-west-2.amazonaws.com]:25
smtp_sasl_auth_enable = yes
smtp_sasl_security_options = noanonymous
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_use_tls = yes
smtp_tls_security_level = encrypt
smtp_tls_note_starttls_offer = yes
Save and close the main.cf file.

3.
On your mail server, open the master.cf file. On many systems, this file resides in the /etc/postfix
folder.
4.
Comment out the following line of the master.cf file by putting a # in front of it: -o
smtp_fallback_relay=
Save and close the master.cf file.
5.
Edit the /etc/postfix/sasl_passwd file. If the file does not exist, create it. Add the following lines to
the file, replacing USERNAME and PASSWORD with your SMTP user name and password. If
Postfix cannot authenticate with the Amazon SES SMTP endpoint because the hostname does not
match, try adding the additional line specified in Amazon SES SMTP Issues (p. 238).
Important
Use your SMTP user name and password, not your AWS access key ID and secret
access key. Your SMTP credentials and your AWS credentials are not the same. For
information about how to obtain your SMTP credentials, see Obtaining Your Amazon SES
[email-smtp.us-west-2.amazonaws.com]:25 USERNAME:PASSWORD
Save and close the sasl_passwd file.

6.
At a command prompt, issue the following command to create a hashmap database file containing
your SMTP credentials.
sudo postmap hash:/etc/postfix/sasl_passwd
7.
(Optional but recommended) Remove the /etc/postfix/sasl_passwd file.
8.
(Optional but recommended) The /etc/postfix/sasl_passwd and /etc/postfix/sasl_passwd.db files

you created in the previous steps are not encrypted. Because these files contain your SMTP
credentials, it is a good idea to use the following commands to change the owner to root and
set permissions to restrict access to the files as much as possible. (Note that if you deleted /etc/
postfix/sasl_passwd in the previous step, you should omit it from the commands below.)
sudo chown root:root /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
sudo chmod 0600 /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
9.
Tell Postfix where to find the CA certificate (needed to verify the Amazon SES server certificate).
You could use a self-signed certificate or you could use default certificates as follows:
If running on the Amazon Linux AMI:
sudo postconf -e 'smtp_tls_CAfile = /etc/ssl/certs/ca-bundle.crt'
If running on Ubuntu Linux:

70

sudo postconf -e 'smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt'
10. When you have finished updating the configuration, stop and start Postfix by typing the following at
the command line:
sudo postfix stop
sudo postfix start
11. Send a test email by typing the following at a command line, pressing Enter after each line. Note
that you must replace [email protected] with your "From" email address, which you must have
previously verified with Amazon SES. Replace [email protected] with your "To" address. If your
account is still in the sandbox, the "To" address must also be verified. Also note that the final line
is a single period.
sendmail -f [email protected] [email protected]
From: [email protected]
Subject: Test
This email was sent through Amazon SES!
.
12. Check your inbox for the email. If the message was not delivered, check your Junk box, and then
check your system's mail log (typically /var/log/maillog) for errors. For example, you will get an
"Email address not verified" error if you have not verified the "From" address that follows "-f" on the
command line.
To configure integration using a secure tunnel

1.
To begin, you will need to set up a secure tunnel as described in Setting Up a Secure Tunnel to
Connect to Amazon SES (p. 68). In the following procedure, we use port 2525 as your stunnel
port. If you are using a different port, modify the settings that you actually use accordingly.
2.
On your mail server, open the main.cf file. On many systems, this file resides in the /etc/postfix
folder.
3.
Add the following lines to the main.cf file.

relayhost = 127.0.0.1:2525
smtp_sasl_auth_enable = yes
smtp_sasl_security_options = noanonymous
smtp_tls_security_level = may
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
Save and close the main.cf file.

4.
On your mail server, open the master.cf file. On many systems, this file resides in the /etc/postfix
folder.
5.
Comment out the following line of the master.cf file by putting a # in front of it: -o
smtp_fallback_relay=
Save and close the master.cf file.
6.
Edit the /etc/postfix/sasl_passwd file. If the file does not exist, create it. Add the following line to
the file, replacing USERNAME and PASSWORD with your SMTP user name and password.
Important
71

information about how to obtain your SMTP credentials, see Obtaining Your Amazon SES
127.0.0.1:2525 USERNAME:PASSWORD
Save the sasl_passwd file.

7.
At a command prompt, issue the following command to create a hashmap database file containing
your SMTP credentials.
sudo postmap hash:/etc/postfix/sasl_passwd
8.
(Optional but recommended) Remove the /etc/postfix/sasl_passwd file.
9.
(Optional but recommended) The /etc/postfix/sasl_passwd and /etc/postfix/sasl_passwd.db files

you created in the previous steps are not encrypted. Because these files contain your SMTP
credentials, it is a good idea to use the following commands to change the owner to root and
set permissions to restrict access to the files as much as possible. (Note that if you deleted /etc/
postfix/sasl_passwd in the previous step, you should omit it from the commands below.)
sudo chown root:root /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
sudo chmod 0600 /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
10. When you have finished updating the configuration, stop and start Postfix by typing the following at
the command line:
sudo postfix stop
sudo postfix start
11. Send a test email by typing the following at a command line, pressing Enter after each line. Note
that you must replace [email protected] with your "From" email address, which you must have
previously verified with Amazon SES. Replace [email protected] with your "To" address. If your
account is still in the sandbox, the "To" address must also be verified. Also note that the final line
is a single period.
sendmail -f [email protected] [email protected]
Subject: Test
This email was sent through Amazon SES!
.
12. Check your inbox for the email. If the message was not delivered, check your Junk box, and then
check your system's mail log (typically /var/log/maillog) for errors. For example, you will get an
"Email address not verified" error if you have not verified the "From" address that follows "-f" on the
command line.
Integrating Amazon SES with Sendmail

Sendmail was released in the early 1980s, and has been continuously improved ever since. It is a very
flexible and configurable MTA, and it has a large installed base. For information about Sendmail, go to
http://www.sendmail.com/sm/open_source/.
The following instructions show you how to configure Sendmail to send email through Amazon SES
using two ways to encrypt the connection: STARTTLS and a secure tunnel.
Image (AMI):
72

Amazon Linux AMI 2015.09.2 (ami-8fcee4e5)

(AMIs).
Prerequisites
Before you perform one of the following procedures, verify the following:
The Sendmail package is installed on your computer, and you are able to successfully send an email
using Sendmail without Amazon SES.
Note
To see if a package is installed on a computer running Red Hat Linux, type rpm -qa |
grep <package>, where <package> is the package name. To see if a package is
installed on a computer running Ubuntu Linux, type dpkg -s <package>.
In addition to the Sendmail package, the following packages are installed on your computer:
sendmail-cf, m4, and cyrus-sasl-plain.
You have verified your "From" address and, if your account is still in the sandbox, you have also
verified your "To" addresses. For more information, see Verifying Email Addresses in Amazon
SES (p. 39).
(Optional) If you are sending email through Amazon SES from an Amazon EC2 instance, you may
need to assign an Elastic IP Address to your Amazon EC2 instance for the receiving ISP to accept
your email. For more information, see Amazon EC2 Elastic IP Addresses.
(Optional) If you are sending email through Amazon SES from an Amazon EC2 instance, you
can fill out a Request to Remove Email Sending Limitations to remove the additional sending limit
restrictions that are applied to port 25 by default.
To configure Sendmail to send email through the Amazon SES endpoint in US West
(Oregon) using STARTTLS
1.
Open the /etc/mail/authinfo file for editing. If the file does not exist, create it.
Important
AWS region. If you want to use a different region, replace all instances of email-smtp.uswest-2.amazonaws.com in these instructions with the SMTP endpoint of the desired
2.
Add the following line to /etc/mail/authinfo, where:

U:rootDo not modify.
I:USERNAMEReplace USERNAME with the Amazon SES username you obtained using the
instructions in Obtaining Your Amazon SES SMTP Credentials (p. 57). This is NOT the same
as your AWS Access Key ID.
P:PASSWORDReplace PASSWORD with the Amazon SES password you obtained using the
as your AWS Secret Key.
M:LOGINReplace LOGIN with the method of authentication to use. For example, PLAIN,
DIGEST-MD5, etc.
AuthInfo:email-smtp.us-west-2.amazonaws.com "U:root" "I:USERNAME"

"P:PASSWORD" "M:LOGIN"
If Sendmail cannot authenticate with the Amazon SES SMTP endpoint because the hostname
does not match, try adding the additional line specified in Amazon SES SMTP Issues (p. 238).
73

3.
Save the authinfo file.
4.
At a command prompt, type the following command to generate /etc/mail/authinfo.db:

sudo makemap hash /etc/mail/authinfo.db < /etc/mail/authinfo
5.
Open the /etc/mail/access file and include support for relaying to the Amazon SES SMTP endpoint
by adding the following line. If Sendmail cannot authenticate with the Amazon SES SMTP
endpoint because the hostname does not match, try adding the additional line specified in Amazon
SES SMTP Issues (p. 238).
Connect:email-smtp.us-west-2.amazonaws.com RELAY
Save the file.

6.
At a command prompt, type the following command to regenerate /etc/mail/access.db:

sudo makemap hash /etc/mail/access.db < /etc/mail/access
7.
Save a back-up copy of /etc/mail/sendmail.mc and /etc/mail/sendmail.cf.
8.
Add the following group of lines to the /etc/mail/sendmail.mc file before any MAILER() definitions.
If you add a FEATURE() line after a MAILER() definition, when you run m4 in a subsequent step,
you will get the following error: "ERROR: FEATURE() should be before MAILER().":
Important
If you are using an AWS region other than US West (Oregon), replace the SMART_HOST
value with the Amazon SES SMTP endpoint of the region you're using, and be sure to
use the ` character and the apostrophe exactly as shown.
define(`SMART_HOST', èmail-smtp.us-west-2.amazonaws.com')dnl
define(`RELAY_MAILER_ARGS', `TCP $h 25')dnl
define(`confAUTH_MECHANISMS', `LOGIN PLAIN')dnl
FEATURE(àuthinfo', `hash -o /etc/mail/authinfo.db')dnl
MASQUERADE_AS(`YOUR_DOMAIN')dnl
FEATURE(masquerade_envelope)dnl
FEATURE(masquerade_entire_domain)dnl
9.
In the text you just added to sendmail.mc, in the line that starts with MASQUERADE_AS, replace
YOUR_DOMAIN with the domain name from which you are sending your email. By adding this
masquerade, you are making email from this host appear to be sent from your domain. Otherwise,
the email will appear as if the email is being sent from the host name of the mail server, and you
may get an "Email address not verified" error when you try to send an email.
10. Save the sendmail.mc file.

11. At a command prompt, type the following command to make sendmail.cf writeable:
sudo chmod 666 /etc/mail/sendmail.cf
12. At a command prompt, type the following command to regenerate sendmail.cf:

sudo m4 /etc/mail/sendmail.mc > /etc/mail/sendmail.cf
Note
If you encounter errors such as "Command not found" and "No such file or directory,"
make sure you have installed the m4 and sendmail-cf packages as specified in the
prerequisites section above.
13. At a command prompt, type the following command to reset the permissions of sendmail.cf to read
only:
14. At a command prompt, type the following command to restart Sendmail:

sudo /etc/init.d/sendmail restart
74

15. Send a test email by doing the following:

1.
At a command prompt, type the following. Note that you should replace [email protected]
with your "From" email address, which you must have verified with Amazon SES. Replace
[email protected] with your "To" address. If your account is still in the sandbox, the "To"
address must also be verified.
sudo /usr/sbin/sendmail -f [email protected] [email protected]
2.
Press <Enter>. Type the body of the message, pressing <Enter> after each line.
3.
When you are finished typing the email, press CTRL+D to send the email.
16. Check the recipient email's client for the email. If you cannot find the email, check the Junk box in
the recipient's email client. If you still cannot find the email, look at the Sendmail log on the mail
server. The log is typically in /var/spool/mail/<user>.
To configure Sendmail to send email through Amazon SES using a secure tunnel
1.
To begin, you will need to set up a secure tunnel as described in Setting Up a Secure Tunnel to
Connect to Amazon SES (p. 68). In the following procedure, we use port 2525 as your stunnel
port. If you are using a different port, modify the settings that you actually use accordingly.
2.
Open the /etc/mail/authinfo file for editing. If the file does not exist, create it.
3.
Add the following lines to /etc/mail/authinfo, where:

U:rootDo not modify.
I:USERNAMEReplace USERNAME with the Amazon SES username you obtained using the
as your AWS Access Key ID.
P:PASSWORDReplace PASSWORD with the Amazon SES password you obtained using the
as your AWS Secret Key.
M:LOGINReplace LOGIN with the method of authentication to use. For example, PLAIN,
DIGEST-MD5, etc.
AuthInfo:127.0.0.1 "U:root" "I:USERNAME" "P:PASSWORD" "M:LOGIN"
4.
Save the authinfo file.
5.
At a command prompt, type the following command:

sudo makemap hash /etc/mail/authinfo.db < /etc/mail/authinfo
6.
Open the /etc/mail/access file to ensure that relaying is allowed for 127.0.0.1. This is the default
behavior. If relaying is not allowed for localhost, open your /etc/hosts file and add another
hostname pointing to 127.0.0.1.
7.
If you modified /etc/mail/access in the last step, at a command prompt, type the following
command to regenerate /etc/mail/access.db:
sudo makemap hash /etc/mail/access.db < /etc/mail/access
8.
Open the /etc/mail/sendmail.mc file and add the following group of lines before any MAILER()
definitions. If you add a FEATURE() line after a MAILER() definition, when you run m4 in a
subsequent step, you will get the following error: "ERROR: FEATURE() should be before
MAILER().":
Important
Be sure to use the ` character and the apostrophe exactly as shown.
75

FEATURE(àuthinfo', `hash -o /etc/mail/authinfo.db')dnl

define(`SMART_HOST', `[127.0.0.1]')dnl
define(`RELAY_MAILER_ARGS', `TCP $h 2525')dnl
define(ÈSMTP_MAILER_ARGS', `TCP $h 2525')dnl
MASQUERADE_AS(`YOUR_DOMAIN')dnl
FEATURE(masquerade_envelope)dnl
FEATURE(masquerade_entire_domain)dnl
9.
In the text you just added to sendmail.mc, in the line that starts with MASQUERADE_AS, replace
YOUR_DOMAIN with the domain name from which you are sending your email. By adding this
masquerade, you are making email from this host appear to be sent from your domain. Otherwise,
the email will appear as if the email is being sent from the host name of the mail server, and you
may get an "Email address not verified" error when you try to send an email.
Also, if you found in Step 5 that relaying was not allowed for 127.0.0.1, change the
`SMART_HOST' line you added to sendmail.mc to use the hostname that you entered in the /etc/
hosts file. That is:
define(`SMART_HOST', `hostname')dnl
10. Save and close the sendmail.mc file.

11. At a command prompt, type the following command to make sendmail.cf writeable:
12. At a command prompt, type the following command to regenerate sendmail.cf:

sudo m4 /etc/mail/sendmail.mc > /etc/mail/sendmail.cf
Note
If you encounter errors such as "Command not found" and "No such file or directory,"
make sure you have installed the m4 and sendmail-cf packages as specified in the
prerequisites section.
13. At a command prompt, type the following command to reset the permissions of sendmail.cf to read
only:
14. At a command prompt, type the following command to restart Sendmail:

sudo /etc/init.d/sendmail restart
15. Send a test email by doing the following:

1.
At a command prompt, type the following. Note that you should replace [email protected]
with your "From" email address, which you must have verified with Amazon SES. Replace
[email protected] with your "To" address. If your account is still in the sandbox, the "To"
address must also be verified.
sudo /usr/sbin/sendmail -f [email protected] [email protected]
2.
Press <Enter>. Type the body of the message, pressing <Enter> after each line.
3.
When you are finished typing the email, press CTRL+D to send the email.
16. Check the recipient email's client for the email. If you cannot find the email, check the Junk box in
the recipient's email client. If you still cannot find the email, look at the Sendmail log on the email
sending computer. The log is typically in /var/spool/mail/<user>.
76

Integrating Amazon SES with Microsoft Exchange

You can configure Microsoft Exchange to send email through Amazon SES. The following procedures
show you how to integrate Microsoft Exchange with Amazon SES using the Microsoft Exchange GUI or
Windows PowerShell.
Important
Follow only one of the following procedures (Microsoft Exchange GUI or Windows
PowerShell). If you follow both procedures, you will get an error stating that you have two
send connectors with the same name.
These instructions were written using Microsoft Exchange 2013.
To integrate Microsoft Exchange with Amazon SES using the Microsoft Exchange GUI
1.
Go to the Microsoft Exchange admin center (typically https://<CASServerName>/ecp) and sign in

as a user who is part of the Exchange administrators group.
2.
From the left menu, choose mail flow.
3.
Choose send connectors.
4.
Choose the plus sign.
5.
Enter a name for the send connector (for example, SES).
6.
Under Type, select Internet.

77

7.
Choose Next.
8.
Select Route mail through smart hosts.

78

9.
Choose the plus sign and then enter the Amazon SES endpoint that you will use (for example,
email-smtp.us-west-2.amazonaws.com). For a list of Amazon SES endpoints, see Regions and
Amazon SES (p. 332).
10. Choose Save. The endpoint you entered will appear in the SMART HOST box.
11. Choose Next.
12. Select Basic authentication, then select Offer basic authentication only after starting TLS,
and then enter your Amazon SES SMTP user name and password.
Important
Your SMTP user name and password are not the same as your AWS access key ID
and secret access key. Do not attempt to use your AWS credentials to authenticate
yourself against the SMTP endpoint. For more information about credentials, see Using
13. Choose Next.

14. Choose the plus sign.
15. Verify that Type is SMTP, FQDN is *, and Cost is 1.

79

16. Choose Save and then choose Next.

17. Choose the plus sign.
18. Select all transport servers you would like to apply this rule to and choose Add. When you have
added all the servers you want to send email through Amazon SES, choose ok.
19. Verify that the servers are added and then choose finish.

80

You should now see a send connector for Amazon SES with an enabled status. All outbound mail
will now flow through Amazon SES.
To integrate Microsoft Exchange with Amazon SES using Windows PowerShell

1.
Open the Exchange Management Shell and type $creds = Get-Credential. A Windows
PowerShell Credential Request dialog box will appear.
2.
In the dialog box, enter your Amazon SES SMTP user name and password and then choose OK.
Important
yourself against the SMTP endpoint. For more information about credentials, see Using

81

3.
At the command prompt, type the following line, replacing ENDPOINT with an Amazon SES
SMTP endpoint (for example, email-smtp.us-west-2.amazonaws.com). For a list of Amazon SES
endpoints, see Regions and Amazon SES (p. 332).
New-SendConnector -Name "SES" -AddressSpaces "*;1" -SmartHosts
"ENDPOINT" -SmartHostAuthMechanism BasicAuthRequireTLS -Usage Internet AuthenticationCredential $creds
The command line should now display a send connector for Amazon SES with an enabled status.
All outbound mail will now flow through Amazon SES.
Integrating Amazon SES with Microsoft Windows Server IIS SMTP

You can configure Microsoft Windows Server's IIS SMTP server to send email through Amazon SES.
These instructions were written using Microsoft Windows Server 2012 on an Amazon EC2 instance.
You can use the same configuration on Microsoft Windows Server 2008 and Microsoft Windows Server
2008 R2.
To integrate the Microsoft Windows Server IIS SMTP server with Amazon SES
1.
2.
First, set up Microsoft Windows Server 2012 using the following instructions.
a.
From the Amazon EC2 management console, launch a new Microsoft Windows Server 2012
Base Amazon EC2 instance.
b.
Connect to the instance and log into it using Remote Desktop by following the instructions in
Getting Started with Amazon EC2 Windows Instances.
c.
Launch the Server Manager Dashboard.
d.
Install the Web Server role. Be sure to include the IIS 6 Management Compatibility tools
(an option under the Web Server checkbox).
e.
Install the SMTP Server feature.
Next, configure the IIS SMTP service using the following instructions.
a.
Return to the Server Manager Dashboard.
b.
From the Tools menu, choose Internet Information Services (IIS) 6.0 Manager.
c.
Right-click SMTP Virtual Server #1 and then select Properties.
d.
On the Access tab, under Relay Restrictions, choose Relay.
e.
In the Relay Restrictions dialog box, choose Add.
f.
Under Single Computer, enter 127.0.0.1 for the IP address. You have now granted access
for this server to relay email to Amazon SES through the IIS SMTP service.
Note
In this procedure, we assume that your emails are generated on this server. If the
application that generates the email runs on a separate server, you need to grant
relaying access for that server in IIS SMTP.
3.
Finally, configure the server to send email through Amazon SES using the following instructions.
a.
b.
Return to the SMTP Virtual Server #1 Properties dialog box and then choose the Delivery
tab.
On the Delivery tab, choose Outbound
82 Security.

c.
Select Basic Authentication and then enter your Amazon SES SMTP username and
password. You can obtain these credentials from the Amazon SES console using the
procedure in Obtaining Your Amazon SES SMTP Credentials (p. 57).
Important
yourself against the SMTP endpoint. For more information about credentials, see
Using Credentials With Amazon SES (p. 323).
d.
Ensure that TLS encryption is selected.
e.
Return to the Delivery tab.
f.
Choose Outbound Connections.
g.
In the Outbound Connections dialog box, ensure that the port is 25 or 587.
h.
Choose Advanced.
i.
For the Smart host name, enter the Amazon SES endpoint that you will use (for example,
email-smtp.us-west-2.amazonaws.com). For a list of Amazon SES endpoints, see Regions
and Amazon SES (p. 332).
j.
Return to the Server Manager Dashboard.
k.
On the Server Manager Dashboard, right-click SMTP Virtual Server #1 and then restart the
service to pick up the new configuration.
l.
Send an email through this server. You can examine the message headers to confirm that it
was delivered through Amazon SES.
Integrating Amazon SES with Exim

Exim is an MTA that was originally developed for Unix-like systems. It is a general purpose mail
program that is very flexible and configurable.
To learn more about Exim, go to http://www.exim.org.
To configure integration with the Amazon SES US West (Oregon) endpoint using
STARTTLS
1.
Open the /etc/exim/exim.conf file for editing. If the file does not exist, create it.
Important
2.
In /etc/exim/exim.conf, make the following changes:

a.
In the routers section, after the begin routers line, add the following:
send_via_ses:
driver = manualroute
domains = ! +local_domains
transport = ses_smtp
route_list = * email-smtp.us-west-2.amazonaws.com;
b.
In the transports section, after the begin transports line, add the following:
ses_smtp:
driver = smtp
port = 25
83

hosts_require_auth = $host_address
hosts_require_tls = $host_address
c.
In the authenticators section, after the begin authenticators line, add the following, replacing
USERNAME and PASSWORD with your SMTP user name and password:
Important
information about how to obtain your SMTP credentials, see Obtaining Your Amazon
SES SMTP Credentials (p. 57).
ses_login:
driver = plaintext
public_name = LOGIN
client_send = : USERNAME : PASSWORD
3.
Save the /etc/exim/exim.conf file.
To configure integration using a secure tunnel

1.
To begin, you will need to set up a secure tunnel as described in Secure Tunnel (p. 62). In the
following procedure, we use port 2525 as your stunnel port. If you are using a different port, modify
the settings that you actually use accordingly.
2.
Open the /etc/exim/exim.conf file for editing. If the file does not exist, create it.
Important
3.
In /etc/exim/exim.conf, make the following changes:

a.
In the routers section, after the begin routers line, add the following:
send_via_ses:
driver = manualroute
domains = ! +local_domains
transport = ses_smtp
self = send
route_list = * localhost
b.
In the transports section, after the begin transports line, add the following:
ses_smtp:
driver = smtp
port = 2525
hosts_require_auth = localhost
hosts_avoid_tls = localhost
c.
In the authenticators section, after the begin authenticators line, add the following, replacing
USERNAME and PASSWORD with your SMTP user name and password:
ses_login:
driver = plaintext
public_name = LOGIN
client_send = : USERNAME : PASSWORD

84

4.
Save the /etc/exim/exim.conf file.
When you have finished updating the configuration, restart Exim. At the command line, type the
following command and press ENTER.
sudo /etc/init.d/exim restart
Note
This command may not be exactly the same on your particular server.
When you have completed this procedure, your outgoing email will be sent via Amazon SES. To test
your configuration, send an email message through your Exim server, and then verify that arrives at
its destination. If the message is not delivered, then check your system's mail log for errors. On many
systems, this is the /var/log/exim/main.log file.
Using the Command Line to Send Email Through the Amazon

SES SMTP Interface
You can use a command line utility to interact directly with the Amazon SES SMTP interface.
The command line interface can be helpful for testing purposes or for writing software that must
communicate directly using the SMTP protocol.
To protect our customers, all communication with the SMTP interface must take place using
TLS (Transport Layer Security). For SMTP command line usage, we recommend that you use
OpenSSL. OpenSSL, which is available at https://www.openssl.org, includes a command line utility for
communicating over a TLS-secured connection.

85

This example shows how to connect to the Amazon SES SMTP endpoint in the US West (Oregon)
openssl s_client -crlf -quiet -connect email-smtp.us-west-2.amazonaws.com:465
Using
Example
Using
OpenSSL
Send Email
Using
Amazon
SES Some of the output in the
region TLS
and :Wrapper:
use
standard
SMTP to
commands
to send
an email
message.
example is omitted for brevity.
s_clientSpecifies that this connection will use TLS (SSL).
-crlfTranslates line feed characters (LF) to CR+LF (carriage return and line feed).
-quietInhibits printing of session and certificate information. This implicitly turns on -ign_eof as
well.
-connectSpecifies the SMTP host and port.
openssl s_client -crlf -quiet -starttls smtp -connect email-smtp.usUsing STARTTLS:
west-2.amazonaws.com:25
s_clientSpecifies that this connection will use TLS (SSL).

-crlfTranslates line feed characters (LF) to CR+LF (carriage return and line feed).
-quietInhibits printing of session and certificate information. This implicitly turns on -ign_eof as
well.
-starttls smtpSpecifies STARTTLS negotiation.
-connectspecifies the SMTP host and port.
After you make the connection using one of the preceding commands, the Amazon SES SMTP
CONNECTED(00000003) ... <output omitted> Server certificate -----BEGIN
interface identifies itself by presenting its server certificate.
CERTIFICATE----MIID2jCCAue4gAwIBAgIAMEkqjWRxm3cqMA0tGC2GxSI37DQEBQ6UAMIGHjswCQD
VQQEwVUzErTMBEGaxA51UECBfMKV2Fza7GluZ3RvbjEMxA4GAUEByEXAMPLECERT
... <output omitted>
At this point, use the EHLO command to identify your client. Specify the hostname of the system from
--- 220
localhost ESMTP SES 2010-12-03
EHLO
bob-desktop.example.com
which you are logging in.
250-localhost
... <output omitted>
250-AUTH LOGIN
You can now use the AUTH LOGIN command to supply your SMTP credentials. You must base64250 Note
Ok
encode your SMTP username and password. The server prompts ("Username:" and "Password:") are
For
example,
if your
SMTP
username
isuse
c2VzLXNtdHAtdXNlcEXAMPLE
and"SMTPyour password
To
a string
in Linux,
you can
thecode
following
similarlybase64-encode
encoded,
and
appear
with
thecredential
SMTP
response
334. command (replace
is SkFYTVpaM3k0U2paVEYwOFpLEXAMPLE,
you would
supply your base64-encoded
credentials as
USERNAME" with your SMTP username): echo
-n "SMTP-USERNAME"
| base64
AUTH LOGIN
follows:
334 VXNlcm5hbWU6
YzJWekxYTnRkSEF0ZFhObGNFWEFNUExF
334 UGFzc3dvcmQ6
U2tGWVRWcGFNM2swVTJwYVZFWXdPRnBMRVhBTVBMRQ==
Specify the sender and recipient by using the MAIL FROM and RCPT TO commands. For MAIL FROM,
235 Authentication successful.
you must use an email address that you have already verified with Amazon SES. For more information
MAIL FROM:[email protected]
about verification, see Verifying Email Addresses and Domains in Amazon SES (p. 39).
250 Ok
RCPT TO:[email protected]
Issue the DATA command to specify the email headers and the body of the message. The headers
250 Ok
and the body must be separated by at least one blank line. In this example, only the Subject: header is
DATA
being used. A dot (".") on a line by itself signifies the end of the message body.
354 End data with <CR><LF>.<CR><LF>
Subject:Hello from Amazon SES!
This email was sent using the Amazon SES SMTP interface.
.
QUIT
Now that the message has been sent, use the QUIT command to close the SMTP connection.
250 Ok
221 Bye
closed

86

Using the API
Note
For more information about SMTP, go to https://tools.ietf.org/html/rfc5321.
Using the Amazon SES API to Send Email

To send production email through Amazon SES, you can use the Simple Mail Transfer Protocol
(SMTP) interface or the Amazon SES API. For more information about the SMTP interface, see Using
the Amazon SES SMTP Interface to Send Email (p. 56). This section describes how to send email
by using the API.
The Amazon SES API has a Query interface over HTTPS. See Regions and Amazon SES (p. 332)
for a list of Amazon SES API endpoints. When you send an email by using the API, you can provide
limited information and have Amazon SES assemble the email for you, or you can assemble the email
yourself so that you have complete control over the content and formatting. For more information about
the API, see the Amazon Simple Email Service API Reference. You can call the API in the following
four ways:
Make raw Query requests and responsesThis is the most advanced method, because you are
calling the API directly. For information about how to make Query requests and responses, see
Amazon SES Query API (p. 326).
Use an AWS SDKAWS SDKs wrap the low-level functionality of the Amazon SES API with higherlevel data types and function calls that take care of the details for you, and provide basic functions
(not included in the Amazon SES API), such as request authentication, request retries, and error
handling.
Use a command line interfaceThe AWS Command Line Interface is the command line tool for
Amazon SES. We also offer the AWS Tools for Windows PowerShell for those who script in the
PowerShell environment.
Regardless of whether you access the Amazon SES API directly or indirectly through an AWS SDK,
the AWS Command Line Interface or the AWS Tools for Windows PowerShell, the Amazon SES API
provides two different ways for you to send an email, depending on how much control you want over
the composition of the email message:
FormattedAmazon SES composes and sends a properly formatted email message. You need
only supply "From:" and "To:" addresses, a subject, and a message body. Amazon SES takes
care of all the rest. For more information, see Sending Formatted Email Using the Amazon SES
API (p. 88).
RawYou manually compose and send an email message, specifying your own email headers and
MIME types. If you are experienced in formatting your own email, the raw interface gives you more
control over the composition of your message. For more information, see Sending Raw Email Using
the Amazon SES API (p. 88).

87

Using the API
Sending Formatted Email Using the Amazon SES API

You can send a formatted email by using the AWS Management Console or by calling the Amazon
SES API through an application directly, or indirectly through an AWS SDK, the AWS Command Line
Interface, or the AWS Tools for Windows PowerShell.
The Amazon SES API provides the SendEmail action, which lets you compose and send a formatted
email. SendEmail requires a From: address, To: address, message subject, and message bodytext,
HTML, or both. For a complete description of SendEmail, go to the Amazon Simple Email Service API
Reference.
Note
The email address string must be 7-bit ASCII. If you want to send to or from email addresses
that contain unicode characters in the domain part of an address, you must encode the
domain using Punycode. For more information, see RFC 3492.
For an example of how to compose a formatted message using the AWS SDK for Java or the AWS
SDK for .NET, see Send an Email Through Amazon SES Using the AWS SDK for Java (p. 32) or Send
an Email Through Amazon SES Using the AWS SDK for .NET (p. 29), respectively.
For tips on how to increase your email sending speed when you make multiple calls to SendEmail,
see Increasing Throughput with Amazon SES (p. 237).
Sending Raw Email Using the Amazon SES API

Sometimes you might want more control over how Amazon SES composes and sends email than
automatic formatting provides. If so, you can use the Amazon SES raw email interface to specify email
headers and MIME types, to send highly customized messages to your recipients.
This section introduces you to some common email standards and how Amazon SES uses them. It
also shows how to construct and send raw email from the command line and from the Amazon SES
API.
About Email Header Fields

Simple Mail Transfer Protocol (SMTP) specifies how email messages are to be sent by defining
the mail envelope and some of its parameters, but it does not concern itself with the content of the
message. Instead, the Internet Message Format (RFC 5322) defines how the message is to be
constructed.
With the Internet Message Format specification, every email message consists of a header and a
body. The header consists of message metadata, and the body contains the message itself. For more
information about email headers and bodies, see Email Format and Amazon SES (p. 12).
Using MIME
The SMTP protocol is designed for sending email messages composed of 7-bit ASCII characters.
While this works well for many use cases, it is insufficient for non-ASCII text encodings (such as
Unicode), binary content, or attachments. The Multipurpose Internet Mail Extensions standard (MIME)
was developed to overcome these limitations, making it possible to send many other kinds of content
using SMTP.
The MIME standard works by breaking the message body into multiple parts and then specifying what
is to be done with each part. For example, one part of an email message body might be plain text,
while another might be an image. In addition, MIME allows email messages to contain one or more
attachments. Message recipients can view the attachments from within their email clients, or they can
save the attachments.
The message header and content are separated by a blank line. Each part of the email is separated by
a boundary, a string of characters that denotes the beginning and ending of each part.
88

Using the API
Here is an example of the raw text of a multipart MIME email message:
Received: from smtp-out.example.com (123.45.67.89) by

in.example.com (87.65.43.210); Wed, 2 Mar 2011 11:39:39 -0800
From: "Bob" <[email protected]>
To: "Andrew" <[email protected]>
Date: Wed, 2 Mar 2011 11:39:34 -0800
Subject: Customer service contact info
Message-ID: <[email protected]>
Accept-Language: en-US
Content-Language: en-US
Content-Type: multipart/mixed;
boundary="_003_97DCB304C5294779BEBCFC8357FCC4D2"
MIME-Version: 1.0
--_003_97DCB304C5294779BEBCFC8357FCC4D2
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Hi Andrew. Here are the customer service names and telephone
numbers I promised you.
See attached.
-Bob
--_003_97DCB304C5294779BEBCFC8357FCC4D2
Content-Type: text/plain; name="cust-serv.txt"
Content-Description: cust-serv.txt
Content-Disposition: attachment; filename="cust-serv.txt";
size=1180;
creation-date="Wed, 02 Mar 2011 11:39:39 GMT";
modification-date="Wed, 02 Mar 2011 11:39:39 GMT"
Content-Transfer-Encoding: base64
TWFyeSBEYXZpcyAtICgzMjEpIDU1NS03NDY1DQpDYXJsIFRob21hcyAtICgzMjEpIDU1NS01MjM1
DQpTYW0gRmFycmlzIC0gKDMyMSkgNTU1LTIxMzQ=
--_003_97DCB304C5294779BEBCFC8357FCC4D2
Note the following aspects of this example:

A blank line separates the header from the body.
The content type is "multipart/mixed," which indicates that the message has many parts and the
receiver must handle each part separately.
The "boundary" parameter specifies where each part begins and ends. In this case, the boundary is
a unique string of characters that the sender's email client generates.
There are two parts to the body, a plain text message and an attachment. The email client will
display the plain text part, and it will handle the attachment separately.
The "Content-Disposition" field specifies how the client should handle the attachment: When the
reader clicks the attachment, the email client will attempt to save it to a text file named "custserv.txt".

89

Using the API
MIME Encoding
Because of the 7-bit ASCII restriction of SMTP, any content containing 8-bit characters must first be
converted to 7-bit ASCII before sending. MIME defines a Content-Transfer-Encoding header field for
this purpose.
By convention, the most common encoding scheme is base64, where 8-bit binary content is encoded
using a well-defined set of 7-bit ASCII characters. Upon receipt, the email client inspects the ContentTransfer-Encoding header field, and can immediately perform a base64 decode operation on the
content, thus returning it to its original form. With most email clients, the encoding and decoding occur
automatically, and the user need not be aware of it.
In the example above, the "cust-serv.txt" attachment must be decoded from base64 format in order to
be read. Some email clients will encode all MIME parts in base64 format, even if they were originally
in plain text. This is not normally an issue, since email clients perform the encoding and decoding
automatically.
Note
For a list of MIME types that Amazon SES accepts, see Appendix: Unsupported Attachment
Types (p. 344).
If you want certain parts of a message, like some headers, to contain characters other than 7-bit ASCII,
then you must use MIME encoded-word syntax (RFC 2047) instead of a literal string. MIME encodedword syntax uses the following form: =?charset?encoding?encoded-text?=. For more information,
see RFC 2047. If you want to send to or from email addresses that contain unicode characters in the
domain part of an address, you must encode the domain using Punycode. For more information, see
RFC 3492.
API
The Amazon SES API provides the SendRawEmail action, which lets you compose and send an
email message in the format that you specify. For a complete description of SendRawEmail, go to the
Note
For tips on how to increase your email sending speed when you make multiple calls to
SendRawEmail, see Increasing Throughput with Amazon SES (p. 237).
The message body must contain a properly formatted, raw email message, with appropriate header
fields and message body encoding. Although it is possible to construct the raw message manually
within an application, it is much easier to do so using existing mail libraries.

90
attachment.setHeader("Content-ID", "<" + id + ">");

attachment.setFileName(fds.getName());
content.addBodyPart(attachment);
Using the API
html.setContent("<html><body><h1>HTML</h1>\n" + EMAIL_BODY_TEXT + "</

body></html>",
"text/html");
Example
try {
System.out.println("Attempting to send an email through Amazon
SES by using the AWS SDK for Java...");
/*
* The ProfileCredentialsProvider will return your [default]
* credential profile by reading from the credentials file
located at
* (~/.aws/credentials).
*
* TransferManager manages a pool of threads, so we create a
* single instance and share it throughout our application.
*/
AWSCredentials credentials = null;
try {
credentials = new
ProfileCredentialsProvider().getCredentials();
} catch (Exception e) {
throw new AmazonClientException(
"Cannot load the credentials from the credential
profiles file. " +
"Please make sure that your credentials file is at
the correct " +
"location (~/.aws/credentials), and is in valid
format.",
e);
}
// Instantiate an Amazon SES client, which will make the service
call with the supplied AWS credentials.
AmazonSimpleEmailServiceClient(credentials);
Region REGION = Region.getRegion(AWS_REGION);
client.setRegion(REGION);
// Print the raw email content on the console
PrintStream out = System.out;
message.writeTo(out);
// Send the email.
ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
message.writeTo(outputStream);
RawMessage rawMessage = new
RawMessage(ByteBuffer.wrap(outputStream.toByteArray()));
SendRawEmailRequest rawEmailRequest = new
SendRawEmailRequest(rawMessage);
client.sendRawEmail(rawEmailRequest);
} catch (Exception ex) {
System.out.println("Email Failed");
System.err.println("Error message: " + ex.getMessage());
ex.printStackTrace();
}
}
}

91

Authenticating Your Email
Authenticating Your Email in Amazon SES

Amazon Simple Email Service (Amazon SES) uses the Simple Mail Transfer Protocol (SMTP) to
send email. Because SMTP does not provide any authentication by itself, spammers can send email
messages that claim to originate from someone else, while hiding their true origin. By falsifying email
headers and spoofing source IP addresses, spammers can mislead recipients into believing that the
email messages that they are receiving are authentic.
Most ISPs that forward email traffic take measures to evaluate whether email is legitimate. One such
measure that ISPs take is to determine whether an email is authenticated. Authentication requires
senders to verify that they are the owner of the account that they are sending from. In some cases,
ISPs refuse to forward email that is not authenticated. To ensure optimal deliverability, we recommend
that you authenticate your emails.
The following sections describe two authentication mechanisms ISPs useSender Policy Framework
(SPF) and DomainKeys Identified Mail (DKIM)and provide instructions for how to use these
standards with Amazon SES.
To learn about SPF, which provides a way to trace an email message back to the system from which
it was sent, see Authenticating Email with SPF in Amazon SES (p. 92).
To learn about DKIM, a standard that allows you to sign your email messages to show ISPs that your
messages are legitimate and have not been modified in transit, see Authenticating Email with DKIM
in Amazon SES (p. 93).
To learn how to comply with Domain-based Message Authentication, Reporting and Conformance
(DMARC), which relies on SPF and DKIM, see Complying with DMARC Using Amazon
SES (p. 103).
Authenticating Email with SPF in Amazon SES

Sender Policy Framework (SPF) is an email validation standard, defined in RFC 7208, designed to
combat email spoofing. SPF enables domain owners to specify which mail servers are authorized to
send email for their domain. To indicate compliance with SPF, the domain owner publishes a list of
authorized mail servers in a DNS record on the domain's DNS server. When a receiving mail server
receives an email that contains the domain in the MAIL FROM address, it checks the domain's DNS
records to compare the sending mail server to the authorized mail servers and takes action on the
email accordingly.
An SPF record indicates to ISPs that you have authorized Amazon SES to send email for your domain.
When you use Amazon SES, your decision about whether to publish an SPF record depends on
whether you only require your email to pass an SPF check by the receiving mail server, or if you
want your email to comply with the additional requirements needed to pass Domain-based Message
Authentication, Reporting and Conformance (DMARC) authentication based on SPF. You can use
DKIM to achieve DMARC validation, but it is a best practice to use both DKIM and SPF for maximum
deliverability.
To pass an SPF checkWhen you use Amazon SES, there are two setups with which you can
pass an SPF check. The first setup is to use the default MAIL FROM domain of Amazon SES, and to
not publish an SPF record at all. This setup enables you to pass an SPF check because by default,
Amazon SES uses its own MAIL FROM domain to send your emails. In this case, an SPF check will
pass because the default MAIL FROM domain is amazonses.com (or a subdomain of that) and the
sending mail server is Amazon SES.
92

Authenticating Email with DKIM
The other setup with which you can pass an SPF check is to configure Amazon SES to use your
own MAIL FROM domain, in which case you must publish an SPF record because the MAIL FROM
domain and the domain of the sending mail server, Amazon SES, are different. Instructions for
configuring your domain to send emails using a custom MAIL FROM domain are provided in Using a
Custom MAIL FROM Domain (p. 46).
To pass DMARC validation based on SPFIf you want DMARC validation to succeed based on
SPF, you must set up a custom MAIL FROM domain (p. 46) and publish an SPF record. Note that
the alignment mode in the DMARC policy must be relaxed, which is the default. For more information
about DMARC policies, see https://dmarc.org/.
Adding an SPF Record

The procedure for adding a TXT record to your domain's DNS settings depends on who provides your
DNS service, but for general instructions, see Adding a TXT Record to Your Domain's DNS Server in
Amazon SES Domain Verification TXT Records (p. 45). For information specific to SPF records, go to
http://www.openspf.net and RFC 7208.
Adding a New SPF Record

If your custom MAIL FROM domain does not have an existing SPF record, publish a TXT record with
the following value. The name of the record can be blank or @, depending on your DNS service.
Important
If you use "-all" as shown in the example, ISPs might block email from IP addresses that are
not listed in your SPF record. Your SPF record must therefore include every IP address that
you use to send email. As a debugging aid, you can use "~all" instead. When you use "~all",
ISPs will typically accept email from IP addresses that are not listed in the SPF record, but
they might flag it. To maximize deliverability, use "-all" and add a record for each IP address.
For examples of how to authorize multiple IP addresses, go to http://www.openspf.org/
SPF_Record_Syntax.
"v=spf1 include:amazonses.com -all"
Adding to an Existing SPF Record

If your domain already has an SPF record, then you must add the following SPF mechanism to the
existing record.
include:amazonses.com
Authenticating Email with DKIM in Amazon SES

DomainKeys Identified Mail (DKIM) is a standard that allows senders to sign their email messages and
ISPs to use those signatures to verify that those messages are legitimate and have not been modified
by a third party in transit.
An email message that is sent using DKIM includes a DKIM-Signature header field that contains a
cryptographically signed representation of all, or part, of the message. An ISP receiving the message
can decode the cryptographic signature using a public key, published in the sender's DNS record, to
ensure that the message is authentic. For more information about DKIM, see http://www.dkim.org.
DKIM signatures are optional. You might decide to sign your email using a DKIM signature to enhance
deliverability with DKIM-compliant ISPs. Amazon SES provides two options to sign your messages
using a DKIM signature:

93

To set up your domain so that Amazon SES automatically adds a DKIM signature to every message
sent from that domain, see Easy DKIM in Amazon SES (p. 94).
To add your own DKIM signature to any email that you send using the SendRawEmail API, see
Manual DKIM Signing in Amazon SES (p. 102).
Easy DKIM in Amazon SES

Easy DKIM is a feature of Amazon SES that signs every message that you send from a verified email
address or domain with a DKIM signature that uses a 1024-bit DKIM key. You can use the Amazon
SES console to configure Easy DKIM settings, and to enable or disable automatic DKIM signing for
your email messages. You must be able to edit your domain's DNS records to set up Easy DKIM.
With the appropriate DNS records in place, you can enable Easy DKIM signing for any verified email
address or domain.
The following rules apply:
As with other verified identity settings, if you verify a domain, subdomain, and email address that
share a root domain, Easy DKIM settings apply at the most granular level you verified. That is:
Verified email address settings override verified domain settings.
Verified subdomain settings override verified domain settings, with lower-level subdomain settings
overriding higher-level subdomain settings.
If you verify a root domain, and do not verify a particular subdomain, then that subdomain uses the
root domain's Easy DKIM settings. That is, if the root domain has Easy DKIM set up and enabled,
the subdomain's emails are automatically DKIM-signed as well.
Once you set up Easy DKIM, your messages will automatically be DKIM-signed regardless of whether
you call Amazon SES through the SMTP interface or the API (SendEmail or SendRawEmail). Note
that you only need to set up Easy DKIM for the domain you use in your "From" address, not for the
domain in a "Return-Path" or "Reply-To" address.
If you are verifying a new domain, you can set up Easy DKIM at that time. If you already have a verified
domain or email address, you can add Easy DKIM capability to it whenever you want.
Note
Amazon SES has endpoints in multiple AWS regions, and Easy DKIM setup applies to each
AWS region separately. You must perform the Easy DKIM setup procedure for each region in
which you want to use Easy DKIM. For information about using Amazon SES in multiple AWS
regions, see Regions and Amazon SES (p. 332).
This topic contains the following sections:
To set up Easy DKIM while you verify a new domain, see Setting Up Easy DKIM for a New
Domain (p. 94).
To set up Easy DKIM for an email address or domain that you have already verified, see Setting Up
Easy DKIM for an Existing Verified Identity (p. 97).
Setting Up Easy DKIM for a New Domain

When you use the AWS Management Console to verify a new domain, you can also set up Easy DKIM
at the same time.
These instructions are for new domains only. If you want to set up Easy DKIM for an email address
or domain that you have already verified, see Setting Up Easy DKIM for an Existing Verified
Identity (p. 97).
94

To set up Easy DKIM for a new domain

1.
to it:
a.
b.
In the navigation pane, under Identities, click Domains.
2.
Click Verify a New Domain.
3.
In the Verify a New Domain dialog box, enter your domain name, select the Generate DKIM
settings check box, and then click Verify This Domain.
In the resulting dialog box, you will see all of the DNS records that you need for setting up domain
verification and Easy DKIM. This information will also be available by clicking the domain name
after you close the dialog box.
4.
To complete domain verification, you must update your domain's DNS settings with the TXT record
information from the Domain Verification Record in the Verify a New Domain dialog box. Note
that some domain name providers use the term Host instead of Name. If your DNS provider does
95

not allow underscores in record names, you can omit _amazonses from the Name of the domain
verification record. To help you easily identify this record within your domain's DNS settings, you
can optionally prefix the Value with amazonses:
Highlight and copy individual records, or select Download Record Set as CSV to download all of
the records.
Important
DNS providers may append the domain name to the end of DNS records. Adding a record
that already contains the domain name (such as _amazonses.example.com) may result
in the duplication of the domain name (such as _amazonses.example.com.example.com).
To avoid duplication of the domain name, add a period to the end of the domain name
in the DNS record. This will indicate to your DNS provider that the record name is fully
qualified (that is, no longer relative to the domain name), and prevent the DNS provider
from appending an additional domain name.
5.
To set up DKIM, you must update your domain's DNS settings with the CNAME record information
from the dialog box. Note that you cannot omit the underscore from _domainkey because the
underscore is required by RFC 4871.
Highlight and copy individual CNAME records, or select Download Record Set as CSV to
download all of the records.
a.
If Amazon Route 53 provides the DNS service for the domain you are verifying, and you are
logged in to Amazon SES console with the same email address and password you use for
Amazon Route 53, then you will have the option of immediately updating your DNS settings
for both domain verification and DKIM from within the Amazon SES console.
b.
If you are not using Amazon Route 53, you will need to update your DNS settings according
to the procedure established by your DNS service provider. (Ask your system administrator
if you are not sure who provides your DNS service.) Amazon Web Services will eventually
detect that you have updated your DNS records; this detection process may take up to 72
hours.
When verification is complete, the domain's Status in the Amazon SES console will change
from pending verification to verified, and you will receive an Amazon SES Domain Verification
SUCCESS confirmation email from Amazon Web Services. (AWS emails are sent to the email
address you used when you signed up for Amazon SES.)
When Amazon SES has successfully detected the changes to your DNS records, the DKIM
Verification Status for that domain in the Amazon SES console will change from in progress to
success, and you will receive an Amazon SES DKIM Setup Successful confirmation email from
Amazon Web Services.
6.
You can now use Amazon SES to send email that is signed using a DKIM signature from any valid
address in the verified domain. To send a test email using the Amazon SES console, check the
box next to the verified domain, and then click Send a Test Email. View the email headers in the
email you receive. Email providers typically provide this capability through an option such as Show
original or View message source. Look for a header named DKIM-Signature with the "d" tag set
to your domain. Note that when DKIM is enabled, there will be two DKIM-Signature headers added
to the message: one header for your domain, and one header with d=amazonses.com. (Amazon
SES adds a signature for amazonses.com automatically whether you have DKIM enabled or not.
You can ignore it.) For example, for a domain called ses-example.com, the DKIM signature header
you are looking for might look like:
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/simple;

s=xtk53kxcy4p3t6ztbrffs6d54rsrrhh6; d=ses-example.com;
t=1366720445;
96

h=From:To:Subject:MIME-Version:Content-Type:Content-TransferEncoding:Date:Message-ID;
bh=lcj/Sl5qKl6K6zwFUwb7Flgnngl892pW574kmS1hrS0=;
b=nhVMQLmSh7/DM5PW7xPV4K/PN4iVY0a5OF4YYk2L7jgUq9hHQlckopxe82TaAr64
eVTcBhHHj9Bwtzkmuk88g4G5UUN8J+AAsd/JUNGoZOBS1OofSkuAQ6cGfRGanF68Ag7
nmmEjEi+JL5JQh//u+EKTH4TVb4zdEWlBuMlrdTg=
Important
How you update the DNS settings depends on who provides your DNS service. DNS service
may be provided by a domain name registrar such as GoDaddy or Network Solutions, or by a
separate service such as Amazon Route 53.
What if Easy DKIM fails?
If your DNS settings are not correctly updated, you will first receive an Amazon SES DKIM FAILURE
email from Amazon Web Services, and you will see a status of failed in the Domains area when you
click on the DKIM tab.
Note
If this happens, Amazon SES will still send your email, but it will not be signed using a DKIM
signature.
Setting Up Easy DKIM for an Existing Verified Identity

If you have already verified a domain or email address, you can use the AWS Management Console to
set up Easy DKIM for that identity at any time.
These instructions are for adding DKIM signing to a domain that has already been verified. If you are
verifying a new domain and want to set up Easy DKIM at the same time, see Setting Up Easy DKIM for
a New Domain (p. 94).
Important
Easy DKIM only works with fully qualified domain names (FQDNs). If you wanted to set up
Easy DKIM for both example.com and newyork.example.com, you would need to set up Easy
DKIM for each of these FQDNs separately.
To set up Easy DKIM for an existing verified domain

1.
to it:
a.
b.
In the navigation pane, under Identities, click Domains.
2.
In the content pane, click the verified domain for which you would like to set up Easy DKIM.
3.
On the domain's Details page, expand DKIM.

97

4.
Click Generate DKIM Settings.

Your DKIM records will be displayed.

98

5.
To set up DKIM, you must update your domain's DNS settings with the displayed CNAME record
information. You can copy the records or click the Download Record Set as CSV link.
a.
If Amazon Route 53 provides the DNS service for the domain you are verifying, and you are
logged in to Amazon SES console with the same email address and password you use for
Amazon Route 53, then Amazon SES will give you the option of immediately updating your
DNS settings for Easy DKIM. If you would like to do this, click the Use Route 53 button.
Next, click Create Record Sets in the Use Route 53 dialog box to complete the process.
b.
If you are not using Amazon Route 53, you will need to update your DNS settings according
to the procedure established by your DNS service provider. (Ask your system administrator
if you are not sure who provides your DNS service.) Amazon Web Services will eventually
detect that you have updated your DNS records; this detection process may take up to 72
hours.
6.
When Amazon SES has successfully detected the changes to your DNS records, the DKIM
Verification Status for that domain in the Amazon SES console will change from in progress to
success, and you will receive an Amazon SES DKIM Setup Successful confirmation email from
Amazon Web Services. (Amazon Web Services emails are sent to the email address you used
when you signed up for Amazon SES.)
7.
(This step is only required if DKIM setup was initiated before 09-13-16, 2:00 PDT) To sign your
messages using a DKIM signature, you must enable Easy DKIM for the appropriate verified
sending identity as follows:
8.
a.
In the navigation pane, under Identities, click either Email Addresses or Domains,
depending whether you want to enable Easy DKIM signing for an email address or a domain.
b.
Click the email address or domain for which you wish to enable Easy DKIM signing.
c.
On the Details page of the email address or domain, expand DKIM.
d.
In the DKIM: field, click enable.
You can now use Amazon SES to send email that is signed using a DKIM signature from any valid
address in the verified domain. To send a test email using the Amazon SES console, check the
box next to the verified domain, and then click Send a Test Email. View the email headers in the
email you receive. Email providers typically provide this capability through an option such as Show
original or View message source. Look for a header named DKIM-Signature with the "d" tag set
to your domain. Note that when DKIM is enabled, there will be two DKIM-Signature headers added
to the message: one header for your domain, and one header with d=amazonses.com. (Amazon
SES adds a signature for amazonses.com automatically whether you have DKIM enabled or not.
You can ignore it.) For example, for a domain called ses-example.com, the DKIM signature header
you are looking for might look like:
99

DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/simple;

s=xtk53kxcy4p3t6ztbrffs6d54rsrrhh6; d=ses-example.com;
t=1366720445;
h=From:To:Subject:MIME-Version:Content-Type:Content-TransferEncoding:Date:Message-ID;
bh=lcj/Sl5qKl6K6zwFUwb7Flgnngl892pW574kmS1hrS0=;
b=nhVMQLmSh7/DM5PW7xPV4K/PN4iVY0a5OF4YYk2L7jgUq9hHQlckopxe82TaAr64
eVTcBhHHj9Bwtzkmuk88g4G5UUN8J+AAsd/JUNGoZOBS1OofSkuAQ6cGfRGanF68Ag7
nmmEjEi+JL5JQh//u+EKTH4TVb4zdEWlBuMlrdTg=
Important
How you update the DNS settings depends on who provides your DNS service. DNS service
may be provided by a domain name registrar such as GoDaddy or Network Solutions, or by a
separate service such as Amazon Route 53.
What if Easy DKIM fails?
If your DNS settings are not correctly updated, you will first receive an Amazon SES DKIM FAILURE
email from Amazon Web Services, and you will see a status of failed in the Domains area when you
click on the DKIM tab.
Note
If this happens, Amazon SES will still send your email, but it will not be signed using a DKIM
signature.
Disabling Easy DKIM in Amazon SES

If you want to temporarily stop Amazon SES from signing your messages using DKIM, you can disable
Easy DKIM for your email address or domain. You can reenable it at any time.
To disable Easy DKIM signing

1.
2.
In the navigation pane, under Identities, click either Email Addresses or Domains, depending
whether you want to disable Easy DKIM signing for an email address or a domain.
3.
Click the email address or domain for which you wish to disable Easy DKIM signing.
4.
On the Details page of the email address or domain, expand DKIM.
5.
In the DKIM: field, click disable. Amazon SES will no longer DKIM-sign emails that you send from
this identity.
Note
If you do not see the disable option as in the figure below, then DKIM is already disabled.

100

Note
If you want to permanently disable DKIM signing from any email address on that domain, you
should also remove the CNAME records from your DNS.
DKIM Record Revocation in Amazon SES

Amazon Web Services periodically reviews DKIM DNS records, and revokes DKIM signing in cases
where it is no longer valid. If Amazon Web Services is unable to detect the CNAME record information
required to confirm the ownership of a domain, you will receive an Amazon SES DKIM REVOCATION
WARNING email from Amazon Web Services. Amazon SES will continue to send your email, but it will
not be signed using a DKIM signature.
If you restore the CNAME record information to your DNS settings within five days, you will receive an
Amazon SES DKIM REVOCATION CANCELLATION email from Amazon Web Services. Amazon SES
will once again sign email using a DKIM signature from a verified identity for which you have enabled
Easy DKIM.
If you do not restore the CNAME record information to your DNS settings within five days, you will
receive an Amazon SES DKIM REVOCATION email from Amazon Web Services, and email you send
via Amazon SES will not be signed using a DKIM signature.
To set up Easy DKIM for a domain for which DKIM signing has been revoked, you must restart the
procedure from the beginning, as if you were setting up Easy DKIM for the first time.
Other Ways to Manage Easy DKIM in Amazon SES

You can also manage Easy DKIM with the Amazon SES API. The following actions are available:
VerifyDomainDkim
SetIdentityDkimEnabled
GetIdentityDkimAttributes
You can use these API actions to write a customized front-end application for working with Easy DKIM.
For a complete description of API actions related to Easy DKIM, go to the Amazon Simple Email

101

Creating DNS Records for DKIM Signing in Amazon SES

Unlike the Amazon SES console, the Amazon SES API does not generate fully-formed DNS records
for use with DKIM. Instead, they return DKIM tokens character strings that represent your domain's
identity.
If you are not using the Amazon SES console, you will need to create your own CNAME records using
the DKIM tokens returned by the API.
To create DNS records for DKIM signing

1.
Obtain the DKIM tokens for your domain. To do so, if you are using the Amazon SES API, call
VerifyDomainDkim to generate the tokens. If you already have a DKIM verified identity, call
GetIdentityDkimAttributes to obtain the tokens.
2.
In the output from the API, you will receive three DKIM tokens similar to the following:
vvjuipp74whm76gqoni7qmwwn4w4qusjiainivf6sf
3frqe7jn4obpuxjpwpolz6ipb3k5nvt2nhjpik2oy
wrqplteh7oodxnad7hsl4mixg2uavzneazxv5sxi2
3.
Use these tokens to construct three CNAME records. For a domain named example.com, the
records should appear similar to these:
vvjuipp74whm76gqoni7qmwwn4w4qusjiainivf6sf._domainkey.example.com CNAME
vvjuipp74whm76gqoni7qmwwn4w4qusjiainivf6sf.dkim.amazonses.com
3frqe7jn4obpuxjpwpolz6ipb3k5nvt2nhjpik2oy._domainkey.example.com CNAME
3frqe7jn4obpuxjpwpolz6ipb3k5nvt2nhjpik2oy.dkim.amazonses.com
wrqplteh7oodxnad7hsl4mixg2uavzneazxv5sxi2._domainkey.example.com CNAME
wrqplteh7oodxnad7hsl4mixg2uavzneazxv5sxi2.dkim.amazonses.com
You can now update your DNS with these records. Amazon Web Services will eventually detect that
you have updated your DNS records; this detection process may take up to 72 hours. Upon successful
detection, you will receive an Amazon SES DKIM Setup Successful confirmation email from Amazon
Web Services. (Amazon Web Services emails are sent to the email address you used when you signed
up for Amazon SES.)
Manual DKIM Signing in Amazon SES

If you prefer not to use Easy DKIM, you can still sign your email messages using a DKIM signature
and send them using Amazon SES. To do this, you must use the SendRawEmail API and self-sign
your message content according to the specifications provided at http://www.dkim.org. If you use this
approach, be aware that Amazon SES does not validate the DKIM signature that you construct. If there
are any errors in the signature, you will need to correct them yourself. If you DKIM-sign your own email
messages, we recommend that you use keys that are at least 1024 bits.
Whether or not you DKIM-sign your messages, Amazon SES automatically adds a DKIM header with
d=amazonses.com, which you can ignore. If you do DKIM-sign your messages, it is expected that
there will be two DKIM headers: one for your domain, and one for amazonses.com.
Important
To ensure maximum deliverability, do not sign any of the following headers using a DKIM
signature:
Message-ID
Date
Return-Path
Bounces-To
102

Complying with DMARC
Note
If you are using the Amazon SES SMTP interface to send email, and your client software
automatically performs DKIM signing, you should check to ensure that your client does not
sign any of the headers listed above. We recommend that you check the documentation for
your software to find out exactly what headers are signed with DKIM.
For more information about the Amazon SES SMTP interface, see Using the Amazon SES
SMTP Interface to Send Email (p. 56).
Complying with DMARC Using Amazon SES

Domain-based Message Authentication, Reporting and Conformance (DMARC) is an email
authentication protocol that uses Sender Policy Framework (SPF) and DomainKeys Identified Mail
(DKIM) to detect email spoofing. An email can comply with DMARC through SPF or through DKIM. For
maximum deliverability, it is a best practice to set up your email-sending to comply with both methods.
This topic describes what to do to enable emails that you send with Amazon SES to comply with
DMARC. For information about the DMARC specification, see http://www.dmarc.org.
DMARC Compliance through SPF

For an email to comply with DMARC based on SPF, the DMARC specification requires that both of the
following conditions are met:
The email must pass an SPF check. For information about SPF checks, see http://www.openspf.org.
The domain in the "From" address of the email header must align with the MAIL FROM domain that
the sending mail server specifies to the receiving mail server to indicate the source of the message.
If the DMARC policy specifies strict alignment, the "From" and MAIL FROM domains must match
exactly. With relaxed alignment, the MAIL FROM domain can be a subdomain of the "From" domain.
To comply with both DMARC SPF requirements with Amazon SES, you must publish an SPF
record (p. 92) and use relaxed alignment in your DMARC policy (relaxed alignment is the default).
DMARC Compliance through DKIM

For an email to comply with DMARC based on DKIM, the DMARC specification requires that both of
the following conditions are met:
The message must have a valid DKIM signature.
The d= domain in the DKIM signature must align with the domain in the "From" address of the email
header. If the DMARC policy specifies strict alignment, these domains must match exactly. With
relaxed alignment, the d= domain can be a subdomain of the "From" domain.
To comply with both DMARC DKIM requirements with Amazon SES, you simply need to set up Easy
DKIM (p. 94) so that Amazon SES signs your emails automatically. You can also manually DKIMsign your messages (p. 102). Regardless of how you DKIM-sign your messages, you will comply
with DMARC if you use relaxed alignment (which is the default) in your DMARC policy. If you want to
require that the "From" domain exactly matches the d= domain, then you must specifically apply strict
alignment in your DMARC policy.
Monitoring Your Amazon SES Sending Activity

Amazon SES provides means by which to monitor your sending activity, and we strongly encourage
you to monitor your sending activity regularly. For example, you should watch your number of bounces,
complaints, and rejected emails so that you can identify and correct problems right away. Excessive
103

Monitoring Your Sending Activity
bounces and complaints constitute abuse and put your Amazon SES sending abilities at risk of
suspension.
Note
To find how close you are to your sending limits, see Monitoring Your Sending
Limits (p. 193).
You monitor your Amazon SES sending in terms of email sending events. The email sending events
that you can monitor are:
Bounces 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.
Complaints The recipient marked the email as spam.
Sends Your API call to Amazon SES was successful and Amazon SES will attempt to deliver the
email.
Rejects Amazon SES initially accepted the email, but later rejected it because the email contained
a virus.
Deliveries Amazon SES successfully delivered the email to the recipient's mail server.
You can monitor email sending events in three ways: using the console, using feedback notifications,
and using event publishing. The monitoring method you choose depends on the type of event you
want to monitor, the granularity and level of detail with which you want to monitor it, and where
you want Amazon SES to publish the data. You might choose to use multiple monitoring methods.
Characteristics of each method are listed in the following table.
Monitoring
Method
Events You Can

Monitor
How to Access
the Data
Level of Detail
Granularity
Amazon SES
or CloudWatch
console or API
Bounces,
complaints,
deliveries, sends,
rejects
Amazon SES
or CloudWatch
console or API
(deliveries are
available through
CloudWatch only)
Count only
Coarse (across
entire AWS
account)
Feedback
notifications
Bounces,
complaints,
deliveries
Amazon SNS or
email (delivery
events are by
Amazon SNS
only)
Details on each
event
Coarse (across
entire AWS
account)
Event publishing
Bounces,
complaints,
deliveries, sends,
rejects
Amazon
CloudWatch or
Amazon Kinesis
Firehose
Details on each
event
Fine-grained
(based on userdefinable email
characteristics)
For information on how to use each monitoring method, see the following topics:
Monitoring Using the Amazon SES Console or API (p. 105)
Monitoring Using Notifications (p. 106)
Monitoring Using Event Publishing (p. 127)
104

Monitoring Using the Console or API
Monitoring Using the Amazon SES Console or API

You can monitor your bounce, complaint, sent, and rejected email statistics by using the Amazon SES
console or the Amazon SES API. You can use the API by calling the Query (HTTPS) interface directly
or indirectly through an AWS SDK, the AWS Command Line Interface, or the AWS Tools for Windows
PowerShell.
Monitoring Your Usage Statistics Using the Amazon SES

Console
The following procedure shows you how to view your usage statistics using the Amazon SES console.
1.
2.
In the Navigation pane, click Sending Statistics. Your usage statistics are shown under Your
Amazon SES Metrics.
Note
The Deliveries graph corresponds to the number of emails you have sent.
3.
To view trend data for any metric, double-click the corresponding graph.
4.
To update the display, click the Refresh button.

105

Monitoring Using Notifications
Monitoring Your Usage Statistics Using the Amazon SES API

The Amazon SES API provides the GetSendStatistics action, which returns information about your
service usage. We recommend that you use GetSendStatistics on a regular basis, so that you can
monitor your sending activity and make adjustments as needed.
When you call GetSendStatistics, you will receive a list of data points representing the last
two weeks of your sending activity. Each data point in this list represents 15 minutes of activity and
contains the following information for that period:
Bounces (hard bounces only)
Complaints
Delivery attempts (corresponds to the number of emails you have sent)
Rejected send attempts
Timestamp
Note
For a complete description of GetSendStatistics, go to the Amazon Simple Email Service
API Reference.
Monitoring Using Amazon SES Notifications

Amazon SES can notify you of the status of your emails by email or through Amazon Simple
Notification Service (Amazon SNS). Amazon SES supports the following three types of notifications:
Bounces The email is rejected by the recipient's ISP or rejected by Amazon SES because the
email address is on the Amazon SES suppression list. For ISP bounces, Amazon SES reports only
hard bounces and soft bounces that will no longer be retried by Amazon SES. In these cases, your
recipient did not receive your email message, and Amazon SES will not try to resend it. Bounce
notifications are available through email and Amazon SNS. You are notified of out-of-the-office
(OOTO) messages through the same method as bounces, although they don't count toward your
bounce statistics. To see an example of an OOTO bounce notification, you can use the Amazon SES
mailbox simulator. For more information, see Testing Amazon SES Email Sending (p. 224).
Complaints The email is accepted by the ISP and delivered to the recipient, but the recipient does
not want the email and clicks a button such as "Mark as spam." If Amazon SES has a feedback loop
set up with the ISP, Amazon SES will send you a complaint notification. Complaint notifications are
available through email and Amazon SNS.
Deliveries Amazon SES successfully delivers the email to the recipient's mail server. This
notification does not indicate that the actual recipient received the email because Amazon SES
cannot control what happens to an email after the receiving mail server accepts it. Delivery
notifications are available only through Amazon SNS.
You can set up notifications using the Amazon SES console or the Amazon SES API.
There are several important points to know about notifications:
Notification settings are configured on a per-verified-identity basis There is no global setting,
and notification settings apply only to the verified identity in the AWS region in which you configured
the settings.
Verified domain notification settings apply to all mail sent from email addresses in
that domain except for email addresses that are also verified The configurations for
email addresses are separate from the configuration for the domain, so changing the domain
configuration will have no effect on the email address configuration. For example, if you verify
only example.com and configure its bounce notification settings, bounce notifications for email
106

from [email protected] will use those settings. However, if you verify both example.com and
[email protected], [email protected] will not use the bounce notification settings that are
configured for example.com.
You must receive bounce and complaint notifications either by email or through Amazon
SNS The default method is by email, through a feature called email feedback forwarding. Delivery
notifications are optional and available only through Amazon SNS.
If you choose to receive notifications for all three types of events, then you might receive
multiple notifications for one email For example, the receiving mail server accepts the email
(triggering a delivery notification), but the recipient marks the email as spam, triggering a complaint
notification.
Before you start sending email, make sure that you set up a process to handle bounces
and complaints Your process needs to monitor bounces and complaints and to remove those
addresses from your mailing list. Excessive bounces and complaints put your Amazon SES account
at risk of termination. You will need to analyze each bounce and complaint message that you
receive to determine the cause. Bounces are usually caused by attempting to send to a nonexistent
recipient; complaints arise when recipients indicate that they do not want to receive your message. In
either case, we strongly recommend that you stop sending to these email addresses.
You can test notifications by using the Amazon SES mailbox simulator Emails that you send
to the mailbox simulator do not affect your bounce and complaint rates. For more information, see
Testing Amazon SES Email Sending (p. 224).
The following sections describe the notification methods:
To receive notifications by email (which applies to bounces and complaints only), see Amazon SES
Notifications Through Email (p. 107).
To receive notifications through Amazon SNS (which applies to all three notification types), see
Amazon SES Notifications Through Amazon SNS (p. 109).
Amazon SES Notifications Through Email

Amazon SES can notify you of your bounces and complaints through email using a process called
email feedback forwarding or through Amazon Simple Notification Service (Amazon SNS). This topic
is about receiving notifications by email, which is the default setting. For information about setting up
notifications through Amazon SNS, see Amazon SES Notifications Through Amazon SNS (p. 109).
Unlike bounce and complaint notifications, delivery notifications are available only through Amazon
SNS.
Important
For several important points about notifications, see Monitoring Using Amazon SES
The following sections describe how to receive bounce and complaint notifications through email:
To enable bounce and complaint notifications by email, see Enabling Email Feedback
Forwarding (p. 107).
To disable bounce and complaint notifications by email, see Disabling Email Feedback
Forwarding (p. 108).
To learn the email address to which bounce and complaint notifications are sent, see Email
Feedback Forwarding Destination (p. 109).
Enabling Email Feedback Forwarding

Email feedback forwarding is enabled by default. If you previously disabled it, you can enable it by
using the following procedure.
107

To enable bounce and complaint forwarding through email using the Amazon SES
console
1.
2.
In the navigation pane, under Identity Management, choose Email Addresses or Domains,
depending on whether you want to configure bounce and complaint notifications for an email
address or domain.
3.
In the list of verified senders, choose the email address or domain for which you want to configure
bounce and complaint notifications.
4.
In the details pane of the verified sender, expand Notifications.
5.
Choose Edit Configuration.
6.
Under Email Feedback Forwarding, choose Enabled.
Note
Changes made to your settings on this page might take a few minutes to take effect.
You can also enable bounce and complaint notifications through email by using the
SetIdentityFeedbackForwardingEnabled API.
Disabling Email Feedback Forwarding

You must receive bounce and complaint notifications through either Amazon SNS or email feedback
forwarding, so you can disable email feedback forwarding only if you select an Amazon SNS topic
for both bounce and complaint notifications. If you selected an Amazon SNS topic for bounces and
complaints, you can disable email feedback forwarding by using the following procedure.
To disable bounce and complaint forwarding through email using the Amazon SES
console
1.
2.
In the navigation pane, under Identity Management, choose Email Addresses or Domains,
depending on whether you want to configure bounce and complaint notifications for an email
address or domain.
3.
bounce and complaint notifications.
4.
5.
6.
In the Edit Notification Configuration dialog box, ensure that you have selected an Amazon SNS
topic for both bounces and complaints. Otherwise, you will not be able to disable email feedback
forwarding in the next step.
7.
Under Email Feedback Forwarding, choose Disabled.
8.
Choose Save Config to save your notification configuration.
Note
Changes made to your settings on this page might take a few minutes to take effect.
You can also disable bounce and complaint notifications through email by using the
SetIdentityFeedbackForwardingEnabled API.

108

Email Feedback Forwarding Destination

When you receive notifications by email, Amazon SES rewrites the From: header and sends the
notification to you. The address to which Amazon SES forwards the notification depends on how you
sent the original message.
If you used the SMTP interface to send the message, then notifications go to the address specified in
the MAIL FROM command, which overrides any Return-Path: header specified in the SMTP DATA.
If you used the SendEmail API to send the message, then the notifications are delivered as follows:
If you specified the optional ReturnPath parameter of SendEmail, then notifications go to that
address.
Otherwise, notifications go to the address specified in the required Source parameter of
SendEmail, which populates the From: header of the message.
If you used the SendRawEmail API to send the message, then the notifications are delivered as
follows:
If you specified the optional Source parameter of SendRawEmail, then notifications go to that
address, overriding any Return-Path: header specified in the raw message.
Otherwise, if the Return-Path: header was specified in the raw message, then notifications go to that
address.
Otherwise, notifications go to the address in the From: header of the raw message.
Important
Regardless of whether you use the SMTP interface, SendEmail API, or SendRawEmail API,
Amazon SES overwrites any Return-Path: header that you provide.
Amazon SES Notifications Through Amazon SNS

You can use Amazon Simple Notification Service (Amazon SNS) to receive notifications about
bounces, complaints, and deliveries for emails that you send through Amazon SES. Amazon SNS
notifications are in JavaScript Object Notation (JSON) format, which enables you to process them
programmatically.
If you configure Amazon SNS notifications for both bounces and complaints, you can disable receiving
bounce and complaint notifications by email entirely. For information about receiving bounce and
complaint notifications by email, see Amazon SES Notifications Through Email (p. 107). Delivery
notifications are available only through Amazon SNS.
Important
For information about Amazon SES bounce, complaint, and delivery notifications through Amazon
SNS, see the following sections:
To set up notifications using the Amazon SES console or the Amazon SES API, see Configuring
Amazon SNS Notifications for Amazon SES (p. 110).
For a description of the contents of a notification, see Amazon SNS Notification Contents for Amazon
SES (p. 111).
For examples of bounce, complaint, and delivery notifications, see Amazon SNS Notification
Examples for Amazon SES (p. 120).
109

Configuring Amazon SNS Notifications for Amazon SES

Amazon SES can notify you of your bounces, complaints, and deliveries through Amazon Simple
Notification Service (Amazon SNS).
Important
You can configure notifications by using the Amazon SES console or by using the Amazon SES API,
as described in the following sections.
To configure notifications by using the Amazon SES console, see Configuring Notifications Using the
Amazon SES Console (p. 110).
To configure notifications by using the Amazon SES API, see Configuring Notifications Using the
Amazon SES API (p. 111).
Configuring Notifications Using the Amazon SES Console

To configure notifications using the Amazon SES console
1.
console.aws.amazon.com/ses/
2.
In the navigation pane, under Identity Management, choose Domains or Email Addresses.
3.
notifications.
Important
Verified domain notification settings apply to all mail sent from email addresses in that
domain except for email addresses that are also verified.
4.
5.
6.
Under SNS Topic Configuration, you can edit the Amazon SNS topic configuration as follows:
a.
Choose the Amazon SNS topics you want to use for bounces, complaints, and/or deliveries.
You can choose to publish notifications to the same Amazon SNS topic or to different Amazon
SNS topics.
Important
The Amazon SNS topics you use for bounce, complaint, and delivery notifications
must be within the same AWS region in which you are using Amazon SES.
If you want to use an Amazon SNS topic that you do not own, you must configure your AWS
Identity and Access Management (IAM) policy to allow publishing from the Amazon Resource
Name (ARN) of the Amazon SNS topic.
b.
If you want the Amazon SNS notifications to contain the original headers of the emails you
pass to Amazon SES, choose Include original headers. This option is only available if you
have assigned an Amazon SNS topic to the associated notification type. For information about
the contents of the original email headers, see the mail object in Amazon SNS Notification
Contents (p. 111).
7.
If you choose Amazon SNS topics for both bounces and complaints, you can disable email
notifications entirely. To disable email notifications for bounces and complaints, under Email
Feedback Forwarding, choose Disable. Delivery notifications are available only through Amazon
SNS.
8.
Choose Save Config. The changes you made to your notification settings might take a few
minutes to take effect.
110

After you configure your settings, you will start receiving bounce, complaint, and/or delivery
notifications to your Amazon SNS topic(s). These notifications will be in JavaScript Object Notation
(JSON) format and will follow the structure described in Amazon SNS Notification Contents (p. 111).
You will be charged standard Amazon SNS rates for bounce, complaint, and delivery notifications. For
more information, see the Amazon SNS pricing page.
Note
If an attempt to publish to your Amazon SNS topic fails because the topic has been deleted or
your AWS account no longer has permissions to publish to it, the Amazon SES configuration
for that topic for the sending identity will be deleted, bounce and complaint notifications
through email will be re-enabled for that identity, and you will be notified of the change through
email. If you have multiple identities configured to use that topic, each identity will have its
topic configuration changed when each identity experiences a failure to publish to that topic.
Configuring Notifications Using the Amazon SES API

You can also configure bounce, complaint, and delivery notifications with the Amazon SES API. The
following actions are available:
SetIdentityNotificationTopic
SetIdentityFeedbackForwardingEnabled
GetIdentityNotificationAttributes
SetIdentityHeadersInNotificationsEnabled
You can use these API actions to write a customized front-end application for notifications. For a
complete description of the API actions related to notifications, see the Amazon Simple Email Service
API Reference.
Amazon SNS Notification Contents for Amazon SES

Bounce, complaint, and delivery notifications are published to Amazon Simple Notification Service
(Amazon SNS) topics in JavaScript Object Notation (JSON) format. The top-level JSON object
contains a notificationType string, a mail object, and either a bounce object, a complaint
object, or a delivery object.
See the following sections for descriptions of the different types of objects:
Top-level JSON object (p. 112)
mail object (p. 112)
bounce object (p. 115)
complaint object (p. 117)
delivery object (p. 119)
The following are some important notes about the contents of Amazon SNS notifications for Amazon
SES:
For a given notification type, you might receive one Amazon SNS notification for multiple recipients,
or you might receive a single Amazon SNS notification per recipient. Your code should be able to
parse the Amazon SNS notification and handle both cases; Amazon SES does not make ordering
or batching guarantees for notifications sent through Amazon SNS. However, different Amazon
SNS notification types (for example, bounces and complaints) will never be combined into a single
notification.
You might receive multiple types of Amazon SNS notifications for one recipient. For example, the
receiving mail server might accept the email (triggering a delivery notification), but after processing
111

the email, the receiving mail server might determine that the email actually results in a bounce
(triggering a bounce notification). However, these will always be separate notifications because they
are different notification types.
Amazon SES reserves the right to add additional fields to the notifications. As such, applications that
parse these notifications must be flexible enough to handle unknown fields.
Amazon SES overwrites the headers of the message when it sends the email. You can retrieve the
headers of the original message from the headers and commonHeaders fields of the mail object.
Top-Level JSON Object

The top-level JSON object in an Amazon SES notification contains the following fields.
Field Name
Description
notificationType
A string that holds the type of notification

represented by the JSON object. Possible values
are Bounce, Complaint, or Delivery.
mail
A JSON object that contains information about

the original mail to which the notification pertains.
For more information, see Mail Object (p. 112).
bounce
This field is present only if the

notificationType is Bounce and contains
a JSON object that holds information about
the bounce. For more information, see Bounce
Object (p. 115).
complaint

notificationType is Complaint and contains
a JSON object that holds information about the
complaint. For more information, see Complaint
Object (p. 117).
delivery

notificationType is Delivery and contains
a JSON object that holds information about the
delivery. For more information, see Delivery
Object (p. 119).
Mail Object
Each bounce, complaint, or delivery notification contains information about the original email in the
mail object. The JSON object that contains information about a mail object has the following fields.
Field Name
Description
timestamp
The time at which the original message was sent

(in ISO8601 format).
messageId
A unique ID that Amazon SES assigned to the

message. Amazon SES returned this value to
you when you sent the message.
Note
This message ID was assigned
by Amazon SES. You can find the
message ID of the original email in the
112

Field Name
Description
headers and commonHeaders fields of
the mail object.
source
The email address from which the original

message was sent (the envelope MAIL FROM
address).
sourceArn
The Amazon Resource Name (ARN) of the

identity that was used to send the email. In the
case of sending authorization, the sourceArn
is the ARN of the identity that the identity
owner authorized the delegate sender to use
to send the email. For more information about
sending authorization, see Using Sending
Authorization (p. 196).
sendingAccountId
The AWS account ID of the account that was

used to send the email. In the case of sending
authorization, the sendingAccountId is the
delegate sender's account ID.
destination
A list of email addresses that were recipients of

the original mail.
headersTruncated
(Only present if the notification settings (p. 110)

include the original email headers.) A string that
specifies whether the headers are truncated in
the notification, which occurs if the headers are
larger than 10 KB. Possible values are true and
false.
headers
(Only present if the notification settings include

the original email headers.) A list of the email's
original headers. Each header in the list has a
name field and a value field.
Note
Any message ID within the headers
field is from the original message
that you passed to Amazon SES.
The message ID that Amazon SES
subsequently assigned to the message
is in the messageId field of the mail
object.
commonHeaders
(Only present if the notification settings include

the original email headers.) A list of the email's
original, commonly used headers. Each header
in the list has a name field and a value field.
Note
Any message ID within the
commonHeaders field is from the
original message that you passed to
Amazon SES. The message ID that
Amazon SES subsequently assigned to
the message is in the messageId field
of the mail object.

113

The following is an example of a mail object that includes the original email headers. When this
notification type is not configured to include the original email headers, the mail object does not
include the headersTruncated, headers, and commonHeaders fields.
{
"timestamp":"2016-01-27T14:05:45 +0000",
"messageId":"000001378603177f-7a5433e7-8edb-42ae-af10f0181f34d6ee-000000",
"source":"[email protected]",
"sourceArn": "arn:aws:ses:us-west-2:888888888888:identity/example.com",
"sendingAccountId":"123456789012",
"destination":[
"[email protected]"
],
"headersTruncated":false,
"headers":[
{
"name":"From",
"value":"\"John Doe\" <[email protected]>"
},
{
"name":"To",
"value":"\"Jane Doe\" <[email protected]>"
},
{
"name":"Message-ID",
"value":"custom-message-ID"
},
{
"name":"Subject",
"value":"Hello"
},
{
"name":"Content-Type",
"value":"text/plain; charset=\"UTF-8\""
},
{
"name":"Content-Transfer-Encoding",
"value":"base64"
},
{
"name":"Date",
"value":"Wed, 27 Jan 2016 14:05:45 +0000"
}
],
"commonHeaders":{
"from":[
"John Doe <[email protected]>"
],
"date":"Wed, 27 Jan 2016 14:05:45 +0000",
"to":[
"Jane Doe <[email protected]>"
],
"messageId":" custom-message-ID",
"subject":"Hello"
}
}

114

Bounce Object
The JSON object that contains information about bounces will always have the following fields.
Field Name
Description
bounceType
The type of bounce, as determined by Amazon

SES. For more information, see Bounce
Types (p. 116).
bounceSubType
The subtype of the bounce, as determined by

Amazon SES. For more information, see Bounce
Types (p. 116).
bouncedRecipients
A list that contains information about the

recipients of the original mail that bounced.
For more information, see Bounced
Recipients (p. 116).
timestamp
The date and time at which the bounce was sent

(in ISO8601 format). Note that this is the time at
which the notification was sent by the ISP, and
not the time at which it was received by Amazon
SES.
feedbackId
A unique ID for the bounce.
If Amazon SES was able to contact the remote Message Transfer Authority (MTA), the following field
will also be present.
Field Name
Description
remoteMtaIp
The IP address of the MTA to which Amazon

SES attempted to deliver the email.
If a delivery status notification (DSN) was attached to the bounce, the following field may also be
present.
Field Name
Description
reportingMTA
The value of the Reporting-MTA field from

the DSN. This is the value of the MTA that
attempted to perform the delivery, relay, or
gateway operation described in the DSN.
The following is an example of a bounce object.

{
"bounceType":"Permanent",
"bounceSubType": "General",
"bouncedRecipients":[
{
"status":"5.0.0",
"action":"failed",
"diagnosticCode":"smtp; 550 user unknown",
"emailAddress":"[email protected]"
},
115

{
"status":"4.0.0",
"action":"delayed",
}
],
"reportingMTA": "example.com",
"timestamp":"2012-05-25T14:59:38.605Z",
"feedbackId":"000001378603176d-5a4b5ad9-6f30-4198-a8c3b1eb0c270a1d-000000",
"remoteMtaIp":"127.0.2.0"
}
Bounced Recipients
A bounce notification may pertain to a single recipient or to multiple recipients. The
bouncedRecipients field holds a list of objectsone per recipient to whom the bounce notification
pertainsand will always contain the following field.
Field Name
Description
emailAddress
The email address of the recipient. If a DSN

is available, this is the value of the FinalRecipient field from the DSN.
Optionally, if a DSN is attached to the bounce, the following fields may also be present.
Field Name
Description
action
The value of the Action field from the DSN. This

indicates the action performed by the ReportingMTA as a result of its attempt to deliver the
message to this recipient.
status
The value of the Status field from the DSN.

This is the per-recipient transport-independent
status code that indicates the delivery status of
the message.
diagnosticCode
The status code issued by the reporting MTA.

This is the value of the Diagnostic-Code field
from the DSN. This field may be absent in the
DSN (and therefore also absent in the JSON).
The following is an example of an object that might be in the bouncedRecipients list.

{
"emailAddress": "[email protected]",
"action": "failed",
"status": "5.0.0",
"diagnosticCode": "X-Postfix; unknown user"
}
Bounce Types
The following bounce types are available. We recommend that you remove the email addresses that
have returned bounces marked Permanent from your mailing list, as we do not believe that you will
116

be able to successfully send to them in the future. Transient bounces are sent to you when all retry
attempts have been exhausted and will no longer be retried. You may be able to successfully resend to
an address that initially resulted in a Transient bounce.
Note
Amazon SES only reports hard bounces and soft bounces that will no longer be retried by
Amazon SES. In other words, your recipient did not receive your email message, and Amazon
SES will not try to resend it.
bounceType
bounceSubType
Description
Undetermined Undetermined
Amazon SES was unable to determine a specific

bounce reason.
Permanent
General
Amazon SES received a general hard bounce and

recommends that you remove the recipient's email
address from your mailing list.
Permanent
NoEmail
Amazon SES received a permanent hard bounce

because the target email address does not exist.
It is recommended that you remove that recipient
from your mailing list.
Permanent
Suppressed
Amazon SES has suppressed sending to this

address because it has a recent history of
bouncing as an invalid address. For information
about how to remove an address from the
suppression list, see Removing an Email
Address from the Amazon SES Suppression
List (p. 236).
Transient
General
Amazon SES received a general bounce. You

may be able to successfully retry sending to that
recipient in the future.
Transient
MailboxFull
Amazon SES received a mailbox full bounce. You

Transient
MessageTooLarge
Amazon SES received a message too large

bounce. You may be able to successfully retry
sending to that recipient if you reduce the
message size.
Transient
ContentRejected
Amazon SES received a content rejected bounce.

You may be able to successfully retry sending to
that recipient if you change the message content.
Transient
AttachmentRejected
Amazon SES received an attachment rejected

sending to that recipient if you remove or change
the attachment.
Complaint Object
The JSON object that contains information about complaints has the following fields.

117

Field Name
Description
complainedRecipients
A list that contains information about recipients

that may have been responsible for the
complaint. For more information, see Complained
timestamp

which the notification was sent by the ISP, and
not the time at which it was received by Amazon
SES.
feedbackId
A unique ID for the complaint.
Further, if a feedback report is attached to the complaint, the following fields may be present.
Field Name
Description
userAgent
The value of the User-Agent field from the

feedback report. This indicates the name and
version of the system that generated the report.
complaintFeedbackType
The value of the Feedback-Type field from

the feedback report received from the ISP. This
contains the type of feedback.
arrivalDate
The value of the Arrival-Date or ReceivedDate field from the feedback report (in ISO8601
format). This field may be absent in the report
(and therefore also absent in the JSON).
The following is an example of a complaint object.

{
"userAgent":"AnyCompany Feedback Loop (V0.01)",
"complainedRecipients":[
{
}
],
"complaintFeedbackType":"abuse",
"arrivalDate":"2009-12-03T04:24:21.000-05:00",
"timestamp":"2012-05-25T14:59:38.623Z",
"feedbackId":"000001378603177f-18c07c78-fa81-4a58-9dd1fedc3cb8f49a-000000"
}
Complained Recipients
The complainedRecipients field contains a list of recipients that may have submitted the complaint.
Important
Since most ISPs redact the email address of the recipient who submitted the complaint from
their complaint notification, this list contains information about recipients who might have
sent the complaint, based on the recipients of the original message and the ISP from which
118

we received the complaint. Amazon SES performs a lookup against the original message to
determine this recipient list.
JSON objects in this list contain the following field.
Field Name
Description
emailAddress
The email address of the recipient.
The following is an example of a Complained Recipient object.

{ "emailAddress": "[email protected]" }
Note
Because of this behavior, you can be more certain that you know which email address
complained about your message if you limit your sending to one message per recipient (rather
than sending one message with 30 different email addresses in the bcc line).
Complaint Types
You may see the following complaint types in the complaintFeedbackType field as assigned by the
reporting ISP, according to the Internet Assigned Numbers Authority website:
abuseIndicates unsolicited email or some other kind of email abuse.
auth-failureEmail authentication failure report.
fraudIndicates some kind of fraud or phishing activity.
not-spamIndicates that the entity providing the report does not consider the message to be spam.
This may be used to correct a message that was incorrectly tagged or categorized as spam.
otherIndicates any other feedback that does not fit into other registered types.
virusReports that a virus is found in the originating message.
Delivery Object
The JSON object that contains information about deliveries will always have the following fields.
Field Name
Description
timestamp
The time Amazon SES delivered the email to the

recipient's mail server (in ISO8601 format).
processingTimeMillis
The time in milliseconds between when Amazon

SES accepted the request from the sender to
passing the message to the recipient's mail
server.
recipients
A list of the intended recipients of the email to

which the delivery notification applies.
smtpResponse
The SMTP response message of the remote ISP

that accepted the email from Amazon SES. This
message will vary by email, by receiving mail
server, and by receiving ISP.
reportingMTA
The host name of the Amazon SES mail server

that sent the mail.
119

Field Name
Description
remoteMtaIp
The IP address of the MTA to which Amazon

SES delivered the email.
The following is an example of a delivery object.

{
"timestamp":"2014-05-28T22:41:01.184Z",
"processingTimeMillis":546,
"recipients":["[email protected]"],
"smtpResponse":"250 ok: Message 64111812 accepted",
"reportingMTA":"a8-70.smtp-out.amazonses.com",
}
Amazon SNS Notification Examples for Amazon SES

The following sections provide examples of the three types of notifications:
For bounce notification examples, see Amazon SNS Bounce Notification Examples (p. 120).
For complaint notification examples, see Amazon SNS Complaint Notification Examples (p. 123).
For delivery notification examples, see Amazon SNS Delivery Notification Example (p. 126).
Amazon SNS Bounce Notification Examples

This section contains examples of bounce notifications with and without a Delivery Status Notification
(DSN) provided by the email receiver that sent the feedback.
Bounce Notification With a DSN

The following is an example of a bounce notification that contains a DSN and the original email
headers. When bounce notifications are not configured to include the original email headers, the
mail object within the notifications does not include the headersTruncated, headers, and
commonHeaders fields.
{
"notificationType":"Bounce",
"bounce":{
"reportingMTA":"dns; email.example.com",
{
"emailAddress":"[email protected]",
"status":"5.1.1",
"action":"failed",
"diagnosticCode":"smtp; 550 5.1.1 <[email protected]>... User"
}
],
"bounceSubType":"General",
"timestamp":"2016-01-27T14:59:38.237Z",
"feedbackId":"00000138111222aa-33322211-cccc-cccc-ccccddddaaaa068a-000000",
},
"mail":{
120

"timestamp":"2016-01-27T14:59:38.237Z",
"sourceArn": "arn:aws:ses:us-west-2:888888888888:identity/
example.com",
"messageId":"00000138111222aa-33322211-cccc-cccc-ccccddddaaaa0680-000000",
"destination":[
"[email protected]",
"[email protected]"],
"headers":[
{
"name":"From",
},
{
"name":"To",
"value":"\"Jane Doe\" <[email protected]>, \"Mary Doe\"
<[email protected]>, \"Richard Doe\" <[email protected]>"
},
{
},
{
"name":"Subject",
"value":"Hello"
},
{
},
{
"value":"base64"
},
{
"name":"Date",
"value":"Wed, 27 Jan 2016 14:05:45 +0000"
}
],
"commonHeaders":{
"from":[
],
"date":"Wed, 27 Jan 2016 14:05:45 +0000",
"to":[
"Jane Doe <[email protected]>, Mary Doe <[email protected]>,
Richard Doe <[email protected]>"
],
"messageId":"custom-message-ID",
"subject":"Hello"
}
}
}

121

Bounce Notification Without a DSN

The following is an example of a bounce notification that includes the original email headers but does
not include a DSN. When bounce notifications are not configured to include the original email headers,
the mail object within the notifications does not include the headersTruncated, headers, and
{
"notificationType":"Bounce",
"bounce":{
{
},
{
}
],
"timestamp":"2016-01-27T14:59:38.237Z",
"feedbackId":"00000137860315fd-869464a4-8680-4114-98d3-716fe35851f9-000000",
},
"mail":{
"timestamp":"2016-01-27T14:59:38.237Z",
"messageId":"00000137860315fd-34208509-5b74-41f3-95c5-22c1edc3c924-000000",
example.com",
"destination":[
"[email protected]"
],
"headers":[
{
"name":"From",
},
{
"name":"To",
},
{
},
{
"name":"Subject",
"value":"Hello"
},
{
122

},
{
"value":"base64"
},
{
"name":"Date",
"value":"Wed, 27 Jan 2016 14:05:45 +0000"
}
],
"commonHeaders":{
"from":[
],
"date":"Wed, 27 Jan 2016 14:05:45 +0000",
"to":[
],
"subject":"Hello"
}
}
}
Amazon SNS Complaint Notification Examples

This section contains examples of complaint notifications with and without a feedback report provided
by the email receiver that sent the feedback.
Complaint Notification With a Feedback Report

The following is an example of a complaint notification that contains a feedback report and the original
email headers. When complaint notifications are not configured to include the original email headers,
the mail object within the notifications does not include the headersTruncated, headers, and
{
"notificationType":"Complaint",
"complaint":{
"userAgent":"AnyCompany Feedback Loop (V0.01)",
{
}
],
"complaintFeedbackType":"abuse",
"arrivalDate":"2016-01-27T14:59:38.237Z",
"timestamp":"2016-01-27T14:59:38.237Z",
"feedbackId":"000001378603177f-18c07c78-fa81-4a58-9dd1fedc3cb8f49a-000000"
},
"mail":{
"timestamp":"2016-01-27T14:59:38.237Z",
"messageId":"000001378603177f-7a5433e7-8edb-42ae-af10f0181f34d6ee-000000",
123

example.com",
"destination":[
"[email protected]"
],
"headers":[
{
"name":"From",
},
{
"name":"To",
},
{
},
{
"name":"Subject",
"value":"Hello"
},
{
},
{
"value":"base64"
},
{
"name":"Date",
"value":"Wed, 27 Jan 2016 14:05:45 +0000"
}
],
"commonHeaders":{
"from":[
],
"date":"Wed, 27 Jan 2016 14:05:45 +0000",
"to":[
],
"subject":"Hello"
}
}
}

124

Complaint Notification Without a Feedback Report

The following is an example of a complaint notification that includes the original email headers but does
not include a feedback report. When complaint notifications are not configured to include the original
email headers, the mail object within the notifications does not include the headersTruncated,
headers, and commonHeaders fields.
{
"notificationType":"Complaint",
"complaint":{
{
}
],
"timestamp":"2016-01-27T14:59:38.237Z",
"feedbackId":"0000013786031775-fea503bc-7497-49e1-881ba0379bb037d3-000000"
},
"mail":{
"timestamp":"2016-01-27T14:59:38.237Z",
"messageId":"0000013786031775-163e3910-53eb-4c8e-a04af29debf88a84-000000",
example.com",
"destination":[
"[email protected]"
],
"headers":[
{
"name":"From",
},
{
"name":"To",
},
{
},
{
"name":"Subject",
"value":"Hello"
},
{
},
{
"value":"base64"
},
125

{
"name":"Date",
"value":"Wed, 27 Jan 2016 14:05:45 +0000"
}
],
"commonHeaders":{
"from":[
],
"date":"Wed, 27 Jan 2016 14:05:45 +0000",
"to":[
],
"subject":"Hello"
}
}
}
Amazon SNS Delivery Notification Example

The following is an example of a delivery notification that includes the original email headers. When
delivery notifications are not configured to include the original email headers, the mail object within the
notifications does not include the headersTruncated, headers, and commonHeaders fields.
{
"notificationType":"Delivery",
"mail":{
"timestamp":"2016-01-27T14:59:38.237Z",
"messageId":"0000014644fe5ef6-9a483358-9170-4cb4-a269f5dcdf415321-000000",
example.com",
"destination":[
"[email protected]"
],
"headers":[
{
"name":"From",
},
{
"name":"To",
"value":"\"Jane Doe\" <[email protected]>"
},
{
},
{
"name":"Subject",
"value":"Hello"
},
126

Monitoring Using Event Publishing
{
},
{
"value":"base64"
},
{
"name":"Date",
"value":"Wed, 27 Jan 2016 14:58:45 +0000"
}
],
"commonHeaders":{
"from":[
],
"date":"Wed, 27 Jan 2016 14:58:45 +0000",
"to":[
"Jane Doe <[email protected]>"
],
"subject":"Hello"
}
},
"delivery":{
"timestamp":"2016-01-27T14:59:38.237Z",
"recipients":["[email protected]"],
"processingTimeMillis":546,
"reportingMTA":"a8-70.smtp-out.amazonses.com",
"smtpResponse":"250 ok: Message 64111812 accepted",
}
}
Monitoring Using Amazon SES Event Publishing

To enable you to track your email sending at a granular level, you can set up Amazon SES to publish
email sending events to Amazon CloudWatch or Amazon Kinesis Firehose based on fine-grained email
characteristics that you define. For example, you can categorize your emails by purpose (transactional
versus marketing), product details, the recipient's "From" domain, and so on.
You can track five types of email sending events: bounces, complaints, deliveries, sent emails, and
rejected emails. This information can be useful for operational and analytical purposes. For example,
you can publish your email sending events to CloudWatch and trigger an alarm when the complaint
rate of a specific email campaign reaches a certain level. You might publish events to Firehose so that
you can transfer the records to Amazon Redshift or another AWS service and merge the information
with your business data.
How Event Publishing Works

To use event publishing, you first set up one or more configuration sets. A configuration set specifies
where to publish your events and which events to publish. Then, each time you send an email, you
provide the name of the configuration set and one or more message tags, in the form of name/value
pairs, to categorize the email. For example, if you advertise books, you could name a message tag
genre, and assign a value of sci-fi or western, when you send an email for the associated campaign.
127

Depending on which email sending interface you use, you either provide the message tag as a
parameter to the API call or as an Amazon SES-specific email header.
In addition to defining your own message tags, you can use message tags that Amazon SES
automatically provides. These are called auto-tags and they include the configuration set name, the
domain of the "From" address, the caller's outgoing IP address, the Amazon SES outgoing IP address,
and the IAM identity of the caller.
How to Use Event Publishing

The following sections contain the information you need to set up and use Amazon SES event
publishing.
Setting Up Event Publishing (p. 129)
Managing Event Publishing (p. 136)
Retrieving Event Data (p. 139)
Tutorials (p. 155)
Event Publishing Terminology

The following list defines terms related to Amazon SES event publishing.
Email sending event
Information associated with the outcome of an email you submit to Amazon SES. There are five
types of email sending events:
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
Complaint The recipient marked the email as spam.
Delivery Amazon SES successfully delivered the email to the recipient's mail server.
Configuration set
An Amazon SES construct that encapsulates where you want to publish email sending events, and
what email sending events you want to publish. When you send an email that you want to use with
event publishing, you specify the configuration set to associate with the email.
Event destination
An Amazon SES construct that represents an AWS service to which you publish Amazon SES
email sending events. Each event destination that you set up belongs to one, and only one,
configuration set.
Message tag
A name/value pair that you use to categorize an email for the purpose of event publishing.
Examples are campaign/book and campaign/clothing. When you send an email, you either specify
the message tag as a parameter to the API call or as an Amazon SES-specific email header.
Auto-tag
Message tags that Amazon SES automatically provides so that you do not need to explicitly
specify them when you send an email. There is an auto-tag for the configuration set name, the
domain of the "From" address, the caller's outgoing IP address, the Amazon SES outgoing IP
address, and the IAM identity of the caller.
128

Setting Up Amazon SES Event Publishing

This section describes what you need to do to configure Amazon SES to publish your email sending
events to Amazon CloudWatch or Amazon Kinesis Firehose.
You first create a configuration set using the Amazon SES console or API. After you create
a configuration set, you add one or more event destinations (CloudWatch or Firehose) to the
configuration set, and configure parameters unique to the event destination. Then, each time you send
an email, you include the configuration set name and email characteristics, called message tags, as
parameters to the API, or Amazon SES-specific headers in the email.
These steps are explained in the following topics.
1. Step 1: Create a Configuration Set (p. 129)
2. Step 2: Add an Event Destination (p. 129)
3. Step 3: Send Email (p. 134)
Step 1: Create a Configuration Set Using Amazon SES

Configuration sets enable you to publish email sending events (bounces, complaints, deliveries, sent
emails, and rejected emails) to Amazon CloudWatch or Amazon Kinesis Firehose.
You can use the Amazon SES console or the CreateConfigurationSet API to create a
configuration set.
To create a configuration set (console)

1.
2.
In the left navigation pane, choose Configuration Sets.
3.
4.
5.
In the content pane, choose Create Configuration Set.

Type a name for the configuration set, and then choose Create Configuration Set.
Choose Close.
For information about how to use the CreateConfigurationSet API to create a configuration set,
see the Amazon Simple Email Service API Reference.
Step 2: Add an Event Destination Using Amazon SES

Event destinations represent AWS services to which you publish email sending events such as
bounces, complaints, deliveries, sent emails, and rejected emails. Each event destination that you
set up belongs to one, and only one, configuration set. When you set up an event destination with
Amazon SES, you choose the AWS service destination, and you specify parameters associated with
that destination.
There are two event destinations: Amazon CloudWatch and Amazon Kinesis Firehose. The event
destination that you choose depends on the level of detail you want about the events. If you simply
want a running total of each type of event (for example, so that you can set an alarm when the total
gets too high), use CloudWatch. If you want detailed event records that you can output to another
service such as Amazon Elasticsearch Service or Amazon Redshift for analysis, choose Firehose.
The following topics explain how to set up each type of event destination.
129

Set Up a CloudWatch Destination (p. 130)

Set Up a Firehose Destination (p. 132)
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 (p. 129) 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 has a set of automatically defined auto-tags to help you define
dimensions for your emails. To set up a CloudWatch dimension for an auto-tag, you must explicitly
type the auto-tag name as the dimension name when you add the CloudWatch event destination to
your configuration set. For more information, see Using Auto-Tags (p. 136).
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.
130

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.
2.
3.
Choose a configuration set from the configuration set list. If the list is empty, you must first create a
configuration set (p. 129).
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:
the email.
contained a virus.
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.
Note
If you want to use an Amazon SES auto-tag, you must explicitly type the name of the
auto-tag as the Dimension Name. For more information, see Using Auto-Tags (p. 136).
10. For Default Value, type a default value for the dimension.
11. Choose Add Dimension to add dimensions, as needed.

131

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.
Set Up a Firehose Event Destination for Amazon SES Event Publishing

An Amazon Kinesis Firehose event destination represents an entity that publishes specific Amazon
SES email sending events to Firehose. Because a Firehose event destination exists within a
configuration set only, you must first create a configuration set (p. 129) and then add the event
destination to the configuration set.
You can use the Amazon SES console or the UpdateConfigurationSetEventDestination API to
add a Firehose event destination.
To add a Firehose event destination to a configuration set (console)

1.
2.
3.
Choose a configuration set from the configuration set list. If the list is empty, you must first create a
configuration set (p. 129).
4.
For Add Destination, choose Select a destination type, and then choose Firehose.
5.
6.
For Event types, select at least one event type to publish to the event destination:
the email.
contained a virus.

132


7.
Select Enabled.
8.
For Stream, choose an existing Firehose delivery stream, or choose Create new stream to create
a new one using the Firehose console.
For information about creating a stream using the Firehose console, see Creating an Amazon
Kinesis Firehose Delivery Stream in the Amazon Kinesis Firehose Developer Guide.
9.
For IAM role, choose an IAM role for which Amazon SES has permission to publish to Firehose on
your behalf. You can choose an existing role, have Amazon SES create a role for you, or create
your own role.
If you choose an existing role or create your own role, you must manually modify the role's policies
to give the role permission to access the Firehose delivery stream, and to give Amazon SES
permission to assume the role. For example policies, see Giving Amazon SES Permission to
Publish to Your Firehose Delivery Stream (p. 133).
10. Choose Save.

For information about how to use the UpdateConfigurationSetEventDestination API to add a
Firehose event destination, see the Amazon Simple Email Service API Reference.
Giving Amazon SES Permission to Publish to Your Firehose Delivery Stream

To enable Amazon SES to publish records to your Firehose delivery stream, you must use an AWS
Identity and Access Management (IAM) role and attach or modify the role's permissions policy and
trust policy. The permissions policy enables the role to publish records to your Firehose delivery
stream, and the trust policy enables Amazon SES to assume the role.
This section provides examples of both policies. For information about attaching policies to IAM roles,
see Modifying a Role in the IAM User Guide.
Permissions Policy
The following permissions policy enables the role to publish data records to your Firehose delivery
stream.
133

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Action": [
"firehose:PutRecordBatch"
],
"Resource": [
"arn:aws:firehose:region:ACCOUNT-ID:deliverystream/DELIVERYSTREAM-NAME "
]
},
]
}
Trust Policy
The following trust policy enables Amazon SES to assume the role.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "ses.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "ACCOUNT-ID"
}
}
}
]
}
Step 3: Send Email Using Amazon SES Event Publishing

After you create a configuration set (p. 129) and add an event destination (p. 129), the last step to
event publishing is to send your emails.
To publish events associated with an email, you must provide two things to Amazon SES when you
send the email: the configuration set to associate with the email, and message tags to categorize the
email.
You provide this information to Amazon SES as either parameters to the email sending API, Amazon
SES-specific email headers, or custom headers in your MIME message. The method you choose
depends on which email sending interface you use, as shown in the following table.
Email Sending Interface
Ways to Publish Events
SendEmail
API parameters
134

Email Sending Interface
Ways to Publish Events
SendRawEmail
API parameters, Amazon SES-specific email

headers, or custom MIME headers
Important
If you specify message tags using
both headers and API parameters,
Amazon SES uses only the message
tags provided by the API parameters.
Amazon SES does not join message
tags specified by API parameters and
headers.
SMTP interface
Amazon SES-specific email headers
Amazon SES also provides a number of auto-tags that you can use without specifying message tags
when you sent the email. For more information, see Using Auto-Tags (p. 136).
The following sections describe how to specify the configuration set and message tags using headers
and using API parameters.
Using Amazon SES API Parameters (p. 135)
Using Amazon SES-Specific Email Headers (p. 135)
Using Custom Email Headers (p. 136)
Using Amazon SES API Parameters

To use SendEmail or SendRawEmail with event publishing, you specify the configuration set and the
message tags by passing data structures called ConfigurationSet and MessageTag to the API call.
For more information about using the Amazon SES API, see the Amazon Simple Email Service API
Reference.
Using Amazon SES-Specific Email Headers

When you use SendRawEmail or the SMTP interface, you can specify the configuration set and
the message tags by adding Amazon SES-specific headers to the email. Amazon SES removes the
headers before sending the email. The following table shows the names of the headers to use.
Event Publishing Information
Header
Configuration set
X-SES-CONFIGURATION-SET
Message tags
X-SES-MESSAGE-TAGS
The following example shows how the headers might look in a raw email that you submit to Amazon
SES.
X-SES-MESSAGE-TAGS: tagName1=tagValue1, tagName2=tagValue2
X-SES-CONFIGURATION-SET: myConfigurationSet
To: [email protected]
Subject: Subject
Content-Type: multipart/alternative;
135

boundary="----=_boundary"
------=_boundary
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
body
------=_boundary
Content-Type: text/html; charset=UTF-8
body
------=_boundary--
Using Custom Email Headers

Although you must specify the configuration set name using the Amazon SES-specific header X-SESCONFIGURATION-SET, you can specify the message tags by using your own MIME headers.
Note
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 Amazon SES event publishing, the
email sending call will still succeed, but the event metrics will not be emitted to Amazon
CloudWatch.
Using Amazon SES Auto-Tags

Amazon SES automatically provides a number of message tags, called auto-tags, to help you
categorize your emails. To use auto-tags, you do not need to specify message tags when you send the
email, but you must still specify a configuration set.
Important
If you publish your events to Amazon CloudWatch and you want to use auto-tags, you must
explicitly define a dimension value for the auto-tags when you set up the CloudWatch event
destination (p. 130).
The following table shows the auto-tags that Amazon SES provides.
Auto-tag name
Description
ses:configuration-set
The name of the configuration set associated

with the email
ses:caller-identity
The caller's AWS Identity and Access

Management (IAM) identity
ses:from-domain
The domain of the "From" address
ses:source-ip
The IP address that the caller used to send the

email
ses:outgoing-ip
The IP address that Amazon SES used to send

the email
Managing Amazon SES Event Publishing

After you create configuration sets and event destinations, you can perform various operations on
them.
136

This section contains the following topics:

Managing Configuration Sets (p. 137)
Managing Event Destinations (p. 138)
Managing Amazon SES Configuration Sets

In addition to creating configuration sets as described in Setting Up Event Publishing (p. 129),
you can view a list of your configuration sets, view the details of a configuration set, and delete a
configuration set, as described in the following sections.
Viewing a List of Your Configuration Sets

You can use the Amazon SES console or you can use the ListConfigurationSets API to view a
list of your configuration sets.
To view your configuration sets (console)

1.
2.

In the details pane, you will see a list of your configuration sets.
For information about how to use the ListConfigurationSets API to list your configuration sets,
Viewing the Details of a Configuration Set

You can use the Amazon SES console to view the details of a configuration set, or you can use the
DescribeConfigurationSet API to describe a configuration set.
Viewing the details of a configuration set (console)

1.
2.
3.
In the details pane, choose the expand icon next to the configuration set.
You will see the details of the configuration set.
For information about how to use the DescribeConfigurationSet API to describe a configuration
set, see the Amazon Simple Email Service API Reference.
Deleting a Configuration Set

You can use the Amazon SES console or the DeleteConfigurationSet API to delete a
configuration set.
To delete a configuration set (console)

1.
2.
3.
In the details pane, choose the configuration set.

137

4.
From the Actions menu, choose Delete, and then confirm that you want to delete the
configuration set.
For information about how to use the DeleteConfigurationSet API to delete a configuration set,
Managing Amazon SES Event Destinations

In addition to creating event destinations as described in Setting Up Event Publishing (p. 129), you
can update, delete, enable, and disable event destinations, as described in the following sections.
Updating an Event Destination

update an event destination.
To update an event destination (console)

1.
2.
3.
In the configuration set list, choose the configuration set that contains the event destination that
you want to update.
4.
In the Destination list, to the right of the destination you want to edit, choose the edit icon (the
pencil).
5.
Edit the event destination details, and then choose Save.
6.
To exit the Edit Configuration Set page, use the back button of your browser.
For information about how to use the UpdateConfigurationSetEventDestination API to update

an event destination, see the Amazon Simple Email Service API Reference.
Deleting an Event Destination

You can use the Amazon SES console or the DeleteConfigurationSetEventDestination API to
delete an event destination.
To delete an event destination (console)

1.
2.
3.
you want to delete.
4.
In the Destination list, choose the delete icon (the X in a circle).
5.
Confirm that you want to delete the configuration set.
6.
For information about how to use the DeleteConfigurationSetEventDestination API to delete

an event destination, see the Amazon Simple Email Service API Reference.
Enabling or Disabling an Event Destination

enable or disable an event destination.
138

To enable or disable an event destination (console)

1.
2.
3.
you want to enable or disable.
4.
In the Destination list, to the right of the destination you want to edit, choose the edit icon (the
pencil).
5.
Select or deselect Enabled, and then choose Save.
6.
For information about how to use the UpdateConfigurationSetEventDestination API to enable

or disable an event destination, see the Amazon Simple Email Service API Reference.
Retrieving Amazon SES Event Data

After you set up event publishing (p. 129) and specify a configuration set for sending emails, you can
retrieve your email sending events from the event destination that you specified when you set up the
configuration set associated with the email.
This section describes how to retrieve your email sending events from the available event destinations,
Amazon CloudWatch and Amazon Kinesis Firehose.
Retrieving Amazon SES Event Data from CloudWatch (p. 139)
Retrieving Amazon SES Event Data from Firehose (p. 141)
Retrieving Amazon SES Event Data from CloudWatch

Amazon SES publishes metrics for your email sending events bounces, complaints, deliveries, sent
emails, and rejected emails to Amazon CloudWatch. CloudWatch provides your email sending event
metrics as an ordered set of time-series data. You can use these metrics to monitor the performance of
your email sending. For example, you can monitor the complaint metric and set a CloudWatch alarm to
trigger when the metric exceeds a certain value.
There are two levels of granularity at which Amazon SES can publish these events to CloudWatch:
Across your AWS account These coarse metrics, which correspond to the metrics you monitor
using the Amazon SES console and the GetSendStatistics API, are totals across your entire
AWS account. Amazon SES publishes these metrics to CloudWatch automatically.
Fine-grained These metrics are categorized by email characteristics that you define using
message tags. To publish these metrics to CloudWatch, you must set up event publishing (p. 129)
with a CloudWatch event destination and specify a configuration set (p. 134) when you send
an email. You can also specify message tags or use auto-tags (p. 136) that Amazon SES
automatically provides.
This section describes the available metrics and how to view the metrics in CloudWatch.
Available Metrics
The following metrics are available from Amazon SES.
Metric
Description
Bounce
The recipients mail server permanently rejected the

email. This event corresponds to hard bounces. Soft
139

Metric
Description
bounces are included only when Amazon SES fails to
deliver the email after retrying for a period of time.
Unit: count
Complaint
The recipient marked the email as spam.

Unit: count
Delivery
Amazon SES successfully delivered the email to the

recipients mail server.
Unit: count
Reject
Amazon SES initially accepted the email, but later

rejected it because the email contained a virus.
Unit: count
Send
The email sending API call to Amazon SES was

successful and Amazon SES will attempt to deliver the
email.
Unit: count
Available Dimensions
CloudWatch uses the dimension names that you specify when you add a CloudWatch event
destination to a configuration set in Amazon SES. For more information, see Set Up a CloudWatch
Event Destination for Amazon SES Event Publishing.
Viewing Amazon SES Metrics in the CloudWatch Console

The following procedure describes how to view your Amazon SES event publishing metrics using the
CloudWatch console.
To view metrics using the CloudWatch console

1.
Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
2.
If necessary, change the region. From the navigation bar, select the region where your AWS
resources reside. For more information, see Regions and Endpoints.
3.
In the navigation pane, choose Metrics.
4.
In the All metrics pane, expand AWS Namespaces, and then choose SES.
5.
To view metrics across your entire AWS account, which Amazon SES publishes automatically,
choose Account Sending Metrics. To view fine-grained event publishing metrics (p. 127),
choose the combination of dimensions that you specified when you set up your CloudWatch event
destination (p. 130).
6.
Choose the metric you want to view.

The graph will display the metric over time.
To view metrics using the AWS CLI
At a command prompt, use the following command:

140

aws cloudwatch list-metrics --namespace "AWS/SES"
Retrieving Amazon SES Event Data from Firehose

Amazon SES publishes email sending events to Firehose as JSON records. Firehose then publishes
the records to the AWS service destination that you chose when you set up the delivery stream in
Firehose. For information about setting up Firehose delivery streams, see Creating an Amazon Kinesis
Firehose Delivery Stream in the Amazon Kinesis Firehose Developer Guide.
For examples of how you can use Firehose to publish your email sending events to Amazon Redshift
and Amazon Elasticsearch Service, see Tutorials (p. 155).
For a description of the record contents and for example records, see the following sections.
Event Record Contents (p. 141)
Event Record Examples (p. 147)
Contents of Amazon SES Event Data Published to Firehose

Amazon SES publishes email sending event records to Amazon Kinesis Firehose in JSON format.
When publishing events to Firehose, Amazon SES follows each JSON record with a newline character.
The top-level JSON object contains an eventType string, a mail object, and either a bounce,
complaint, delivery, send, or reject object.
See the following sections for descriptions of the different types of objects:
Top-level JSON object (p. 141)
mail object (p. 142)
bounce object (p. 143)
complaint object (p. 145)
delivery object (p. 147)
send object (p. 147)
reject object (p. 147)

The top-level JSON object in an email sending event record contains the following fields.
Field Name
Description
eventType
A string that holds the type of email sending

event represented by the JSON object. Possible
values are Bounce, Complaint, Delivery,
Send, and Reject.
mail
A JSON object that contains information about

the original mail to which the event pertains. For
more information, see Mail Object (p. 142).
bounce
This field is present only if the eventType

is Bounce and contains a JSON object that

141

Field Name
Description
holds information about the bounce. For more
information, see Bounce Object (p. 143).
complaint
This field is present only if the eventType is

Complaint and contains a JSON object that
holds information about the complaint. For more
information, see Complaint Object (p. 145).
delivery
This field is present only if the eventType is

Delivery and contains a JSON object that
holds information about the delivery. For more
information, see Delivery Object (p. 147).
send

is Send. For more information, see Send
Object (p. 147).
reject

is reject and contains a JSON object that
holds information about the rejection. For more
information, see Reject Object (p. 147).
Mail Object
Each email sending event record contains information about the original email in the mail object. The
JSON object that contains information about a mail object has the following fields.
Field Name
Description
timestamp
The time at which the original message was sent

(in ISO8601 format).
messageId
A unique ID that Amazon SES assigned to the

message. Amazon SES returned this value to
you when you sent the message.
Note
This message ID was assigned
by Amazon SES. You can find the
message ID of the original email in the
headers and commonHeaders fields of
the mail object.
source
The email address from which the original

message was sent (the envelope MAIL FROM
address).
sourceArn
The Amazon Resource Name (ARN) of the

identity that was used to send the email. In the
case of sending authorization, the sourceArn
is the ARN of the identity that the identity
owner authorized the delegate sender to use
to send the email. For more information about
sending authorization, see Using Sending
sendingAccountId
The AWS account ID of the account that was

used to send the email. In the case of sending
142

Field Name
Description
authorization, the sendingAccountId is the
delegate sender's account ID.
destination
A list of email addresses that were recipients of

the original mail.
headersTruncated
A string that specifies whether the headers are

truncated in the notification, which occurs if the
headers are larger than 10 KB. Possible values
are true and false.
headers
A list of the email's original headers. Each

header in the list has a name field and a value
field.
Note
Any message ID within the headers
field is from the original message
that you passed to Amazon SES.
The message ID that Amazon SES
subsequently assigned to the message
is in the messageId field of the mail
object.
commonHeaders
A list of the email's original, commonly used

headers. Each header in the list has a name field
and a value field.
Note
Any message ID within the
commonHeaders field is from the
original message that you passed to
Amazon SES. The message ID that
Amazon SES subsequently assigned to
the message is in the messageId field
of the mail object.
Bounce Object
The JSON object that contains information about a bounce event will always have the following fields.
Field Name
Description
bounceType
The type of bounce, as determined by Amazon

SES. For more information, see Bounce
Types (p. 144).
bounceSubType
The subtype of the bounce, as determined by

Amazon SES. For more information, see Bounce
Types (p. 144).
bouncedRecipients
A list that contains information about the

recipients of the original mail that bounced.
For more information, see Bounced
timestamp

143

Field Name
Description
which the bounce notification was sent by the
ISP, and not the time at which it was received by
Amazon SES.
feedbackId
A unique ID for the bounce.
Optionally, if a delivery status notification (DSN) was attached to the bounce, the following field may
also be present.
Field Name
Description
reportingMTA
The value of the Reporting-MTA field from the

DSN. This is the value of the Message Transfer
Authority (MTA) that attempted to perform the
delivery, relay, or gateway operation described in
the DSN.
Bounced Recipients
A bounce event may pertain to a single recipient or to multiple recipients. The bouncedRecipients
field holds a list of objects one object per recipient to whom the bounce event pertains and will
always contain the following field.
Field Name
Description
emailAddress
The email address of the recipient. If a DSN

is available, this is the value of the FinalRecipient field from the DSN.
Optionally, if a DSN is attached to the bounce, the following fields may also be present.
Field Name
Description
action
The value of the Action field from the DSN. This

indicates the action performed by the reporting
MTA as a result of its attempt to deliver the
message to this recipient.
status
The value of the Status field from the DSN.

This is the per-recipient transport-independent
status code that indicates the delivery status of
the message.
diagnosticCode
The status code issued by the reporting MTA.

This is the value of the Diagnostic-Code field
from the DSN. This field may be absent in the
DSN (and therefore also absent in the JSON).
Bounce Types
The following bounce types are available. We recommend that you remove the email addresses that
have returned bounces marked Permanent from your mailing list, as we do not believe that you will
be able to successfully send to them in the future. Transient bounces are sent to you when all retry
144

attempts have been exhausted and will no longer be retried. You may be able to successfully resend to
an address that initially resulted in a Transient bounce.
Note
Amazon SES only reports hard bounces and soft bounces that will no longer be retried by
Amazon SES. In other words, your recipient did not receive your email message, and Amazon
SES will not try to resend it.
bounceType
bounceSubType
Description
Undetermined Undetermined
Amazon SES was unable to determine a specific

bounce reason.
Permanent
General
Amazon SES received a general hard bounce and

recommends that you remove the recipient's email
address from your mailing list.
Permanent
NoEmail
Amazon SES received a permanent hard bounce

because the target email address does not exist.
It is recommended that you remove that recipient
from your mailing list.
Permanent
Suppressed
Amazon SES has suppressed sending to this

address because it has a recent history of
bouncing as an invalid address. For information
about how to remove an address from the
suppression list, see Removing an Email
Address from the Amazon SES Suppression
List (p. 236).
Transient
General
Amazon SES received a general bounce. You

Transient
MailboxFull
Amazon SES received a mailbox full bounce. You

Transient
MessageTooLarge
Amazon SES received a message too large

sending to that recipient if you reduce the
message size.
Transient
ContentRejected
Amazon SES received a content rejected bounce.

You may be able to successfully retry sending to
that recipient if you change the message content.
Transient
AttachmentRejected
Amazon SES received an attachment rejected

sending to that recipient if you remove or change
the attachment.
Complaint Object
The JSON object that contains information about a complaint event has the following fields.
Field Name
Description
complainedRecipients
A list that contains information about recipients

that may have submitted the complaint.
145

Field Name
Description
For more information, see Complained
timestamp

which the complaint notification was sent by the
ISP, and not the time at which it was received by
Amazon SES.
feedbackId
A unique ID for the complaint.
Further, if a feedback report is attached to the complaint, the following fields may be present.
Field Name
Description
userAgent
The value of the User-Agent field from the

feedback report. This indicates the name and
version of the system that generated the report.
complaintFeedbackType
The value of the Feedback-Type field from

the feedback report received from the ISP. This
contains the type of feedback.
arrivalDate
The value of the Arrival-Date or ReceivedDate field from the feedback report (in ISO8601
format). This field may be absent in the report
(and therefore also absent in the JSON).
Complained Recipients
The complainedRecipients field contains a list of recipients that may have submitted the complaint.
Important
Since most ISPs redact the email address of the recipient who submitted the complaint from
their complaint notification, this list contains information about recipients who might have
sent the complaint, based on the recipients of the original message and the ISP from which
we received the complaint. Amazon SES performs a lookup against the original message to
determine this recipient list.
JSON objects in this list contain the following field.
Field Name
Description
emailAddress
The email address of the recipient.
Complaint Types
You may see the following complaint types in the complaintFeedbackType field as assigned by the
reporting ISP, according to the Internet Assigned Numbers Authority website:
abuseIndicates unsolicited email or some other kind of email abuse.

auth-failureEmail authentication failure report.
fraudIndicates some kind of fraud or phishing activity.
not-spamIndicates that the entity providing the report does not consider the message to be spam.
This may be used to correct a message that was incorrectly tagged or categorized as spam.
146

otherIndicates any other feedback that does not fit into other registered types.
virusReports that a virus is found in the originating message.
Delivery Object
The JSON object that contains information about a delivery event will always have the following
fields.
Field Name
Description
timestamp
The time Amazon SES delivered the email to the

recipient's mail server (in ISO8601 format).
The time in milliseconds between when Amazon

SES accepted the request from the sender to
when Amazon SES passed the message to the
recipient's mail server.
recipients
A list of the intended recipients of the email to

which the delivery event applies.
smtpResponse
The SMTP response message of the remote ISP

that accepted the email from Amazon SES. This
message will vary by email, by receiving mail
server, and by receiving ISP.
reportingMTA
The host name of the Amazon SES mail server

that sent the mail.
Send Object
The JSON object that contains information about a send event is always empty.
Reject Object
The JSON object that contains information about a reject event will always have the following fields.
Field Name
Description
reason
The reason the email was rejected. The only

possible value is Bad content, which means
that Amazon SES detected that the email
contained a virus.
Examples of Amazon SES Event Data Published to Firehose

This section provides examples of each type of email sending event record that Amazon SES
publishes to Firehose.
The event types are as follows:
Bounce Record (p. 148)
Complaint Record (p. 149)
Delivery Record (p. 151)
Send Email Record (p. 152)
147

Reject Event Record (p. 154)
Bounce Record
The following is an example of a bounce event record that Amazon SES publishes to Firehose.
{
"eventType": "Bounce",
"bounce": {
"bounceType": "Permanent",
"bouncedRecipients": [
{
"emailAddress": "[email protected]",
"action": "failed",
"status": "5.1.1",
"diagnosticCode": "smtp; 550 5.1.1 user unknown"
}
],
"timestamp": "2016-10-14T05:02:52.574Z",
"feedbackId": "EXAMPLE7c1923f27ab0c24cb-5d9f-4e77-99b8-85e4cb3a33bb-000000",
"reportingMTA": "dsn; ses-example.com"
},
"mail": {
"timestamp": "2016-10-14T05:02:16.645Z",
"source": "[email protected]",
"sourceArn": "arn:aws:ses:us-east-1:123456789012:identity/
[email protected]",
"sendingAccountId": "123456789012",
"messageId": "EXAMPLE7c191be45-e9aedb9a-02f9-4d12-a87d-dd0099a07f8a-000000",
"destination": [
"[email protected]"
],
"headersTruncated": false,
"headers": [
{
"name": "From",
"value": "[email protected]"
},
{
"name": "To",
},
{
"name": "Subject",
"value": "Email Subject"
},
{
"name": "MIME-Version",
"value": "1.0"
},
{
"name": "Content-Type",
"value": "multipart/mixed; boundary=\"---=_Part_0_716996660.1476421336341\""
},
{
148

"name": "X-SES-MESSAGE-TAGS",
"value": "myCustomTag1=myCustomTagValue1, myCustomTag2=myCustomTagValue2"
}
],
"commonHeaders": {
"from": [
"[email protected]"
],
"to": [
"[email protected]"
],
"messageId": "EXAMPLE7c191be45-e9aedb9a-02f9-4d12-a87ddd0099a07f8a-000000",
"subject": "Email Subject"
},
"tags": {
"ses:configuration-set": [
"my-configuration-set"
],
"ses:source-ip": [
"192.0.2.0"
],
"ses:from-domain": [
"example.com"
],
"ses:caller-identity": [
"ses_user"
],
"myCustomTag1": [
"myCustomTagValue1"
],
"myCustomTag2": [
"myCustomTagValue2"
]
}
}
}
Complaint Record
The following is an example of a complaint event record that Amazon SES publishes to Firehose.
{
"eventType": "Complaint",
"complaint": {
"complainedRecipients": [
{
"emailAddress": "[email protected]"
}
],
"timestamp": "2016-10-14T17:48:17.365Z",
"feedbackId":
"01000157c44f053b-61b59c11-9236-11e6-8f96-7be8a4ae61bb-000000",
"userAgent": "Amazon SES Mailbox Simulator",
"complaintFeedbackType": "abuse",
"arrivalDate": "2016-10-14T17:48:17.584Z"
},
"mail": {
149

"timestamp": "2016-10-14T17:48:02.777Z",
[email protected]",
"destination": [
"[email protected]"
],
"headers": [
{
"name": "From",
},
{
"name": "To",
},
{
"name": "Subject",
},
{
"value": "1.0"
},
{
},
{
}
],
"commonHeaders": {
"from": [
"[email protected]"
],
"to": [
"[email protected]"
],
},
"tags": {
],
"ses:source-ip": [
"192.0.2.0"
],
"example.com"
],
150

"ses_user"
],
"myCustomTag1": [
"myCustomTagValue1"
],
"myCustomTag2": [
"myCustomTagValue2"
]
}
}
}
Delivery Record
The following is an example of a delivery event record that Amazon SES publishes to Firehose.
{
"eventType": "Delivery",
"mail": {
"timestamp": "2016-10-19T23:20:52.240Z",
[email protected]",
"destination": [
"[email protected]"
],
"headers": [
{
"name": "From",
},
{
"name": "To",
},
{
"name": "Subject",
},
{
"value": "1.0"
},
{
"value": "text/html; charset=UTF-8"
},
{
"name": "Content-Transfer-Encoding",
"value": "7bit"
}
],
"commonHeaders": {
"from": [
"[email protected]"
151

],
"to": [
"[email protected]"
],
},
"tags": {
],
"ses:source-ip": [
"192.0.2.0"
],
"example.com"
],
"ses_user"
],
"ses:outgoing-ip": [
"192.0.2.0"
],
"myCustomTag1": [
"myCustomTagValue1"
],
"myCustomTag2": [
"myCustomTagValue2"
]
}
},
"delivery": {
"timestamp": "2016-10-19T23:21:04.133Z",
"processingTimeMillis": 11893,
"recipients": [
"[email protected]"
],
"smtpResponse": "250 2.6.0 Message received",
"reportingMTA": "mta.example.com"
}
}
Send Email Record

The following is an example of a send event record that Amazon SES publishes to Firehose.
{
"eventType": "Send",
"mail": {
"timestamp": "2016-10-14T05:02:16.645Z",
[email protected]",
"destination": [
"[email protected]"
152

],
"headers": [
{
"name": "From",
},
{
"name": "To",
},
{
"name": "Subject",
},
{
"value": "1.0"
},
{
},
{
}
],
"commonHeaders": {
"from": [
"[email protected]"
],
"to": [
"[email protected]"
],
},
"tags": {
],
"ses:source-ip": [
"192.0.2.0"
],
"example.com"
],
"ses_user"
],
"myCustomTag1": [
"myCustomTagValue1"
],
"myCustomTag2": [
"myCustomTagValue2"
]
153

}
},
"send": {}
}
Reject Event Record

The following is an example of a reject event record that Amazon SES publishes to Firehose.
{
"eventType": "Reject",
"mail": {
"timestamp": "2016-10-14T17:38:15.211Z",
[email protected]",
"destination": [
"[email protected]"
],
"headers": [
{
"name": "From",
},
{
"name": "To",
},
{
"name": "Subject",
},
{
"value": "1.0"
},
{
"value": "multipart/mixed; boundary=\"qMm9M+Fa2AknHoGS\""
},
{
}
],
"commonHeaders": {
"from": [
"[email protected]"
],
"to": [
"[email protected]"
],
154

},
"tags": {
],
"ses:source-ip": [
"192.0.2.0"
],
"example.com"
],
"ses_user"
],
"myCustomTag1": [
"myCustomTagValue1"
],
"myCustomTag2": [
"myCustomTagValue2"
]
}
},
"reject": {
"reason": "Bad content"
}
}
Amazon SES Event Publishing Tutorials

This section provides tutorials that demonstrate how to use Amazon SES event publishing with AWS
services that enable you to analyze and visualize your data.
These tutorials are contained in the following sections.
Analyze Email Sending Events With Amazon Redshift (p. 155)
Visualize Email Sending Events With Amazon Elasticsearch Service and Kibana (p. 166)
Graph Email Sending Events in CloudWatch (p. 176)
Analyze Email Sending Events With Amazon Kinesis Analytics (p. 179)
Analyze Email Sending Events With Amazon Redshift

In this tutorial, you publish Amazon SES email sending events to an Amazon Kinesis Firehose delivery
stream that publishes data to Amazon Redshift. You then connect to the Amazon Redshift database
and use a SQL query tool to query the database for Amazon SES email sending events that meet
certain criteria.
The following sections walk you through the process.
Prerequisites (p. 156)
Step 1: Create an Amazon Redshift Cluster (p. 156)
Step 2: Connect to Your Amazon Redshift Cluster (p. 157)
Step 3: Create a Database Table (p. 159)
Step 4: Create a Firehose Delivery Stream (p. 161)
Step 5: Set up a Configuration Set (p. 164)
Step 6: Send Emails (p. 164)
155

Step 7: Query Email Sending Events (p. 165)
Prerequisites
For this tutorial, you will need the following:
An AWS account To access any web service that AWS offers, you must first create an AWS
account at https://aws.amazon.com/.
Verified email address To send emails using Amazon SES, you must verify your "From"
address or domain to show that you own it. If you are in the sandbox, you also must verify your "To"
addresses. You can verify email addresses or entire domains, but this tutorial requires a verified
email address so that you can send an email from the Amazon SES console, which is the simplest
way to send an email. For information about how to verify an email address, see Verifying Email
Addresses in Amazon SES (p. 39).
A SQL query tool Amazon Redshift does not provide or install any SQL client tools or libraries,
so you must install one that you can use to access the Amazon Redshift clusters that contain your
Amazon SES events. In this tutorial, we use SQL Workbench/J, a free, DBMS-independent, crossplatform SQL query tool. The following steps show you were to go to install it.
The following procedure shows how to install SQL Workbench/J.
To install SQL Workbench/J on Your Client Computer

1.
Review the SQL Workbench/J software license.
2.
Go to the SQL Workbench/J website and download the appropriate package for your operating
system.
3.
Go to Installing and starting SQL Workbench/J and install SQL Workbench/J.
Important
Note the Java runtime version prerequisites for SQL Workbench/J and ensure you are
using that version. Otherwise, this client application will not run.
4.
Go to Configure a JDBC Connection and download an Amazon Redshift JDBC driver to enable
SQL Workbench/J to connect to your cluster.
Next Step
Step 1: Create an Amazon Redshift Cluster (p. 156)
Step 1: Create an Amazon Redshift Cluster

To create an Amazon Redshift cluster, go the Amazon Redshift console and choose Launch Cluster.
A wizard guides you through choosing options for your cluster, and it provides default values for most
options.
For this simple tutorial, type a cluster name and password, and then you can use all of the default
values. You do not need to set any values specific to Amazon SES event publishing.
Important
The cluster that you deploy for this tutorial will run in a live environment. As long as it is
running, it will accrue charges to your AWS account. To avoid unnecessary charges, you
should delete your cluster when you are done with it. For pricing information, go to the
Amazon Redshift pricing page.
Next Step
Step 2: Connect to Your Amazon Redshift Cluster (p. 157)
156

Step 2: Connect to Your Amazon Redshift Cluster

Now you will connect to your cluster by using a SQL client tool. For this tutorial, you use the SQL
Workbench/J client that you installed in the prerequisites section (p. 156).
Complete this section by performing the following steps:
Getting Your Connection String (p. 157)
Connecting to Your Cluster From SQL Workbench/J (p. 157)
Getting Your Connection String

The following procedure shows how to get the connection string that you will need to connect to your
Amazon Redshift cluster from SQL Workbench/J.
To get your connection string

1.
In the Amazon Redshift console, in the navigation pane, choose Clusters.
2.
To open your cluster, choose your cluster name.
3.
On the Configuration tab, under Cluster Database Properties, copy the JDBC URL of the
cluster.
Note
The endpoint for your cluster is not available until the cluster is created and in the
available state.
Connecting to Your Cluster From SQL Workbench/J

The following procedure shows how to connect to your cluster from SQL Workbench/J. This
procedure assumes that you installed SQL Workbench/J on your computer as described in
Prerequisites (p. 156).
To connect to your cluster from SQL Workbench/J

1.
Open SQL Workbench/J.

157

2.
Choose File, and then choose Connect window.
3.
Choose the Create a new connection profile button.
4.
In the New profile text box, type a name for the profile.
5.
At the bottom of the window, on the left, choose Manage Drivers.
6.
In the Manage Drivers dialog box, choose the Create a new entry button, and then add the driver
as follows.
a.
In the Name box, type a name for the driver.
b.
Next to Library, choose the folder icon.
c.
Navigate to the location of the driver you downloaded in Configure a JDBC Connection, select
the driver, and then choose Open.
d.
Choose OK.
You will be taken back to the Select Connection Profile dialog box.
7.
For Driver, choose the driver that you just added.
8.
For URL, paste the JDBC URL that you copied from the Amazon Redshift console.
9.
For Username, type the username that you chose when you set up the Amazon Redshift
cluster (p. 156).
10. For Password, type the password that you chose when you set up the Amazon Redshift cluster.
11. Select Autocommit.
12. To test the connection, choose Test.
Note
If the connection attempt times out, you might need to add your IP address to the security
group that allows incoming traffic from IP addresses. For more information, see The
Connection Is Refused or Fails in the Amazon Redshift Database Developer Guide.

158

13. On the top menu bar, choose the Save profile list button.
14. Choose OK.
SQL Workbench/J will connect to your Amazon Redshift cluster.
Next Step
Step 3: Create a Database Table (p. 159)
Step 3: Create a Database Table

After you connect to the initial database in Amazon Redshift, you typically use the initial database as
the base for creating a new database. However, in this simple tutorial, we create a table to hold your
Amazon SES event publishing data directly within the initial database.
For this tutorial, let's assume that we're interested in the following fields within the email sending event
records (p. 141). All of these fields, except for mail.tags.campaign, are provided automatically by
Amazon SES. We introduce the mail.tags.campaign field when we send an email using campaign
as a message tag in Step 6: Send Emails (p. 164).
mail.messageId
eventType
mail.sendingAccountId
mail.timestamp
mail.destination
mail.tags.ses:configuration-set
mail.tags.campaign

159

To access this information within your database, you must create a table. The following procedure
shows how to specify this information when you create the table in your database.
Note
We assume that SQL Workbench/J is currently open on your computer, and it is connected to
your Amazon Redshift cluster, as described in previous step (p. 157).
To create a table using SQL Workbench/J

1.
In SQL Workbench/J, copy the following code and paste it into the Statement 1 window.
create table ses (
message_id varchar(200) not null,
event_type varchar(20) not null,
sending_account_id char(12),
timestamp varchar(50),
destination text,
configuration_set text,
campaign text
);
2.
Place the cursor within the statement (somewhere before the semicolon), and then choose the
Execute current statement button, as shown in the following figure.
3.
In the Messages pane, verify that your table was successfully created.
Next Step
160

Step 4: Create a Firehose Delivery Stream

To publish email sending events to Amazon Kinesis Firehose, you must create a Firehose delivery
stream. When you set up a Firehose delivery stream, you choose where Firehose publishes the data.
For this tutorial, we will set up Firehose to publish the data to Amazon Redshift, and choose to have
Firehose publish the records to Amazon S3 as an intermediary step. In the process, we need to specify
how Amazon Redshift should copy records from Amazon S3 into the table we created in the previous
step (p. 159).
This section shows how to create a Firehose delivery stream that sends data to Amazon Redshift, and
how to edit the delivery stream to specify how Amazon Redshift should copy the Amazon SES event
publishing data to Amazon S3.
Note
You must have already set up the Amazon Redshift cluster (p. 156), connected to your
cluster (p. 157), and created a database table (p. 159), as explained previous steps.
Creating a Firehose Delivery Stream

The following procedure shows how to create a Firehose delivery stream that publishes data to
Amazon Redshift, using Amazon S3 as the intermediary data location.
To create a delivery stream from Firehose to Amazon Redshift

1.
Sign in to the AWS Management Console and open the Firehose console at https://
console.aws.amazon.com/firehose/.
2.
Choose Create Delivery Stream.
3.
On the Destination page, choose the following options.

Destination Choose Amazon Redshift.
Delivery stream name Type a name for the delivery stream.
S3 bucket Choose New S3 bucket, type a bucket name, choose the region, and then choose
Create Bucket.
Redshift cluster Choose the Amazon Redshift cluster that you created in a previous step.
Redshift database Type dev, which is the default database name.
Redshift table Type ses, which is the table you created in Step 3: Create a Database
Table (p. 159).
Redshift table columns Leave this field empty.
Redshift username Type the username that you chose when you set up the Amazon Redshift
cluster (p. 156).
Redshift password Type the password that you chose when you set up the Amazon Redshift
cluster.
Redshift COPY options Leave this field empty.
Retry duration Leave this at its default value.
COPY command Leave this at its default value. You will update it in the next procedure.
4.
Choose Next.
5.
On the Configuration page, leave the fields at the default settings for this simple tutorial. The
only step you must do is select an IAM role that enables Firehose to access your resources, as
explained in the following procedure.
a.
For IAM Role, choose Select an IAM role.
b.
In the drop-down menu, under Create/Update existing IAM role, choose Firehose delivery
IAM role.
You will be taken to the IAM console.
161

c.
In the IAM console, leave the fields at their default settings, and then choose Allow.
You will return to the Firehose delivery stream set-up steps in the Firehose console.
6.
Choose Next.
7.
On the Review page, review your settings, and then choose Create Delivery Stream.
Setting Amazon Redshift Copy Options

Next, you must specify to Amazon Redshift how to copy the Amazon SES event publishing JSON
records into the database table you created in Step 3: Create a Database Table (p. 159). You do this
by editing the copy options in the Firehose delivery stream.
For this procedure, you must create a JSONPaths file. A JSONPaths file is a text file that specifies to
the Amazon Redshift COPY command how to parse the JSON source data. We provide a JSONPaths
file in the procedure. For more information about JSONPaths files, see COPY from JSON Format in the
Amazon Redshift Database Developer Guide.
You upload the JSONPaths file to the Amazon S3 bucket you set up when you created the Firehose
delivery stream, and then edit the COPY options of the Firehose delivery stream to use the JSONPaths
file you uploaded. These steps are explained in the following procedure.
To set Amazon Redshift COPY command options

1.
Create a JSONPaths file On your computer, create a file called jsonpaths.json. Copy the
following text into the file, and then save the file.
{
"jsonpaths": [
"$.mail.messageId",
"$.eventType",
"$.mail.sendingAccountId",
162

"$.mail.timestamp",
"$.mail.destination",
"$.mail.tags.ses:configuration-set",
"$.mail.tags.campaign"
]
}
2.
Upload the JSONPaths file to the Amazon S3 bucket Go to the Amazon S3 console and
upload the file to the bucket you created when you set up the Firehose delivery stream in Creating
a Firehose Delivery Stream (p. 161).
3.
Set the COPY command in the Firehose delivery stream settings Now you have the
information you need to set the syntax of the COPY command that Amazon Redshift uses when it
puts your data in the table you created. The following procedure shows how to update the COPY
command information in the Firehose delivery stream settings.
1. Go to the Firehose console.
2. Under Redshift Delivery Streams, choose the Firehose delivery stream that you created for
Amazon SES event publishing.
3. On the Details page, choose Edit.
4. In the Redshift COPY options box, type the following text, replacing the following values with
your own values:
S3-BUCKET-NAME The name of the Amazon S3 bucket where Firehose places your
data for Amazon Redshift to access. You created this bucket when you set up your Firehose
delivery stream in Step 4: Create a Firehose Delivery Stream (p. 161). An example is mybucket.
REGION The region in which your Amazon SES, Firehose, Amazon S3, and Amazon
Redshift resources are located. An example is us-west-2.
json 's3://S3-BUCKET-NAME/jsonpaths.json' region 'REGION';
5. Choose Save.

163

Next Step
Step 5: Set up a Configuration Set

To set up Amazon SES to publish your email sending events to Amazon Kinesis Firehose, you first
create a configuration set, and then you add a Firehose event destination to the configuration set. This
section shows how to accomplish those tasks.
If you already have a configuration set, you can add a Firehose destination to your existing
configuration set. In this case, skip to Adding a Firehose Event Destination (p. 164).
Creating a Configuration Set

The following procedure shows how to create a configuration set.
To create a configuration set

1.
2.
3.
4.
5.
Choose Close.
Adding a Firehose Event Destination

The following procedure shows how to add a Firehose event destination to the configuration set you
created.
To add a Firehose event destination to the configuration set

1.
Choose the configuration set from the configuration set list.
2.
3.
4.
Select all Event types.
5.
Select Enabled.
6.
For Stream, choose the delivery stream that you created in Step 4: Create a Firehose Delivery
Stream (p. 161).
7.
For IAM role, choose Let SES make a new role, and then type a name for the role.
8.
Choose Save.
9.
Next Step
Step 6: Send Emails

For Amazon SES to publish events associated with an email, you must specify a configuration set
when you send the email. You can also include message tags to categorize the email. This section
shows how to send a simple email that specifies a configuration set and message tags using the
164

Amazon SES console. You send the email to the Amazon SES mailbox simulator so that you can test
bounces, complaints, and other email sending outcomes.
To send an email using the Amazon SES console

1.
2.
In the navigation pane of the Amazon SES console, under Identity Management, choose Email
Addresses.
3.
In the list of identities, select the check box of an email address that you have successfully verified
with Amazon SES (p. 39).
4.
5.

In the Send Test Email dialog box, for Email Format, choose Raw.
6.
For the To address, type an address from the Amazon SES mailbox simulator (p. 224), such as
[email protected] or [email protected].
7.
Copy and paste the following message in its entirety into the Message text box, replacing
CONFIGURATION-SET-NAME with the name of the configuration set you created in Step 5: Set up
a Configuration Set (p. 164), and replacing FROM-ADDRESS with the verified address you are
sending this email from.
X-SES-MESSAGE-TAGS: campaign=book
X-SES-CONFIGURATION-SET: CONFIGURATION-SET-NAME
Subject: Amazon SES Event Publishing Test
From: Amazon SES User <FROM-ADDRESS>
MIME-Version: 1.0
Content-Type: text/plain
This is a test message.
8.
9.

Repeat this procedure a few times so that you generate multiple email sending events. For a few
of the emails, change the value of the campaign message tag to clothing to simulate sending
for a different email campaign. That way, when you query your Amazon Redshift database for
email sending event records in the last step of this tutorial, you can experiment with querying
based on email campaign.
Next Step
Step 7: Query Email Sending Events (p. 165)
Step 7: Query Email Sending Events

Now that you have generated some email sending events by sending emails with your configuration set
and message tags, you can query those records in Amazon Redshift.
Note
We assume that SQL Workbench/J is currently open on your computer, and it is connected
to your Amazon Redshift cluster, as described in Step 2: Connect to Your Amazon Redshift
Cluster (p. 157).
To query email sending event data in Amazon Redshift from SQL Workbench/J
1.
To display all of your email sending records, copy the following query and paste it into the
Statement 1 window.
select * from ses;

165

2.
Execute current statement button.
You will see the email sending records for all of the emails you sent in Step 6: Send
Emails (p. 164). The records in the following figure show that our book campaign had two
complaints, and the clothing campaign had one bounce.
3.
To count the complaint records for the campaign of type book, copy the following query and
paste it into the Statement 1 window.
select count(*) as numberOfComplaint from ses where event_type =
'Complaint' and campaign like '%book%';
4.
Execute current statement button.
The results are the following, showing that the book campaign had two complaints.
Visualize Email Sending Events With Amazon Elasticsearch Service and

Kibana
Elasticsearch is an open-source search and analytics engine for use cases such as log analytics and
real-time application monitoring. Amazon Elasticsearch Service (Amazon ES) is an AWS service that
enables you to deploy, operate, and scale Elasticsearch in the AWS cloud. You can use Amazon ES to
analyze your Amazon SES email sending events.
In this tutorial, you publish Amazon SES email sending events to an Amazon Kinesis Firehose delivery
stream that publishes the event data to Amazon ES. You then view the data with Kibana, an opensource visualization tool designed to work with Elasticsearch. Amazon ES includes built-in integration
with Kibana.
166


Step 1: Create an Amazon ES Cluster (p. 167)
Step 5: Visualize Data in Kibana (p. 171)
Prerequisites
Next Step
Step 1: Create an Amazon ES Cluster (p. 167)
Step 1: Create an Amazon ES Cluster

Before you set up Amazon Kinesis Firehose to publish your Amazon SES email sending events to
Amazon Elasticsearch Service (Amazon ES), you must create an Amazon ES cluster. This section
shows how to create an Amazon ES cluster using the Amazon ES console.
For the simplicity of this tutorial, we choose basic options. For information about all available options,
see the Amazon Elasticsearch Service Developer Guide.
Important
The cluster that you deploy for this tutorial will run in a live environment. As long as it is
running, it will accrue charges to your AWS account. To avoid unnecessary charges, you
should delete your cluster when you are done with it. For pricing information, go to the
Amazon Elasticsearch Service pricing page.
To create an Amazon ES cluster

1.
Sign in to the AWS Management Console and open the Amazon Elasticsearch Service console at
https://console.aws.amazon.com/es/.
2.
3.
4.
5.
6.
In the Amazon ES console, choose Get started.

On the Define domain page, under Domain Name, type a name for your Amazon ES domain.
Under Version, leave the Elasticsearch version field at its default value.
Choose Next.
On the Configure cluster page, under Node configuration, choose the following options.
Instance count Type 1.
Instance type Choose t2.micro.elasticsearch (Free tier eligible).
Enable dedicated master Do not enable this option.
Enable zone awareness Do not enable this option.
167

7.
8.
9.
Under Storage configuration, choose the following options.

Storage type Choose EBS. For the EBS settings, choose EBS volume type of General
Purpose (SSD) and EBS volume size of 10.
Automated snapshot start hour Choose Automated snapshots start hour 00:00 UTC
(default).
Choose Next.
On the Set up access policy page, for Set the domain access policy to, choose Allow open
access to the domain.
Important
This setting simplifies testing but is not recommended for production environments.
For information about configuring access policies, see Configuring Access Policies in the
Amazon Elasticsearch Service Developer Guide.
10. Choose Next.
11. On the Review page, review your settings, and then choose Confirm and create.
Note
The cluster will take up to ten minutes to deploy.
Next Step

To publish email sending events to Amazon Kinesis Firehose, you must create a Firehose delivery
stream. When you set up a Firehose delivery stream, you choose where Firehose publishes the data.
In this tutorial, we set up Firehose to publish the data to Amazon Elasticsearch Service (Amazon ES).
This section shows how to create a Firehose delivery stream using the Firehose console. For the
simplicity of this tutorial, we choose basic options. For information about all available options, see
Creating an Amazon Kinesis Firehose Delivery Stream in the Amazon Kinesis Firehose Developer
Guide.
Note
You must have already set up an Amazon ES cluster, as explained in Step 1: Create an
Amazon ES Cluster (p. 167).
To create a delivery stream from Firehose to Amazon Elasticsearch Service

1.
2.
3.
Destination Choose Amazon Elasticsearch Service.
Elasticsearch domain Choose the Amazon ES domain that you created in Step 1: Create an
Amazon ES Cluster (p. 167).
Index Type a name that you want to use to explore your email sending event data in Kibana.
You can choose any name, but let's use holiday-sale for this tutorial. An index is analogous
to a database. For example, if you want an easy way to access events from each of your email
campaigns separately, you can use a different Firehose stream and index for each campaign.
Index rotation Choose NoRotation.
Type Although this setting is not relevant to this tutorial, you must choose something, so type
events. A type is a logical category or partition of your index.
168

Retry duration (sec) Type 300.

Backup mode Choose Failed Documents Only.
S3 bucket Choose New S3 Bucket. Type a name for the bucket and choose the region your
console is currently using.
S3 prefix Leave this field empty.
4.
Choose Next.
5.
On the Configuration page, leave the fields at the default settings. The only step you must do is
select an IAM role that enables Firehose to access your resources, as explained in the following
procedure.
a.
b.
IAM role.
You will be taken to the IAM console.
c.
You will return to the Firehose delivery stream set-up steps in the Firehose console.
6.
Choose Next.
7.
Next Step

To set up Amazon SES to publish your email sending events to Amazon Kinesis Firehose, you first
create a configuration set, and then you add a Firehose event destination to the configuration set. This
169



1.
2.
3.
4.
5.
Choose Close.

created.

1.
2.
3.
4.
5.
Select Enabled.
6.
Stream (p. 168).
7.
8.
Choose Save.
9.
Next Step
Step 4: Send Emails


1.
2.
Addresses.
170

3.
4.
5.
6.
7.
MIME-Version: 1.0
8.
9.
for a different email campaign.
Next Step
Step 5: Visualize Data in Kibana (p. 171)
Step 5: Visualize Data in Kibana

Now that you have published some Amazon SES email sending events to Amazon Elasticsearch
Service (Amazon ES) by sending emails with your configuration set and message tags, you can
visualize the events using Kibana, a web interface for Elasticsearch.
This section shows how to find your email sending events in Kibana, graph your email sending events
by event type, and find the email addresses that bounced. These exercises are useful because
monitoring your bounces and complaints is an important part of maintaining your mailing list.
Viewing Your Email Sending Events (p. 171)
Graphing Your Email Sending Events by Type (p. 173)
Finding Recipient Addresses That Bounced (p. 174)
For Kibana documentation and tutorials, see the Kibana User Guide.
Viewing Your Email Sending Events

The following procedure shows how to go to the Kibana user interface from the Amazon ES console.
It then shows how to view the email sending events associated with the index you defined when
you set up your Amazon Kinesis Firehose delivery stream in Step 2: Create a Firehose Delivery
Stream (p. 168).
To view your raw email sending events in Kibana

1.
Sign in to the AWS Management Console and open the Amazon Elasticsearch Service console at
https://console.aws.amazon.com/es/.
171

2.
Under My Elasticsearch domains, choose the domain you created in Step 1: Create an Amazon
ES Cluster (p. 167).
3.
Choose the Kibana link.
You will be directed to the Kibana web interface.

4.
On the Configure an index pattern page, clear the Index contains time-based events check
box.
5.
Under Index name or pattern, verify that holiday-sale, the index you created in Step 1: Create
an Amazon ES Cluster (p. 167), is present. If it is not present, type holiday-sale* into the
field, and then choose Create.
Note
If the Create button does not appear, try adding an asterisk to the end of the index
pattern.
6.
Choose the Discover tab on the top menu.
7.
In the search box below the Discover tab, put the cursor after the asterisk (*), and then press
Enter.
Kibana will display a list of all of your email sending events.

172

Graphing Your Email Sending Events by Type

For insight into the overall health of your email campaign, you can visually compare the number of
problematic outcomes (bounces, complaints, and rejected emails) you have received across your
campaign. The following procedure shows how to set up a vertical bar chart that displays the count of
each type of email sending event.
To graph your email sending events by type

1.
Choose the Visualize tab on the top menu.
2.
Choose Vertical bar chart.
3.
Choose From a new search. If prompted for an index pattern, choose holiday-sale*.
4.
On the metrics pane, next to Y-Axis, ensure that the metric is set to Count.
5.
In the Buckets pane, choose X-Axis.
6.
For Aggregation, choose Terms. Terms refers to the fields in your JSON documents in your
index.
7.
For Field, under String, choose eventType. Leave the rest of the fields at their default values.
8.
Next to Options, choose the play button. Your bar chart comparing the event types will display on
the screen.

173

9.
To save your visualization, choose the save icon from the group of icons to the right of the search
bar.
10. Type a title such as All Event Types, and then choose Save.
Finding Recipient Addresses That Bounced

Now that you have a visualization of the health of your overall email campaign, you can go back to the
raw data and find out which recipient addresses bounced, as described in the following procedure.
To view the email addresses that bounced

1.
Go to the Discover tab on the top menu.

You will see a list of your raw event records.
Note
If the main window reports that there are zero search results, enter * in the search bar,
and then press Enter.
2.
In the left pane, under Available Fields, hover over eventType, and then choose the add button
that appears next to it.

174

3.
In the main window, hover over the eventType column heading, and then choose the arrow to sort
the event types by name.
The bounce events will move to the top of the list.
Note
There might be a short delay before the events are resorted.
4.
In the left pane, under Available Fields, hover over bounce.bouncedRecipients, and then
choose the add button that appears next to it.
In the main window, you will see the recipient address and bounce reason for each bounce event.

175

Graph Events in Amazon CloudWatch

In this tutorial, you publish Amazon SES email sending events to Amazon CloudWatch and then graph
the events using the CloudWatch console.
Step 3: Graph Events (p. 178)
Prerequisites
Next Step

To set up Amazon SES to publish your email sending events to Amazon CloudWatch, you first create
a configuration set, and then you add a CloudWatch event destination to the configuration set. This

176

If you already have a configuration set, you can add a CloudWatch destination to your existing
configuration set. In this case, skip to Adding a CloudWatch Event Destination (p. 177).


1.
2.
3.
4.
5.
Choose Close.
Adding a CloudWatch Event Destination

The following procedure shows how to add a CloudWatch event destination to the configuration set you
created.
To add a CloudWatch event destination to a configuration set

1.
2.
3.
4.
Choose the configuration set you created in the previous procedure.

For Add Destination, choose Select a destination type, and then choose CloudWatch.
5.
6.
7.

For Event types, choose Bounce and Complaint.
Select Enabled.
8.
9.
For Value Source, choose Message Tag.

For Dimension Name, type campaign.
10. For Default Value, type unknown.

177

11. Choose Save.

Step 2: Send Emails


1.
2.
Addresses.
3.
4.
5.
6.
7.
MIME-Version: 1.0
8.
9.
for a different email campaign.
Next Step
Step 3: Graph Email Sending Events (p. 178)
Step 3: Graph Email Sending Events

Now that you have published some Amazon SES email sending events to CloudWatch by sending
emails with your configuration set and message tags, you can graph metrics for those events using the
CloudWatch console.
To graph email sending event metrics

1.
Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

178

2.
In the left navigation pane, choose Metrics.
3.
In the All metrics tab, choose SES.

You can also type SES into the search field.
4.
Choose Per configuration set.
5.
Select the metric to view.

A graph appears in the details pane.
Analyze Email Sending Events With Amazon Kinesis Analytics

Amazon Kinesis Analytics enables you to process and analyze streaming data using SQL. You can use
Amazon Kinesis Analytics to analyze your Amazon SES email sending events.
In this tutorial, you first set up an Amazon SES configuration set to publish your email sending events
to an Amazon Kinesis Firehose delivery stream, and then you send emails through Amazon SES using
that configuration set. You then set up Amazon Kinesis Analytics to capture the email sending events
from the Firehose stream and use SQL to extract key information from the emails you sent.
Note
This tutorial requires that you have an application that can send a steady stream of emails
through Amazon SES. This requirement is explained in Prerequisites (p. 179).
The following sections walk you through the tutorial.
Step 4: Create an Amazon Kinesis Analytics Application (p. 182)
Step 5: Run a SQL Query (p. 187)
(Optional) Step 6: Save SQL Query Results (p. 188)
Prerequisites
For this tutorial, you need the following:
Email application To use Amazon Kinesis Analytics as described in this tutorial, you must send
a steady stream of emails through Amazon SES so that you generate a steady stream of email
sending events. This enables Amazon Kinesis Analytics to automatically detect the schema and
then to process the event records with SQL. Sending one email every ten seconds for five minutes is
sufficient for this tutorial.
Important
If you do not have an existing email campaign to send to real recipients, we strongly
recommend that you send emails to an Amazon SES mailbox simulator (p. 224) address.
179

Emails that you send to the mailbox simulator do not count toward your Amazon SES
bounce and complaint rates or your daily sending quota.
Next Step

To analyze Amazon SES email sending events with Amazon Kinesis Analytics, you must configure
Amazon SES to publish the events to an Amazon Kinesis Firehose delivery stream, and then configure
Amazon Kinesis Analytics to get the event data from Firehose.
When you set up a Firehose delivery stream, you choose the final destination of the data. Your
destination options are Amazon Simple Storage Service (Amazon S3), Amazon Elasticsearch Service,
and Amazon Redshift. If you simply want to analyze email sending events with Amazon Kinesis
Analytics, it does not matter which destination you choose. For this tutorial, we configure Firehose to
publish the data to Amazon S3, but you can use the other destination options if they are in the same
region as your Amazon SES sending and Firehose delivery stream.
This section shows how to create a Firehose delivery stream using the Firehose console. For this
tutorial, we choose basic options. For information about all available options, see Creating an Amazon
Kinesis Firehose Delivery Stream in the Amazon Kinesis Firehose Developer Guide.
To create a delivery stream from Firehose to Amazon S3

1.
2.
3.

Destination Choose Amazon S3.
S3 bucket Choose an existing bucket, or choose New S3 Bucket. If you create a new bucket,
type a name for the bucket and choose the region your console is currently using.
S3 prefix Leave this field empty.
4.
Choose Next.
5.
On the Configuration page, leave the fields at the default settings. The only required step is to
select an IAM role that enables Firehose to access your resources, as follows:
a.
b.
IAM role.
You are taken to the IAM console.
c.

180

You return to the Firehose delivery stream set-up steps in the Firehose console.
6.
Choose Next.
7.
Next Step

To set up Amazon SES to publish your email sending events to Amazon Kinesis Firehose, you create
a configuration set, and then you add a Firehose event destination to the configuration set. This section
describes how to accomplish those tasks.

The following procedure describes how to create a configuration set.

1.
2.
3.
4.
5.
Choose Close.

181


created.

1.
2.
3.
4.
5.
Select Enabled.
6.
Stream (p. 180).
7.
8.
9.
Choose Save.
Next Step
Step 3: Send Emails

Because this tutorial uses the Amazon Kinesis Analytics console to process and analyze streaming
data, you must set up a steady stream of emails through Amazon SES. This tutorial assumes that you
have an application that can send these emails. Sending one email every ten seconds for five minutes
is sufficient for this tutorial. We highly recommend that you use a "To" address from the Amazon SES
mailbox simulator (p. 224), such as [email protected].
To enable event publishing for an email, you provide the name of the configuration set to Amazon
SES when you send the email. You can optionally include message tags to categorize the email. You
provide this information to Amazon SES as either parameters to the email sending API, Amazon SESspecific email headers, or custom headers in your MIME message. For more information, see Send
Email Using Amazon SES Event Publishing (p. 134).
For example, you might add the following Amazon SES-specific email headers to your email to
simulate a book campaign. Replace CONFIGURATION-SET-NAME with the name of the configuration
set you created in Step 2: Set up a Configuration Set (p. 181).
Next Step
Step 4: Create an Amazon Kinesis Analytics Application (p. 182)
Step 4: Create an Amazon Kinesis Analytics Application

Now that you have set up event publishing with Amazon SES, you can configure Amazon Kinesis
Analytics to capture the email sending event data from your Amazon Kinesis Firehose delivery stream.
To do this, you create an Amazon Kinesis Analytics application.
The following procedure shows how to use the Amazon Kinesis Analytics console to create an
application that captures Amazon SES email sending event data from your Firehose delivery stream,
and then how to perform a simply SQL query on the data to return the events of type "Send".
182

Note
The email sending events of different event types (send, bounce, complaint, and delivery)
have different JSON schemas (p. 141). In a production environment, you might examine
several fields of this schema, but in this tutorial, we limit our examination to a small set of
fields that are present for all event types.
To create an Amazon Kinesis Analytics application

1.
Start sending a steady stream of emails configured for event publishing through Amazon SES, and
continue sending the emails throughout this procedure. This is required so that Amazon Kinesis
Analytics can automatically detect the schema of the event records. Sending one email every
ten seconds for five minutes is sufficient for this tutorial. For more information, see Step 3: Send
Emails (p. 182).
After your email program has sent a few emails, move to the next step.
2.
Sign in to the AWS Management Console and open the Analytics console at https://
console.aws.amazon.com/kinesisanalytics.
3.
Choose Create new application.
4.
Enter an application name and description, and then choose Save and continue.
5.
Choose Connect to a source.
6.
Choose the Firehose stream you created in Step 2: Set up a Configuration Set (p. 181).
Amazon Kinesis Analytics attempts to discover the schema of the email sending event records
based on the incoming records. If Amazon Kinesis Analytics displays Error discovering input
schema, that means that Amazon Kinesis Analytics has not received any email sending records
yet. Choose Rediscover schema. You might need to choose this button several times. If schema
discovery does not succeed after several attempts, ensure that your email sending application is
steadily sending emails, and that the emails specify a configuration set.
When Amazon Kinesis Analytics detects a schema, it displays a success message and lists the
records it detected.
Important
Do not choose Save and continue. This will cause errors because the discovered
schema does not adhere to SQL naming constraints. You must edit the schema as
described in the next step.
7.
Choose Edit schema.

183

8.
For this tutorial, we remove most of the rows. Choose X next to all rows except rows with the
following column names:
eventType
timestamp
messageId
to
ses:configuration-set
Important
Do not choose Save schema and update stream samples. This will cause errors
because the discovered schema does not adhere to SQL naming constraints. You must
edit the schema as described in the next step.

184

9.
Examine the remaining entries under Column name and compare them to the SQL naming
requirements as follows:
Format As described in Identifiers in the Amazon Kinesis Analytics SQL Reference,
unquoted identifiers must start with a letter or underscore, and be followed by letters, digits, or
underscores. Amazon SES auto-tag names do not comply with these requirements because
they contain colons and dashes. You will edit these in the next step.
Reserved words Column names must not conflict with the SQL reserved words listed in
Reserved Words and Keywords in the Amazon Kinesis Analytics SQL Reference. Examples of
reserved keywords that conflict with Amazon SES event records are timestamp, value, date,
from, and to.
10. Edit the remaining column names to conform to the SQL requirements as follows:
Rename ses:configuration-set to ses_configuration_set.
Rename timestamp to ses_timestamp.
Rename to to ses_to.

185

11. Choose Save schema and update stream samples. If you encounter validation errors, ensure
that you correctly performed step 10. If you encounter the No rows in source stream error,
ensure that you are still sending the email stream that you started at the beginning of this
procedure, and then choose Retrieve rows. You might need to choose Retrieve rows several
times before Amazon Kinesis Analytics captures records.
12. Upon successful retrieval of rows, choose Exit (done).
Next Step
Step 5: Run a SQL Query (p. 187)

186

Step 5: Run a SQL Query

Now that you have created an Amazon Kinesis Analytics application and configured it to use your
Amazon Kinesis Firehose delivery stream as its source, you can query the email sending event data
that the Firehose delivery stream receives.
This topic shows how to run a SQL query on the email sending event data.
Important
This procedure requires that you continue to send a steady stream of emails configured for
event publishing through Amazon SES, as described in Step 3: Send Emails (p. 182).
To run a SQL query in Amazon Kinesis Analytics

1.
Assuming that you have moved on to this procedure after completing the last step (p. 182), go to
the Amazon Kinesis Analytics console top menu and choose your application.
2.
Choose Go to SQL editor.

Amazon Kinesis Analytics attempts to read event data from the Firehose stream. If you encounter
the No rows in source stream error, ensure that you are still sending the email stream you
started at the beginning of this procedure, and then choose Retrieve rows.
3.
In the code editor box, paste the following.

187

CREATE OR REPLACE STREAM "DESTINATION_SQL_STREAM" ("eventType"

VARCHAR(16), "ses_timestamp" timestamp, "messageId" VARCHAR(64), "ses_to"
VARCHAR(64), "ses_configuration_set" VARCHAR(32));
CREATE OR REPLACE PUMP "STREAM_PUMP" AS INSERT INTO
"DESTINATION_SQL_STREAM"
SELECT STREAM "eventType", "ses_timestamp", "messageId", "ses_to",
"ses_configuration_set"
FROM "SOURCE_SQL_STREAM_001"
WHERE "eventType" = 'Send'
4.
Choose Save and run SQL.

After Amazon Kinesis Analytics retrieves and processes incoming records, you see a list of event
records of type "Send".
Next Step
(Optional) Step 6: Save SQL Query Results (p. 188)
(Optional) Step 6: Save SQL Query Results

You can set up your Amazon Kinesis Analytics application to write the output of your SQL queries to an
Amazon Kinesis Firehose delivery stream. To do so, you must create another Firehose delivery stream
because you cannot use the same delivery stream as both the source and destination of an Amazon
Kinesis Analytics application. As with any Firehose delivery stream, you can choose Amazon Simple
Storage Service (Amazon S3), Amazon Elasticsearch Service, or Amazon Redshift as the destination.
The following procedure shows how to configure Amazon Kinesis Analytics to save SQL query results
in JSON format to a Firehose delivery stream that writes the data to Amazon S3. Then you run a SQL
query and access the saved data.

188

To save the results of SQL queries to Amazon S3

1.
Set up a new Firehose stream that uses Amazon S3 as the destination. It is the same procedure
as Step 1: Create a Firehose Delivery Stream (p. 180).
2.
Go to the Amazon Kinesis Analytics console, choose the arrow next to your application, and then
choose Application details.
3.
Choose Connect to a destination.
4.
Choose the Firehose stream you created in step 1, leave the rest of the options at their default
settings, and then choose Save and continue.
In several seconds, you return to the main page of the application.
189

5.
Choose Go to SQL results.
6.
Choose Save and run SQL to re-run the query you ran in Step 5: Run a SQL Query (p. 187).
Amazon Kinesis Analytics attempts to process event data it receives from the Firehose delivery
stream. If you encounter the No rows have arrived yet error, ensure that you are still sending
emails so that Amazon Kinesis Analytics has email sending events to process.
As Amazon Kinesis Analytics processes records, results appear in the Real-time analytics tab.
Amazon Kinesis Analytics automatically saves the results to the Amazon S3 bucket that you
specified when you set up the Firehose delivery stream in step 1.

190

7.
To retrieve the results, go to the Amazon S3 console.
8.
Choose the Amazon S3 bucket that is associated with the Firehose delivery stream that the
Amazon Kinesis Analytics application uses as its destination.
9.
Navigate to the data, which, by default, is organized in a folder hierarchy based on the date the
results are saved to the bucket.
If the bucket is empty, wait a few minutes and try again. It can take several minutes for data to get
from Amazon Kinesis Analytics to your Amazon S3 bucket.
10. Choose a file, and then from the Actions menu, choose Download.
11. Follow the on-screen instructions to download the file to your computer.
12. On your computer, open the file with a text editor. The records are in JSON format, and each
record is contained in curly braces. The following is an example of a file that contains two records.

191

Managing Your Sending Limits
{"eventType":"Send","ses_timestamp":"2016-12-08
18:51:12.092","messageId":"EXAMPLE8dfc6695c-5f048b74ca83-4052-8348-4e7da9669fc3-000000","ses_to":"[\"[email protected]
\" ]","ses_configuration_set":"[\"MyConfigSet\" ]"}
{"eventType":"Send","ses_timestamp":"2016-12-08
18:50:42.181","messageId":"EXAMPLEdfc5f485d40a2543-2cac-4b84-8a8f-30bebdf3820c-000000","ses_to":"[\"[email protected]
\" ]","ses_configuration_set":"[\"MyConfigSet\" ]"}
Managing Your Amazon SES Sending Limits

Your Amazon Simple Email Service (Amazon SES) account has a set of sending limits to regulate the
number of email messages that you can send and the rate at which you can send them. Sending limits
benefit all Amazon SES customers because they help to maintain the trusted relationship between
Amazon SES and Internet service providers (ISPs). Sending limits help you to gradually ramp up
your sending activity and decrease the likelihood that ISPs will block your emails because of sudden,
unexpected spikes in your email sending volume or rate.
The following are Amazon SES sending limits:
Sending QuotaThe maximum number of emails that you can send in a 24-hour period. The
sending quota reflects a rolling time period. Every time you try to send an email, Amazon SES
checks how many emails you sent in the previous 24 hours. As long as the total number of emails
that you have sent is less than your quota, your send request will be accepted and your email will
be sent. If you have already sent your full quota, your send request will be rejected with a throttling
exception. For example, if your sending quota is 50,000, and you sent 15,000 emails in the previous
24 hours, then you can send another 35,000 emails right away. If you have already sent 50,000
emails in the previous 24 hours, you will not be able to send more emails until some of the previous
sending rolls out of its 24-hour window.
Maximum Send RateThe maximum number of emails that Amazon SES can accept from your
account per second. You can exceed this limit for short bursts, but not for a sustained period of time.
Note
The rate at which Amazon SES accepts your messages might be less than the maximum
send rate.
Your Amazon SES sending limits for each AWS region are separate. For information about using
Amazon SES in multiple AWS regions, see Regions and Amazon SES (p. 332).
When you are in the Amazon SES sandbox, your sending quota is 200 messages per 24-hour period
and your maximum sending rate is one message per second. To increase your sending limits, you
need to submit an SES Sending Limits Increase case. For more information, see Moving Out of the
Amazon SES Sandbox (p. 54). After you have moved out of the sandbox and start sending emails, you
can increase your sending limits further by submitting another SES Sending Limits Increase case, as
discussed in Increasing Your Amazon SES Sending Limits (p. 194).
Note
Sending limits are based on recipients rather than on messages. For example, an email
that has 10 recipients counts as 10 against your quota. However, we do not recommend
that you send an email to multiple recipients in one call to SendEmail because if the call to
Amazon SES fails (for example, the request is improperly formatted), the entire email will be
rejected and none of the recipients will get the intended email. We recommend that you call
SendEmail once for every recipient.
To increase your sending limits, see Increasing Your Amazon SES Sending Limits (p. 194).

192

Monitoring Your Sending Limits
For information about the errors your application receives when you reach your sending limits, see
What Happens When You Reach Your Amazon SES Sending Limits (p. 195).
To monitor your sending limits by using the Amazon SES console or the Amazon SES API, see
Monitoring Your Amazon SES Sending Limits (p. 193).
Monitoring Your Amazon SES Sending Limits

You can monitor your sending limits by using the Amazon SES console or through the Amazon SES
API, whether by calling the Query (HTTPS) interface directly or indirectly through an AWS SDK, the
AWS Command Line Interface, or the AWS Tools for Windows PowerShell.
Important
We recommend that you frequently check your sending statistics to ensure that you are
not close to your sending limits. If you are close to your sending limits, see Increasing Your
Amazon SES Sending Limits (p. 194) for information about how to increase them. Don't wait
until you reach your sending limits to consider increasing them.
Monitoring Your Sending Limits Using the Amazon SES

Console
The following procedure shows you how to view your sending limits using the Amazon SES console.
1.
2.
In the Navigation pane, choose Sending Statistics. Your sending limits are shown under Your
Amazon SES Sending Limits.
3.
To update the display, choose Refresh.
Monitoring Your Sending Limits Using the Amazon SES API

The Amazon SES API provides the GetSendQuota action, which returns your sending limits. When
you call GetSendQuota action, you receive the following information:
193

Increasing Your Sending Limits
Number of emails you have sent during the past 24 hours

Sending quota for the current 24-hour period
Maximum send rate
Note
For a complete description of GetSendQuota, go to the Amazon Simple Email Service API
Reference.
Increasing Your Amazon SES Sending Limits

When your account is out of the sandbox, your sending limits will increase if you are sending highquality content and we detect that your utilization is approaching your current limits. Often, the system
will automatically increase your quota before you actually need it, and no further action is needed.
If your existing quota is not adequate for your needs and the system has not automatically increased
your quota, you can open an SES Sending Limits Increase case in Support Center.
For a list of the information that you will need when you open the case, see Opening an SES Sending
Limits Increase Case (p. 194).
Important
Plan ahead. Be aware of your sending limits and try to stay within them. If you anticipate
needing a higher quota than the system has allocated automatically, please open an SES
Sending Limits Increase case well prior to the date that you need the higher quota.
Important
If you anticipate needing to send more than one million emails per day, you must open an
SES Sending Limits Increase case.
For Amazon SES to increase your quota, make sure that you use the following guidelines:
Send high-quality contentSend content that recipients want and expect. For recommendations
about how to send high-quality emails, see the Amazon Simple Email Service Email Sending Best
Practices whitepaper.
Send real production contentSend your actual production email. This enables Amazon SES to
accurately evaluate your sending patterns, and verify that you are sending high-quality content.
Send near your current quotaIf your volume stays close to your quota without exceeding it,
Amazon SES can detect this usage pattern and automatically increase your quota.
Have low bounce and complaint ratesTry to minimize the numbers of bounces and complaints.
Having high numbers of bounces and complaints can adversely affect your sending limits.
Important
Test emails that you send to your own email addresses may adversely affect your bounce
and complaint metrics, or appear as low-quality content to our filters. Whenever possible, use
the Amazon SES mailbox simulator to test your system. Emails that are sent to the mailbox
simulator do not count toward your sending metrics or your bounce and complaint rates. For
more information, see Testing Amazon SES Email Sending (p. 224).
For information about opening an SES Sending Limits Increase case, see Opening an SES Sending
Limits Increase Case (p. 194).
Opening an SES Sending Limits Increase Case

To apply for higher sending limits for Amazon SES, you need to open a case in Support Center by
using the following instructions.
194

What Happens When You Reach Your Sending Limits
To request higher sending limits

1.
2.
Log into the AWS Management Console.

Go to https://aws.amazon.com/ses/extendedaccessrequest/. Alternatively, you can go to AWS
Support Center, choose Create Case, choose Service Limit Increase, and then select SES
Sending Limits as the limit type.
3.
In the form, provide the following information:

Region: Select the AWS region for which you are requesting a sending limit increase. Note that
your Amazon SES sandbox status and sending limits are separate for each AWS region. For
more information, see Regions and Amazon SES (p. 332).
Limit: Select Desired Daily Sending Quota or Desired Maximum Send Rate. Sending limits are
described in Managing Your Amazon SES Sending Limits (p. 192).
Note
The rate at which Amazon SES accepts your messages might be less than the
maximum send rate.
New limit value: Enter the amount you are requesting. Be sure to only request the amount you
think you'll need. Keep in mind that you are not guaranteed to receive the amount you request,
and the higher the limit you request, the more justification you will need to be considered for that
amount.
Mail type Select Transactional, System Notifications, Subscription, Marketing, or Other.
Website URL Provide a link to your website. Although it isn't required, we highly recommend
that you provide one if you have it, because it helps us evaluate your request.
My email-sending complies with the AWS Service Terms and AWS Acceptable Use Policy
(AUP) Select Yes or No.
I only send to recipients who have specifically requested my mail Select Yes or No.
For tips on how to send high-quality mail and keep your recipient list clean, see Obtaining and
Maintaining Your Recipient List (p. 228) and the Amazon Simple Email Service Email Sending
Best Practices whitepaper.
I have a process to handle bounces and complaints. Select Yes or No. For information
on how to monitor and handle bounces and complaints, see Processing Bounces and
Use Case Description Explain your situation in as much detail as possible. For example,
describe the type of emails you are sending and how email-sending fits into your business.
The more information you can provide that indicates that you are sending high-quality emails to
recipients who want and expect it, the more likely we are to approve your request. The higher
the limit value you are requesting, the more detail you should provide.
We will respond to the case after reviewing your request. Please allow one business day for
processing.
What Happens When You Reach Your Amazon

SES Sending Limits
If you attempt to send an email after you have reached your sending quota or maximum send rate,
you will encounter a throttling error and the email will be dropped. The way you observe the error
depends on whether you are calling the Amazon SES API directly, or accessing Amazon SES through
the SMTP interface. The following sections describe both scenarios.
Note
You can send an email to multiple recipients as long as you have at least one email left before
you reach your sending rate limit. Then, you have to wait until you build up the corresponding
amount of sending rate quota before you can send again. For example, if your sending
195

Using Sending Authorization
rate limit is one email per second, then you will be able to send an email with 10 recipients
once every 10 seconds. However, we do not recommend that you send an email to multiple
recipients in one call to SendEmail.
For a technique to use when you reach your maximum send rate, see How to handle a "Throttling
Maximum sending rate exceeded" error on the Amazon SES blog.
Reaching Sending Limits with the Amazon SES API

If your application attempts to send an email beyond your sending limits, the application will encounter
a Throttling error with one of the following messages:
Daily message quota exceeded
Maximum sending rate exceeded
A throttling error might occur because of incorrect predictions of email volume, or bursts of
transactional email that are higher than expected. To handle a throttling error, program your application
to wait for a random interval of between 0 and 10 minutes, and then retry the send request.
Reaching Sending Limits with SMTP

If you reach your sending limits when you are accessing Amazon SES through the SMTP interface,
your SMTP client will receive one of the following errors:
454 Throttling failure: Maximum sending rate exceeded
454 Throttling failure: Daily message quota exceeded
However, SMTP clients handle these errors in various ways. For example, if you use Microsoft Outlook
as your email client, and you attempt to send past your sending quota, you get a Send/Receive error
that displays the following text in the status pane at the bottom of the Outlook client window:
Task '[email protected] Sending' reported error (0x800CCC7F): 'Establishing
an encrypted connection to your outgoing (SMTP) server failed. If this
problem continues, contact your server administrator or Internet service
provider (ISP). The server responded: 454 Throttling failure: Daily message
quota exceeded.'
The way in which these errors are handled depends on the SMTP client that you use; some SMTP
clients may not display the error code at all.
Using Sending Authorization with Amazon SES

Amazon Simple Email Service (Amazon SES) enables you to authorize other users to send emails
from your identities on your behalf. This feature, called sending authorization, lets you maintain control
over your identities so that you can change or revoke the permissions at any time. For example, as a
business owner, you might use sending authorization to enable an email marketing company to send
marketing emails from an email address under your domain name.
If you want to authorize someone to send emails on your behalf, then you are an identity owner. If you
are an identity owner, we recommend that you read the following sections:
Overview of Sending Authorization (p. 197)
Sending Authorization Policies (p. 199)
196

Overview of Sending Authorization
Sending Authorization Policy Examples (p. 203)

Identity Owner Tasks (p. 207)
If you have been authorized to send emails on behalf of someone else, then you are a delegate
sender. If you are a delegate sender, we recommend that you read the following sections:
Overview of Sending Authorization (p. 197)
Delegate Sender Tasks (p. 213)
Note
You can also control access to Amazon SES by using IAM policies. IAM policies constrain
what individual IAM users can do, while sending authorization policies constrain how individual
verified identities can be used. Further, only sending authorization policies can grant crossaccount access. For more information about using IAM policies with Amazon SES, see
Controlling Access to Amazon SES (p. 307).
Overview of Amazon SES Sending Authorization

This topic provides an overview of the sending authorization process and then explains how Amazon
SES email-sending features, such as sending limits and notifications, work with sending authorization.
We use the following terminology:
An identity is an email address or domain that Amazon SES users use to send email.
An identity owner is an Amazon SES user who has verified ownership of an identity by using the
procedure described in Verifying Email Addresses and Domains (p. 39).
A delegate sender is an entity that is authorized to send emails from an identity it does not own. An
AWS account, an AWS Identity and Access Management (IAM) user, or an AWS service can have
this cross-account authority.
A sending authorization policy is a document that you attach to an identity to specify who may send
for that identity and under which conditions.
An Amazon Resource Name (ARN) is a standardized way to uniquely identify an AWS resource
across all AWS services. In the case of sending authorization, the resource is the identity that
the identity owner wants the delegate sender to use. An example of an ARN is arn:aws:ses:uswest-2:123456789012:identity/example.com.
Sending Authorization Process

Sending authorization is based on sending authorization policies. If you want to enable a delegate
sender to send on your behalf, you create a sending authorization policy and associate the policy to
your identity by using the Amazon SES console or the Amazon SES API. When the delegate sender
attempts to send an email through Amazon SES on your behalf, the delegate sender passes the ARN
of your identity in the request or in the header of the email.
When Amazon SES receives the request to send the email, it checks your identity's policy (if present)
to determine if you have authorized the delegate sender to send on the identity's behalf. If the delegate
sender is authorized, Amazon SES accepts the email; otherwise, Amazon SES returns an error
message.
197

Overview of Sending Authorization
The following diagram shows the high-level relationship between sending authorization concepts:
Step by step, the sending authorization process is as follows:

1. The identity owner verifies an identity with Amazon SES by using the Amazon SES console or the
Amazon SES API. For information about the verification procedure, see Verifying Email Addresses
and Domains (p. 39).
2. The delegate sender gives the identity owner the AWS account ID, IAM user ARN, or AWS service
name of the entity that will do the sending.
3. The identity owner creates a sending authorization policy and attaches the policy to the identity by
using the Amazon SES console or the Amazon SES API.
4. The identity owner gives the delegate sender the ARN of the identity so that the delegate sender
can provide the ARN to Amazon SES at the time of email sending.
5. The identity owner and delegate sender configure bounce, complaint, and delivery notifications
separately by using either the Amazon SES console or the Amazon SES API. For information about
setting up notifications, see Monitoring Using Amazon SES Notifications (p. 106).
6. The delegate sender attempts to send an email through Amazon SES on behalf of the identity
owner by passing the ARN of the identity owner's identity in the request or in the header of the
email. The delegate sender can send the email by using either the Amazon SES SMTP interface
or the Amazon SES API. Upon receiving the request, Amazon SES examines any policies that
are attached to the identity, and accepts the email if the delegate sender is authorized to use the
specified "From" address and "Return Path" address; otherwise, Amazon SES returns an error and
does not accept the message.
7. To deauthorize the delegate sender, the identity owner simply edits the sending authorization policy
or deletes the policy entirely. Either action can be performed by using the Amazon SES console or
the Amazon SES API.
For more information about how the identity owner or delegate sender perform those tasks, see Identity
Owner Tasks (p. 207) or Delegate Sender Tasks (p. 213), respectively.
Attribution of Email-Sending Features

It is important to understand the role of the delegate sender and the identity owner with respect to
Amazon SES email-sending features such as daily sending quota, bounces and complaints, DKIM
signing, feedback forwarding, and so on. The attribution is the following:
Sending limitsThe emails count toward the delegate sender's daily sending quota.
198

Sending Authorization Policies
Bounces and complaintsBounces and complaints count toward the delegate sender's bounce
and complaint metrics, and therefore the delegate sender's reputation as a sender.
DKIM signingIf the identity owner has enabled Easy DKIM signing for an identity, all email sent
from that identity will be DKIM-signed, including email sent by a delegate sender. Only the identity
owner has control of whether the emails are DKIM-signed.
NotificationsThe identity owner and the delegate sender set up their own Amazon SNS
notifications for bounces, complaints, and deliveries independently. However, feedback forwarding
by email is only available to the identity owner.
VerificationIdentity owners are responsible for following the procedure in Verifying Email
Addresses and Domains (p. 39) to verify that they own the email addresses and domains that
they are authorizing delegate senders to use. Delegate senders do not need to verify any email
addresses or domains specifically for sending authorization.
AWS regionsThe delegate sender must send the emails from the AWS region in which the
identity owner's identity is verified. The sending authorization policy that gives permission to the
delegate sender must be attached to the identity in that region.
Amazon SES Sending Authorization Policies

To enable another AWS account, Identity Access and Management (IAM) user, or AWS service to
send email through Amazon SES on your behalf, you create a sending authorization policy, which is
a JSON document that you attach to an identity that you own. The policy explicitly lists who you are
allowing to send for that identity, and under which conditions. All senders but you and the entities you
explicitly grant permissions to in the policies are denied. An identity can have no policy, one policy, or
multiple policies attached to it. You can also have one policy with multiple statements to achieve the
effect of multiple policies.
Policies can be very simple or very detailed for fine-grained control. For example, if you owned
example.com, you could write a simple policy to grant AWS ID 123456789012 permission to send from
that domain. A more detailed policy could specify that AWS ID 123456789012 can send email only
from [email protected] and only within a specified date range.
Amazon SES sending authorization policies apply to email-sending APIs (SendEmail and
SendRawEmail) only. They do not enable a user to access your AWS account in any other way.
Policy Structure
Each sending authorization policy is a JSON document that is attached to an identity. A policy includes:
Optional policy-wide information at the top of the document.
One or more individual statements, each of which describes one set of permissions.
Each statement includes the core information about a single permission. If a policy includes multiple
statements, Amazon SES applies a logical OR across the statements at evaluation time. Similarly, if
an identity has multiple policies attached to it, Amazon SES applies a logical OR across the policies at
evaluation time.
The following example shows a simple policy that allows AWS ID 123456789012 to send email from
the identity example.com (which is under account 888888888888) but only if the "From" address is
marketing+.*@example.com, where .* is any string that the sender wants to add after marketing+.
{
"Id": "SampleAuthorizationPolicy",
"Version": "2012-10-17",
"Statement": [
{
199

"Sid": "AuthorizeMarketer",
"Effect": "Allow",
"Resource": "arn:aws:ses:us-east-1:888888888888:identity/example.com",
"Principal": {"AWS": ["123456789012"]},
"Action": ["SES:SendEmail", "SES:SendRawEmail"],
"Condition": {
"StringLike": {
"ses:FromAddress": "marketing+.*@example.com"
}
}
}
]
}
You can find more sending authorization policy examples at Sending Authorization Policy
Examples (p. 203).
Policy Elements
This section describes the elements contained in sending authorization policies. First we describe
policy-wide elements, and then we describe elements that apply only to the statement in which they are
included. We follow with a discussion of how to add conditions to your statements.
For specific information about the syntax of the elements, see Grammar of the IAM Policy Language in
the IAM User Guide.
Policy-Wide
There are two policy-wide elements: Id and Version. The following table provides information about
these elements.
Name
Description
Required
Valid Values
Id
Uniquely identifies the policy.
No.
Any string
Version
Specifies the policy access

language version.
No, but
as a best
practice, we
recommend
that you
include this
field with
a value of
"2012-10-17".
Any string
Statements
Sending authorization policies require at least one statement. Each statement can include the elements
described in the following table.
Name
Description
Required
Valid Values
Sid
Uniquely identifies the

statement.
No.
Any string.
Effect
Specifies the result that

you want the policy
No, although a
statement without an
effect is useless.
"Allow" or "Deny".

200

Name
Description
Required
Valid Values
statement to return at
evaluation time.
Resource
Specifies the identity

to which the policy
applies. This is the
email address or
domain that the identity
owner is authorizing
the delegate sender to
use.
Yes.
An identity's ARN,
as specified in the
Amazon SES console.
Principal
Specifies the AWS

account, IAM user,
or AWS service
that receives the
permission in the
statement.
Yes.
A valid AWS account

ID, IAM user ARN, or
AWS service. AWS
account IDs and
IAM user ARNs are
specified using "AWS"
(for example, "AWS":
["123456789012"]
or "AWS":
["arn:aws:iam::123456789012:root
AWS service names
are specified using
"Service" (for
example, "Service":
["cognitoidp.amazonaws.com"]).
For examples of the
format of IAM user
ARNs, see the AWS
General Reference.
Action
Specifies the emailsending action to which

the statement applies.
Yes.
"ses:SendEmail",
"ses:SendRawEmail" (one
or both). If you use
the custom policy
editor, you can also
set the action to
"ses:*" to encompass
both APIs. If your
sender will access
Amazon SES through
the SMTP interface,
you must select
"ses:SendRawEmail"
at a minimum (or use
"ses:*").
Condition
Specifies any
restrictions or details
about the permission.
No.
See the information

about conditions
following this table.

201

Conditions
A condition is any restriction about the permission in the statement. The part of the statement that
specifies the conditions can be the most detailed of all the parts. A key is the specific characteristic that
is the basis for access restriction, such as the date and time of the request.
You use both conditions and keys together to express the restriction. For example, if you want to
restrict the delegate sender from making requests to Amazon SES on your behalf after July 30, 2015,
you use the condition called DateLessThan. You use the key called aws:CurrentTime and set it to
the value 2015-07-30T00:00:00Z.
You can use any of the AWS-wide keys listed at Available Keys in the IAM User Guide, or you can use
one of the following keys specific to Amazon SES:
Condition Key
Description
ses:Recipients
Restricts the recipient addresses, which include the To:,

"CC", and "BCC" addresses.
ses:FromAddress
Restricts the "From" address.
ses:FromDisplayName
Restricts the contents of the string that is used as

the "From" display name (sometimes called "friendly
from"). For example, the display name of "John Doe
<[email protected]>" is John Doe.
ses:FeedbackAddress
Restricts the "Return Path" address, which is the address

where bounce and complaints can be sent to you by
email feedback forwarding. For information about email
feedback forwarding, see Amazon SES Notifications
Through Email (p. 107).
It is common to use the StringEquals and StringLike conditions with the Amazon SES keys.
These conditions are for case-sensitive string matching. For StringLike, the values can include a
multi-character match wildcard (*) or a single-character match wildcard (?) anywhere in the string.
For example, the following condition specifies that the delegate sender can only send from a "From"
address that starts with invoicing and ends with example.com:
"Condition": {
"StringLike": {
"ses:FromAddress": "invoicing+.*@example.com"
}
}
Note
When you want to disallow access to an email address, use wildcards to ensure that you
are completely preventing access to all forms of that address. For example, to disallow
sending from [email protected], you can prevent access to alternatives such as
"admin"@example.com and [email protected] by specifying the following condition:
"Condition": {
"StringNotLike": {
"ses:FromAddress": "*admin*.example.com"
}
}
For more information about how to specify conditions, see Condition in the IAM User Guide.
202

Sending Authorization Policy Examples
Policy Requirements
Each policy must adhere to the following requirements:
Each policy must include at least one statement.
Each policy must include at least one valid principal.
Each policy must specify one resource, and that resource must be the ARN of the identity to which
the policy is attached.
Identity owners can associate up to 20 policies with each unique identity.
Policies must not exceed 4 kilobytes (KB).
Policy names cannot exceed 64 characters and can only include alphanumeric characters, dashes,
and underscores.
Amazon SES Sending Authorization Policy

Examples
Sending authorization enables you to specify the fine-grained conditions under which you allow
delegate senders to send on your behalf. The following examples show you how to write policies to
control different aspects of sending:
Specifying the Delegate Sender (p. 203)
Restricting the "From" Address (p. 204)
Restricting the Destination of Bounce and Complaint Feedback (p. 205)
Restricting the Time Period of Sending (p. 205)
Restricting the Email-Sending Action (p. 206)
Restricting the Display Name of the Email Sender (p. 206)
Using Multiple Statements (p. 207)
Specifying the Delegate Sender

The principal, which is the entity to which you are granting permission, can be an AWS account, an
AWS Identity and Access Management (IAM) user, or an AWS service. The following example policy
grants AWS account ID 123456789012 permission to send from identity example.com.
{
"Id": "ExampleAuthorizationPolicy",
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AuthorizeAccount",
"Effect": "Allow",
"Principal": {"AWS": ["123456789012"]},
"Action": ["SES:SendEmail", "SES:SendRawEmail"]
}
]
}
The following example policy grants permission to two IAM users to send from identity example.com.
IAM users are specified by their Amazon Resource Name (ARN).
203

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AuthorizeIAMUser",
"Effect": "Allow",
"Principal": {"AWS": [
"arn:aws:iam::111122223333:user/John",
"arn:aws:iam::444455556666:user/Jane"
]},
}
]
}
The following example policy grants permission to Amazon Cognito to send from identity example.com.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AuthorizeService",
"Effect": "Allow",
"Principal": {"Service": ["cognito-idp.amazonaws.com"]},
}
]
}
Restricting the "From" Address

Even if you have verified a whole domain, you might want to restrict the "From" address so that the
delegate sender can send from a specified email address only. To restrict the "From" address, you
set a condition on the key called ses:FromAddress. The following policy enables AWS account ID
123456789012 to send from identity example.com, but only from email address [email protected].
{
"Id": "ExamplePolicy",
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AuthorizeFromAddress",
"Effect": "Allow",
"Principal": {"AWS": ["123456789012"]},
"Condition": {
"StringEquals": {
"ses:FromAddress": "[email protected]"
}
}
}
204

]
}
Restricting the Destination of Bounce and Complaint Feedback

If a delegate sender is sending on your behalf and you want to ensure that bounce and complaint
notifications are forwarded to you by email, you need to do two things: you must enable email
feedback forwarding for the identity by using the procedure in Amazon SES Notifications Through
Email (p. 107), and you must restrict the "Return Path" of the emails to an email address that you
own by setting a condition on the ses:FeedbackAddress key.
The following sending authorization policy enables AWS account ID 123456789012 to send from the
identity example.com as long as the "Return Path" of the email is set to [email protected].
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ControlReturnPath",
"Effect": "Allow",
"Principal": {"AWS": ["123456789012"]},
"Condition": {
"StringEquals": {
"ses:FeedbackAddress": "[email protected]"
}
}
}
]
}
Restricting the Time Period of Sending

You might want to constrain the date and time during which the delegate sender can send on your
behalf. For example, if your email campaign is scheduled for the month of September 2015, the
following policy enables the delegate sender to send emails on your behalf during that month only.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ControlTimePeriod",
"Effect": "Allow",
"Principal": {"AWS": ["123456789012"]},
"Condition": {
"DateGreaterThan": {
"aws:CurrentTime":"2015-08-31T12:00Z"
},
"DateLessThan": {
}
}
205

}
]
}
Restricting the Email-Sending Action

There are two actions that senders can use to send an email with Amazon SES: SendEmail and
SendRawEmail, depending on how much control the sender wants over the format of the email.
Sending authorization policies enable you to restrict the delegate sender to one of those two actions.
However, many identity owners leave the details of the email-sending calls up to the delegate sender
by enabling both actions in their policies.
Note
If you want to enable the delegate sender to access Amazon SES through the SMTP
interface, you must choose SendRawEmail at a minimum.
If your use case is such that you want to restrict the action, you can do so by including only one of
the actions in your sending authorization policy. The following example shows you how to restrict the
action to SendRawEmail.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ControlAction",
"Effect": "Allow",
"Principal": {"AWS": ["123456789012"]},
"Action": ["SES:SendRawEmail"]
}
]
}
Restricting the Display Name of the Email Sender

Some email clients display the "friendly" name of the email sender (if the email header
provides it), rather than the actual "From" address. For example, the display name of "John
Doe <[email protected]>" is John Doe. For instance, you might send emails from
[email protected], but you prefer that recipients see that the email is from Marketing rather than
from [email protected]. The following policy enables AWS account ID 123456789012 to send from
identity example.com, but only if the display name of the "From" address includes Marketing.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AuthorizeFromAddress",
"Effect": "Allow",
"Principal": {"AWS": ["123456789012"]},
"Condition": {
"StringLike": {
"ses:FromDisplayName": "Marketing"
}
206

Identity Owner Tasks
}
}
]
}
Using Multiple Statements

You can use multiple statements for fine-grained control. The following example policy has
two statements. The first statement authorizes two individual AWS accounts to send from
[email protected] using the SendEmail API as long as the "From" address and the feedback
address are both under the domain example.com. The second statement authorizes an IAM user to
send email from [email protected] as long as the email is sent to an email address under the
domain example.com.
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "AuthorizeAWS",
"Effect": "Allow",
"Resource": "arn:aws:ses:us-east-1:999999999999:identity/
[email protected]",
"Principal": {
"AWS": ["111111111111", "222222222222"]
},
"Condition": {
"StringLike": {
"ses:FromAddress": "*@example.com",
"ses:FeedbackAddress": "*@example.com"
}
}
}, {
"Sid": "AuthorizeInternal",
"Effect": "Allow",
"Resource": "arn:aws:ses:us-east-1:999999999999:identity/
[email protected]",
"Principal": {
"AWS": "arn:aws:iam::333333333333:user/Jane"
},
"Condition": {
"ForAllValues:StringLike": {
"ses:Recipients": "*@example.com"
}
}
}]
}
Identity Owner Tasks for Amazon SES Sending

Authorization
This section describes all of your responsibilities as an identity owner. Your main responsibility is to
create a sending authorization policy that grants permission to a delegate sender to send on your
behalf, and to attach that policy to the identity that you want the delegate sender to use. There are also
some small setup tasks that you need to perform.
207

To see where these tasks fit into the overall sending authorization process, see Overview of Sending
Verifying an Identity (p. 208)
Setting Up Notifications (p. 208)
Getting Information from the Delegate Sender (p. 208)
Creating a Policy (p. 208)
Providing the Delegate Sender with the Identity Information (p. 211)
Managing Your Policies (p. 211)
Verifying an Identity for Amazon SES Sending Authorization

As with any Amazon SES sender, you must first prove that you own the email address or domain from
which your emails will be sent, even though the delegate sender will send the emails. The verification
procedure is described in Verifying Email Addresses and Domains (p. 39).
You can confirm that your email address or domain is verified by looking at its status
in the Verified Senders list in the Amazon SES console or by using the Amazon SES
GetIdentityVerificationAttributes API.
Setting Up Identity Owner Notifications for Amazon SES

Sending Authorization
When a delegate sender sends emails on your behalf, bounces and complaints that those emails
generate count toward the delegate sender's bounce and complaint metrics rather than your own.
However, if you want to be informed of these email-sending outcomes, you can set up notifications by
email or by Amazon SNS notifications just as you would for any other identity. Follow the procedures in
Monitoring Using Amazon SES Notifications (p. 106).
Delegate senders can set up their own Amazon SNS notifications for the identities that you have
authorized them to use, although only you, the identity owner, can control whether feedback can be
directly forwarded to your identity via email.
Getting Information from the Delegate Sender for Amazon SES

Your sending authorization policy must specify at least one principal, which is the entity to which you
are granting access. For Amazon SES sending authorization policies, the principal can be an AWS
account, an AWS Identity and Access Management (IAM) user, or an AWS service.
The type of principal you choose depends on your preference, but if you want the finest grain control,
ask the delegate sender to set up an IAM user so that only one delegate sender can send for you
rather than any user in the delegate sender's AWS account. The delegate sender can find information
about setting up an IAM user in Creating an IAM User in Your AWS Account in the IAM User Guide.
After you have decided whether you want to grant access to an AWS account, an IAM user, or an
AWS service, ask the delegate sender for the AWS account ID or the IAM user's Amazon Resource
Name (ARN) so that you can include it in your sending authorization policy. You can refer your
delegate sender to the instructions for finding this information in Providing Information to the Identity
Owner (p. 213). If your delegate sender is an AWS service, the service's documentation should
provide the service name to use in the policy.
Creating a Policy for Amazon SES Sending Authorization

To authorize a delegate sender to send emails for one of your identities, you create a sending
authorization policy and then attach that policy to the identity. Identities can have zero policies, one
208

policy, or multiple policies. However, each policy must be associated with an identity, and one identity
only.
Important
Policies attached to email address identities override policies attached to the
corresponding domain identities. For example, say that you have verified example.com
and [email protected]. If you create a policy for example.com that disallows a delegate
sender, and you create a policy for [email protected] that allows that delegate sender,
the delegate sender will be able to send from [email protected] if they specify the ARN of
[email protected] in the request to send the email.
You can create a sending authorization policy in the following ways:
Using the Policy Generator You can create a simple policy by using the Policy Generator in
the Amazon SES console. In addition to specifying who can send the emails, you can constrain
the email-sending with conditions based on the time and date range in which emails can be sent,
the "From" address, the "From" display name, the address to which bounces and complaints are
sent, the recipient addresses, and the source IP. You might also want to use the Policy Generator to
create the structure of a simple policy and then customize it later by editing the policy.
Creating a Custom PolicyIf you want to include more advanced conditions or use an AWS
service as the principal, you can create a custom policy and attach it to the identity by using the
Amazon SES console or the Amazon SES API.
This topic describes both methods.
Using the Policy Generator

You can use the Policy Generator to create a simple authorization policy by using the following
procedure.
To create a policy by using the Policy Generator

1.
2.
In the left navigation pane, under Identity Management, choose either Email Addresses or
Domains.
3.
In the resource list, choose the identity for which you want to create a policy.
4.
In the details pane, expand Identity Policies, choose Create Policy, and then choose Policy
Generator.
5.
In the wizard, create a policy statement by choosing values for the following fields. You can find
information about these options in Sending Authorization Policies (p. 199).
EffectIf you want to grant access, choose Allow; otherwise, choose Deny.
PrincipalsEnter either the 12-digit AWS account ID or the ARN of an IAM user that you are
allowing or denying access, and then choose Add. You can add more principals by repeating
this step. An example of an AWS account ID is 123456789012 and an example of an IAM user
ARN is arn:aws:iam::123456789012:user/John.
Note
The policy generator wizard does not currently support AWS service principals. To add
an AWS service principal, you must either create a custom policy (p. 211) or use the
policy generator to add an AWS account or IAM user principal, and then edit (p. 212)
the policy.
ActionsChoose the email-sending access to which this policy applies. Typically, identity
owners choose both options to give the delegate sender the freedom to choose how to
implement the email sending. For more information, see Statements (p. 200).
209

6.
(Optional) If you want to add restrictions to the policy, choose Add Conditions, and then choose
the following information:
KeyThis is the characteristic that is the basis for access restriction. The Policy Generator
lets you choose an Amazon SES-specific key or one of a few commonly used AWS-wide keys
(current time and source IP). For details, see Conditions (p. 202). If you want to specify the
more advanced AWS-wide keys listed in Available Keys, you can edit the policy after you create
it.
ConditionThis is the type of condition that you want to specify. For example, there are string
conditions, numeric conditions, date and time conditions, and so on. For a list of conditions, see
Condition Types in the IAM User Guide.
ValueThis is the value that will be tested against the condition. For examples, see the policies
in Sending Authorization Policy Examples (p. 203).
After you choose the key, condition, and value, choose Add Condition. The condition appears in
the Conditions list. You can remove conditions by choosing Remove next to a condition in the
list. You can add another condition by choosing Add Conditions again.
7.
When you are finished adding conditions (if any), choose Add Statement. The statement appears
in the Statements list, where you can choose to edit or remove it. You can add additional
statements by repeating steps 5-7.
210

8.
When you are finished adding statements, choose Next.
9.
In the Edit Policy dialog box, review your policy, edit it if needed, and then choose Apply Policy.
Creating a Custom Policy

If you want to create a custom policy and attach it to an identity, you have the following options:
Using the Amazon SES APICreate a policy in a text editor and then attach the policy to the
identity by using the PutIdentityPolicy API described in the Amazon Simple Email Service API
Reference.
Using the Amazon SES consoleCreate a policy in a text editor and attach it to an identity
by pasting it into the Custom Policy editor in the Amazon SES console. The following procedure
describes this method.
To create a custom policy by using the Custom Policy editor

1.
2.
Domains.
3.
In the resource list, choose the identity for which you want to create a policy.
4.
In the details pane, expand Identity Policies, choose Create Policy, and then choose Custom
Policy.
5.
In the Edit Policy pane, paste the text of your policy and edit it as necessary.
6.
Choose Apply Policy.
Providing the Delegate Sender with the Identity Information for

Amazon SES Sending Authorization
After you create your sending authorization policy and attach it to your identity, you need to give the
delegate sender the Amazon Resource Name (ARN) of the identity. The delegate sender will pass that
ARN to Amazon SES in the email-sending operation or in the header of the email.
You can use the following procedure to find your identity's ARN.
To find the ARN of an identity

1.
2.
Domains.
3.
In the resource list, choose the identity to which you attached the sending authorization policy.
4.
At the top of the details pane, after Identity ARN, you will see the identity's ARN. It will look similar
to arn:aws:ses:us-east-1:123456789012:identity/[email protected]. Copy the entire ARN and
give it to your delegate sender.
Managing Your Policies for Amazon SES Sending

Authorization
In addition to creating and attaching policies to identities as explained in Creating a Policy (p. 208),
you can edit, remove, list, and retrieve an identity's policies, as described in the following sections.
211

Note
To revoke permissions, you can either edit a policy or remove it.
Editing a Policy
The easiest way to edit a policy is to use the Amazon SES console. If you want to use the Amazon
SES API instead, you can use the GetIdentityPolicies API to retrieve the policy, edit the policy
by using a text editor, and then use the PutIdentityPolicy API to overwrite the older policy. These
actions are explained in the Amazon Simple Email Service API Reference.
The following procedure shows you how to edit a policy by using the Amazon SES console.
To edit a policy by using the Amazon SES console

1.
2.
Domains.
3.
In the resource list, choose the identity that is associated with the policy that you want to edit.
4.
In the details pane, expand Identity Policies, find the policy that you want in the Identity Policy
list, and then choose Edit Policy.
5.
In the Edit Policy pane, edit the policy, and then choose Apply Policy.
6.
In the Overwrite Existing Policy dialog box, choose Overwrite.
Removing a Policy
To revoke permissions at any time, you can simply remove the policy. You can remove a policy by
using the DeleteIdentityPolicy API, as explained in the Amazon Simple Email Service API
Reference, or you can use the Amazon SES console, as described in the following procedure.
Important
After you remove a policy, there is no way to get it back. We recommend that you back up the
policy by copying and pasting it into a text file before you remove the policy.
To remove a policy by using the Amazon SES console

1.
2.
Domains.
3.
In the resource list, choose the identity that is associated with the policy that you want to remove.
4.
In the details pane, expand Identity Policies, find the policy that you want to remove, and then
choose Remove Policy.
5.
In the Remove Policy dialog box, choose Yes, Remove Policy.
Listing and Retrieving Policies

You can list the policies that are attached to an identity by using the ListIdentityPolicies API
as explained in the Amazon Simple Email Service API Reference. You can also retrieve the policies
themselves by using the GetIdentityPolicies API.
You can also jointly perform these operations in the Amazon SES console as described in the following
procedure.
212

Delegate Sender Tasks
To list and show the policies attached to an identity by using the Amazon SES console
1.
2.
Domains.
3.
In the resource list, choose the identity for which you want to see policies.
4.
In the details pane, expand Identity Policies. You will see a list of policies.
5.
Find the policy that you want to view in the Identity Policy list, and then choose Show Policy.
6.
After you are finished viewing the policy, close the Show Policy dialog box.
Delegate Sender Tasks for Amazon SES Sending

Authorization
As a delegate sender, you are sending cross-account emails. This means that you are sending emails
on behalf of an identity that you do not own, but are authorized to use. Even though you are sending on
the identity owner's behalf, bounces and complaints count toward your bounce and complaint metrics,
and the emails count toward your sending quota. You are also responsible for requesting any sending
limit increases that you might need to send the identity owner's emails.
Delegate senders are responsible for the tasks described in this section. To see where these tasks fit
into the overall sending authorization process, see Overview of Sending Authorization (p. 197).
Providing Information to the Identity Owner (p. 213)
Using Delegate Sender Notifications (p. 214)
Sending Emails for the Identity Owner (p. 217)
Providing Information to the Identity Owner for Amazon SES

As a delegate sender, you need to give your AWS account ID or the Amazon Resource Name (ARN)
of the AWS Identity and Access Management (IAM) user who will do the sending to the identity owner.
You can find this information by using the following procedures.
To find the ARN of an IAM user

1.
Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2.
In the left navigation pane, choose Users.
3.
In the resource list, choose the user name. The Summary section displays the ARN. The ARN will
look something like arn:aws:iam::123456789012:user/John.
To find your AWS account ID

1.
You can go directly to https://console.aws.amazon.com/billing/home?#/account. Alternatively, you

can navigate to it by going to the AWS Management Console at https://console.aws.amazon.com/.
In the top bar, select your name, and then select My Account.
2.
Expand Account Settings. The AWS account ID is at the top of this section.

213

Using Delegate Sender Notifications for Amazon SES Sending

Authorization
As a delegate sender, you can set up Amazon Simple Notification Service (Amazon SNS) notifications
to inform you of bounces, complaints, and deliveries. The format and content of these notifications
are described in Amazon SES Notifications Through Amazon SNS (p. 109). Only the identity owner
has the option to receive notifications by email feedback forwarding as described in Amazon SES
Notifications Through Email (p. 107).
Important
As the delegate sender, bounces and complaints count toward your bounce and complaint
metrics. High bounce and complaint rates put your account at risk of being shut down, so
ensure that you set up notifications and have a process in place to monitor the notifications
and remove recipient addresses that have bounced or complained from your mailing list. For
more information, see Processing Bounces and Complaints (p. 228).
You will be charged standard Amazon SNS rates for bounce, complaint, and delivery notifications. For
more information, see the Amazon SNS pricing page.
The following sections show you how to manage cross-account identity notifications.
Setting Up a Notification Configuration (p. 214)
Editing a Notification Configuration (p. 215)
Viewing a Notification Configuration (p. 215)
Removing a Notification Configuration (p. 216)
Setting Up an Amazon SES Cross-Account Identity Notification Configuration

Before you set up notifications, you need to know the Amazon Resource Name (ARN) of the identity
that the identity owner has authorized you to use, and for which you want to configure notifications.
For example, the ARN for identity [email protected] would look similar to arn:aws:ses:useast-1:123456789012:identity/[email protected]. If the identity owner has not given you the
identity's ARN, refer them to the procedure in Providing the Delegate Sender with the Identity
Information (p. 211).
The easiest way to configure notifications is to use the Amazon SES console. If you want to use the
Amazon SES API instead, you can use the SetIdentityNotificationTopic API and pass the
identity's ARN as the Identity parameter. This action is explained in the Amazon Simple Email
Service API Reference. The following procedure shows you how to set up notifications by using the
Amazon SES console.
To set up Amazon SNS bounce, complaint, and/or delivery notifications by using the
Amazon SES console
1.
2.
In the left navigation pane, choose Cross-Account Notifications.
3.
Choose Add Notification Config.
4.
In the Edit Notification Configuration dialog box, enter the ARN of the identity that the identity
owner has authorized you to use, and for which you want to configure notifications. The identity
cannot belong to the account that is currently logged in. If you want to configure notifications for
your own identities, see Configuring Amazon SNS Notifications for Amazon SES (p. 110).
5.
Specify the existing Amazon SNS topics that you want to use for bounces, complaints, and/or
deliveries, or create a new Amazon SNS topic.
214

Important
The Amazon SNS topics that you use for Amazon SES notifications must be within the
same AWS region in which you are using Amazon SES.
You can choose to publish bounce, complaint, and delivery notifications to the same Amazon SNS
topic or to different Amazon SNS topics. If you want to use an Amazon SNS topic that you do
not own, then the owner of that topic must configure an Amazon SNS access policy that allows
your account to call the SNS:Publish action on their topic. For information about how to control
access to your Amazon SNS topic through the use of IAM policies, see Managing Access to Your
Amazon SNS Topics.
6.
Choose Save Config to save your notification configuration. Changes might take a few minutes to
take effect.
After you have configured your settings, you will start receiving bounce, complaint, and/or delivery
notifications to your Amazon SNS topic(s). These notifications will follow the structure described in
Amazon SNS Notification Contents for Amazon SES (p. 111).
Editing an Amazon SES Cross-Account Notification Configuration

The easiest way to edit notification configurations is to use the Amazon SES console. If you want to
use the Amazon SES API instead, you can use the SetIdentityNotificationTopic API and pass
the identity's ARN as the Identity parameter. This action is explained in the Amazon Simple Email
The following procedure shows you how to edit a cross-account notification configuration by using the
Amazon SES console.
To edit a cross-account notification configuration by using the Amazon SES console

1.
2.

The cross-account identities for which you have set up notifications will be listed in the CrossAccount Notifications details pane.
3.
Choose the ARN of the identity for which you want to view the notification configuration.
4.
Edit the notification settings, and then choose Save Config.
Note
Setting all notifications to No SNS Topic is the equivalent of removing the identity's
notification configuration entirely. In this case, the ARN of the cross-account identity will
disappear from your list of cross-account identity ARNs in the Amazon SES console. This
does not mean that you cannot continue to send for that identity; it just means that you
are no longer set up to receive bounce, complaint, and/or delivery notifications for it. If
you want to re-enable notifications, you need to repeat the notification setup procedure
described in Setting Up a Notification Configuration (p. 214).
Viewing Your Amazon SES Cross-Account Identity Notifications

The easiest way to view your notification configurations is to use the Amazon SES console. If you want
to use the Amazon SES API instead, you can use the GetIdentityNotificationAttributes
API and pass the identity's ARN as the Identity parameter. This action is explained in the Amazon
Simple Email Service API Reference.

215

Note
The only cross-account identities that you will find in the cross-account identity list are the
identities for which you have configured notifications by using the procedure described in
Setting Up a Notification Configuration (p. 214).
To view your cross-account notification configurations by using the Amazon SES

console
1.
2.

3.
Choose the ARN of an identity.

The Edit Configuration Notification dialog box will display the identity's settings.
Removing an Amazon SES Cross-Account Identity Notification Configuration

The easiest way to remove a notification configuration is to use the Amazon SES console. If you want
to use the Amazon SES API instead, you can use the SetIdentityNotificationTopic API, pass
the identity's ARN as the Identity parameter, and pass in null for the SnsTopic parameter. This
action is explained in the Amazon Simple Email Service API Reference. To completely remove the
notification configuration, you must perform this operation for each type of notification type (bounce,
complaint, and/or delivery) that was set.
Note
When you remove a notification configuration, the ARN of the cross-account identity will
disappear from your list of cross-account identity ARNs in the Amazon SES console. This
does not mean that you cannot continue to send for that identity; it just means that you are no
longer set up to receive bounce, complaint, and/or delivery notifications for it. If you want to reenable notifications, you need to repeat the notification setup procedure described in Setting
Up a Notification Configuration (p. 214).
The following procedure shows you how to remove a cross-account notification configuration by using
the Amazon SES console.
To remove a cross-account notification configuration by using the Amazon SES

console
1.
2.

3.
Choose the box to the left of the cross-identity that you want to remove, and then choose
Remove.
4.
In the Remove Cross-Account Notification Config dialog box, choose Delete Notification
config.
The ARN of the cross-account identity will no longer appear in the list of cross-account identity
ARNs. This does not mean that you cannot send for the identity, just that you no longer have
configured notifications for it.
216

Sending Emails for the Identity Owner for Amazon SES

As a delegate sender, you send emails the same way that other Amazon SES senders do, except that
you provide the ARN of the identity that the identity owner has authorized you to use. When you call
Amazon SES to send the email, Amazon SES checks to see if the identity that you specified has a
policy that authorizes you to send for it.
There are different ways that you can specify the identity's ARN when you send an email. The method
that you can use depends on whether you send the email by using the Amazon SES API (SendEmail
or SendRawEmail) or the Amazon SES SMTP interface.
Important
To successfully send an email on behalf of an identity owner's identity, you must connect to
the Amazon SES endpoint of the AWS region in which the identity is verified. The sending
authorization policy that grants you permission must be attached to the identity in that region.

As with any Amazon SES email sender, if you access Amazon SES through the Amazon SES API
(either directly through HTTPS or indirectly through an AWS SDK), you can choose between one of
two email-sending actions: SendEmail and SendRawEmail. The Amazon Simple Email Service API
Reference describes the details of these APIs, but we provide an overview of the sending authorization
parameters here.
SendRawEmail
If you want to use SendRawEmail so that you can control the format of your emails, you can specify
the cross-account identity in one of two ways:
Pass optional parameters to the SendRawEmail API These parameters are as follows:
Parameter
Description
SourceArn
The ARN of the identity that is associated with the

sending authorization policy that permits you to send for
the email address specified in the Source parameter of
SendRawEmail.
Note
For the most common use case, we
recommend that you specify the SourceArn
and do not specify either the FromArn
or ReturnPathArn. If you only specify
the SourceArn, Amazon SES will simply
set the "From" address and the "Return
Path" addresses to the identity specified in
SourceArn.
FromArn

sending authorization policy that permits you to specify
a particular "From" address in the header of the raw
email.
ReturnPathArn

sending authorization policy that permits you to use the
email address specified in the ReturnPath parameter
of SendRawEmail.
217

Include X-headers in the email X-headers are custom headers that you can use in addition to
standard email headers. Amazon SES has three X-headers that you can use to specify sending
authorization parameters. If you include multiple instances of any of the X-headers, Amazon SES
will use the first instance. In all cases, Amazon SES removes all X-headers from the email before
sending it. The following table shows you the three X-headers that you can use with Amazon SES for
sending authorization.
Important
Do not include these X-headers in the DKIM signature, because they are removed by
Amazon SES before sending the email.
X-Header
Description
X-SES-SOURCE-ARN
Corresponds to the SourceArn.
X-SES-FROM-ARN
Corresponds to the FromArn.
X-SES-RETURN-PATH-ARN
Corresponds to the ReturnPathArn.
The following example shows an email that includes sending authorization X-headers:
X-SES-SOURCE-ARN: arn:aws:ses:us-west-2:123456789012:identity/example.com
X-SES-FROM-ARN: arn:aws:ses:us-west-2:123456789012:identity/example.com
X-SES-RETURN-PATH-ARN: arn:aws:ses:us-west-2:123456789012:identity/
example.com
To: [email protected]
Return-Path: [email protected]
Subject: subject
Content-Type: multipart/alternative;
boundary="----=_boundary"
------=_boundary
Content-Type: text/plain; charset=UTF-8
body
------=_boundary
Content-Type: text/html; charset=UTF-8
body
------=_boundary--
SendEmail
If you want to use SendEmail so that Amazon SES formats your emails for you, you can specify the
cross-account identity by passing in the optional parameters below. You cannot use the X-header
method because when you use SendEmail, Amazon SES assembles the message for you.
Parameter
Description
SourceArn

sending authorization policy that permits you to send for
the email address specified in the Source parameter of
SendRawEmail.

218

Using Dedicated IP Addresses
Parameter
Description
ReturnPathArn

sending authorization policy that permits you to use the
email address specified in the ReturnPath parameter of
SendRawEmail.
Using the Amazon SES SMTP interface

If you are using the Amazon SES SMTP interface for cross-account sending, the only method you can
use is to include the X-headers as SendRawEmail described earlier.
Using Dedicated IP Addresses with Amazon SES

By default, Amazon SES sends your email from IP addresses (IPs) that you share with other Amazon
SES customers. For an extra cost, you can reserve dedicated IPs for your exclusive use. This topic
describes use cases for dedicated IPs, trade-offs to consider when you choose between shared IPs
and dedicated IPs, how to request dedicated IPs, and how to prepare dedicated IPs before you use
them to their full capacity.
This topic contains the following sections:
Dedicated IP Use Cases (p. 219)
Trade-offs Between Dedicated IPs and Shared IPs (p. 219)
How to Request and Relinquish Dedicated IPs (p. 220)
How to Warm Up Dedicated IPs (p. 222)
Dedicated IP Use Cases

Dedicated IPs provide a set of known, unchanging IP addresses for which you control the mail.
Dedicated IPs are a good choice for the following use cases.
You want to isolate the reputation of your transactional mail, such as order confirmations and
password resets, from your marketing mail.
You want to isolate the reputation of mail streams for separate customers, programs, or engagement
metrics.
You need to know your specific IP addresses for certification purposes or security reasons. For
example, you might want to send diagnostic or operational email from a certain set of IPs, and reject
all other mail.
Trade-offs Between Dedicated IPs and Shared IPs

When you choose whether to use dedicated IPs, shared IPs, or a mix, consider the following trade-offs.
Cost
Shared IPs are included with Amazon SES. Dedicated IPs incur an extra cost. For pricing information,
see the Amazon SES pricing page.
219

How to Request and Relinquish Dedicated IPs
Email Volume
With shared IPs, you can send as little email as you like. To be a good candidate for dedicated IPs,
we typically require you to have a daily sending quota (p. 192) of at least 150,000 emails per day.
If your existing daily sending quota is less than 150,000 emails per day, please describe your use
case in detail in your dedicated IP request and we will evaluate a sending quota increase within the
same case. If you are granted dedicated IPs, you must consistently send at least 50,000 emails
per dedicated IP per day after you warm up (p. 222) the dedicated IPs. This is to maintain the
reputational health of the IPs.
We sometimes grant exceptions to the sending quota requirement to senders who only send mail to
a small, well-defined list of recipients who decide whether to accept or reject mail based on the IP
address that sent the mail (rather than the reputation of the IP).
Sending Pattern
When you use dedicated IPs, we recommend that you gradually ramp up your sending as described
in How to Warm Up Dedicated IPs (p. 222), and then maintain a sustained and consistent sending
pattern. With shared IPs, you can scale your sending up or down at any time.
Reputation Isolation
Dedicated IPs enable you to isolate the reputation of your separate mail streams, and to separate the
reputation of your email sending from the sending of other Amazon SES customers. However, this also
means that you are primarily responsible for maintaining the reputation of your IPs because your IP
reputation is largely driven by the email you send.
Regardless of the type of IPs you use, you must ensure that your email sending follows standard best
practices. For best practices, see Obtaining and Maintaining Your Recipient List (p. 228), Processing
Bounces and Complaints (p. 228), Improving Deliverability with Amazon SES (p. 227), and the
Knowledge of the IP Addresses

When you use dedicated IPs, you can find the values of the IPs that send your mail in the Dedicated
IPs page of the Amazon SES console, and those addresses do not change. With shared IPs, you do
not know the IP addresses that Amazon SES uses to send your mail, and those addresses can change
at any time.
Engaging Amazon SES

Shared IPs are the default option, so you do not need to contact us to use them. To request or
relinquish dedicated IPs, you must open an SES Sending Limits Increase case as described in How to
Request and Relinquish Dedicated IPs (p. 220).

This section describes how to request and relinquish dedicated IPs. In this process, you submit an
SES Sending Limits Increase case in Support Center. Depending on the outcome, you might need to
perform some additional steps, as described in the relevant procedures.
Requesting Dedicated IPs

The following steps show how to request dedicated IPs for the first time, and how to request additional
dedicated IPs. You will know that you need to request additional dedicated IPs when you start
receiving Maximum sending rate exceeded errors when you send emails with Amazon SES.
220

To request dedicated IPs for the first time

1.
Sign in to the AWS Management Console and open an SES Sending Limits Increase case in
Support Center. You can also reach this link using the Dedicated IPs page in the Amazon SES
console.
2.
In the case submission form, choose the region, choose Desired Maximum Send Rate, and then
enter the number of emails per second you expect to use with dedicated IPs.
3.
For the Use Case Description, tell us that you are requesting dedicated IPs, and provide as much
detail as possible about your use case, including what you expect your daily sending volume will
be with dedicated IPs. If we determine that you are a good candidate for dedicated IPs, we will let
you know the number of dedicated IPs that best fits your use case.
4.
After we evaluate your request, you will receive a reply within the case. This reply could be the
outcome of your request, or a request for more information. If your current daily sending quota is
less than the minimum requirement of 150,000 emails per day, we will evaluate a quota increase
within the same case.
5.
If the case reply indicates that you have been granted dedicated IPs, do the following steps:
a.
Open another AWS account. This is the account you will use with your dedicated IPs.
b.
In the other account, configure Amazon SES (notifications, verified identities, and so on) for
the sending you will do with dedicated IPs. You do not need to submit a separate sending
limit increase case for the new account because we will make the sending limits on your new
account the same as the sending limits of your old account.
c.
Find the AWS account ID of the new account. To find the AWS account ID, ensure that you
are signed into the new account, and then go to https://console.aws.amazon.com/billing/
home?#/account.
d.
Sign out of the new AWS account, and sign back into the old account.
e.
Go to Support Center, and provide the AWS account ID of the new account in a reply to your
dedicated IP limit increase case.
f.
You will receive a case reply confirming that your dedicated IPs are now associated with your
new account.
g.
Warm up the dedicated IPs as described in How to Warm Up Dedicated IPs (p. 222).
To request additional dedicated IPs

1.
Sign in to the AWS Management Console with the account you use for dedicated IPs, and open
an SES Sending Limits Increase case in Support Center. You can also reach this link using the
Dedicated IPs page in the Amazon SES console.
2.
In the case submission form, choose the region, choose Desired Maximum Send Rate, and then
enter the number of emails per second you expect to use across all of your dedicated IPs.
3.
For the Use Case Description, tell us that you are requesting additional dedicated IPs, explain
why you need them, and include what you expect your daily sending volume will be across all of
your dedicated IPs. If we determine that you need additional dedicated IPs, we will let you know
the number of additional dedicated IPs that best fits your use case.
4.
After we evaluate your request, you will receive a reply within the case. This reply could be the
outcome of your request, or a request for more information. If your request is granted, the reply will
confirm that your dedicated IPs are now associated with your new account.
5.
If your request is granted, you do not need to warm up the new dedicated IPs because Amazon
SES will distribute your sending among all of your dedicated IPs.
Relinquish Dedicated IPs

To relinquish dedicated IPs, do the following steps.
221

How to Warm Up Dedicated IPs
To relinquish dedicated IPs

1.
2.
3.
4.
5.
Sign in to the AWS Management Console with the account you use for dedicated IPs, and open
an SES Sending Limits Increase case in Support Center. You can also reach this link using the
Dedicated IPs page in the Amazon SES console.
In the case submission form, choose the region, choose Desired Maximum Send Rate and then
enter any number. (You will specify how many dedicated IPs you want to relinquish within the use
case description.)
For the Use Case Description, tell us that you want to relinquish dedicated IPs, and how many
dedicated IPs you want to relinquish.
After we evaluate your request, you will receive a reply within the case asking you to confirm that
you want to release the number of dedicated IPs that you specified.
You will receive a case reply confirming that your dedicated IPs have been released.

When determining whether to accept or reject an email, ISPs consider the reputation of the IP that sent
it. One of the factors that contributes to the reputation of an IP is whether the IP has a considerable
history of sending high-quality emails. ISPs that receive mail from a new IP that has no history tend to
be more cautious about accepting mail from it. This manifests as throttling (soft, transient) bounces,
but can also result in rejection (hard) bounces, as well as putting your mail in the junk folder until the IP
establishes a good reputation by sending a steady stream of high-quality mail.
You should therefore gradually increase your sending through a new dedicated IP before you use it to
its full capacity. This process is called warming up the IP. You warm up an IP by using the following
three principles:
1. Start small.
2. Measure results.
3. Make corrections.
Ideal IP warm-up times vary by ISP and recipient. It takes a minimum of 14 days to establish some
level of positive reputation with some ISPs; it can take up to 6 weeks for many ISPs. When warming
up a new IP, you should send emails to the users who engage with you the most to ensure that your
complaint rate is low.
For best results, you should carefully examine your bounce messages and send less email if you
receive a high number of IP blocking or throttling responses. For information about how to monitor your
bounces, see Monitoring Your Amazon SES Sending Activity (p. 103).
The following is an example of a warm-up plan. This plan assumes that your goal is to send one million
messages a day, and that you work with a linear warm-up plan over 45 days.
Day
Number of emails
Percentage of your
sending
22,222
2.22%
44,444
4.44%
66,667
6.67%
88,889
8.89%
111,111
11.11%
133,333
13.33%

222

Day
Number of emails
Percentage of your
sending
155,556
15.56%
177,778
17.78%
200,000
20.00%
10
222,222
22.22%
11
244,444
24.44%
12
266,667
26.67%
13
288,889
28.89%
14
311,111
31.11%
15
333,333
33.33%
16
355,556
35.56%
17
377,778
37.78%
18
400,000
40.00%
19
422,222
42.22%
20
444,444
44.44%
21
466,667
46.67%
22
488,889
48.89%
23
511,111
51.11%
24
533,333
53.33%
25
555,556
55.56%
26
577,778
57.78%
27
600,000
60.00%
28
622,222
62.22%
29
644,444
64.44%
30
666,667
66.67%
31
688,889
68.89%
32
711,111
71.11%
33
733,333
73.33%
34
755,556
75.56%
35
777,778
77.78%
36
800,000
80.00%
37
822,222
82.22%

223

Testing Email Sending
Day
Number of emails
Percentage of your
sending
38
844,444
84.44%
39
866,667
86.67%
40
888,889
88.89%
41
911,111
91.11%
42
933,333
93.33%
43
955,56
95.556%
44
977,78
97.778%
45
1,000,000
100.00%
After you successfully warm up your dedicated IPs, you must send at least 50,000 emails per
dedicated IP per day so that the IPs maintain a positive reputation with ISPs.
Testing Amazon SES Email Sending

Amazon Simple Email Service (Amazon SES) provides a mailbox simulator that you can use to test
how your application handles various email sending scenarios without affecting your sending quota
or your bounce and complaint metrics. The Amazon SES mailbox simulator is a set of test email
addresses. Each email address represents a specific scenario. You can send emails to the mailbox
simulator when you want to:
Test your application without having to create test "To" addresses.
Test how your email sending program handles bounces, complaints, and out-of-the-office (OOTO)
responses.
See what happens when you email an address that is on the Amazon SES suppression list.
Generate a bounce without putting a valid email address on the suppression list.
Find your system's maximum throughput without using up your daily sending quota.
Send test emails without affecting your email deliverability metrics for bounces and complaints.
To use the mailbox simulator, email the addresses and observe how your setup responds to the
simulated scenarios. The following table lists each simulated scenario and the corresponding email
address that you would use. The email addresses are not case-sensitive.
Note
You can only access the mailbox simulator by using Amazon SES. You cannot access it from
an external mail server.
Simulated scenario
Mailbox simulator email address
SuccessThe recipient's ISP accepts your email. If you

[email protected]
have set up delivery notifications as described in Monitoring
Using Amazon SES Notifications (p. 106), Amazon SES
sends you a delivery notification through Amazon Simple
Notification Service (Amazon SNS). Otherwise, you will
not receive any confirmation about this successful delivery
other than the API return value.
224

Testing Email Sending
Simulated scenario
Mailbox simulator email address
BounceThe recipient's ISP rejects your email with

an SMTP 550 5.1.1 response code ("Unknown User").
Amazon SES generates a bounce notification and sends it
to you via email or by using an Amazon SNS notification,
depending on how you set up your system. This mailbox
simulator email address will not be placed on the Amazon
SES suppression list as one normally would when an email
hard bounces. The bounce response that you receive from
the mailbox simulator is compliant with RFC 3464. For
information about how to receive bounce feedback, see
[email protected]
Out of the OfficeThe recipient's ISP accepts your

email and delivers it to the recipients inbox. The ISP
sends an out-of-the-office (OOTO) message to Amazon
SES. Amazon SES then forwards the OOTO message
to you via email or by using an Amazon SNS notification,
depending on how you set up your system. The OOTO
response that you receive from the Mailbox Simulator is
compliant with RFC 3834. For information about how to
set up your system to receive OOTO responses, follow
the same instructions for setting up how Amazon SES
sends you notifications in Monitoring Using Amazon SES
[email protected]
ComplaintThe recipient's ISP accepts your email and

delivers it to the recipients inbox. The recipient, however,
does not want to receive your message and clicks "Mark
as Spam" within an email application that uses an ISP that
sends a complaint response to Amazon SES. Amazon
SES then forwards the complaint notification to you via
email or by using an Amazon SNS notification, depending
on how you set up your system. The complaint response
that you receive from the mailbox simulator is compliant
with RFC 5965. For information about how to receive
bounce feedback, see Monitoring Using Amazon SES
[email protected]
Address on Suppression ListAmazon SES treats

your email as a hard bounce because the address you are
sending to is on the Amazon SES suppression list.
[email protected]
Important
If you send an email to a mailbox simulator address other than the test addresses listed
above, the unlisted address will be placed on the suppression list.
The mailbox simulator provides typical bounce, complaint, and OOTO responses. In the bounce
scenario, multiple bounces from the same sending request are gathered into a single response. In
practice, the response varies by ISP. To reduce your bounce and complaint rates, see the Amazon
Simple Email Service Email Sending Best Practices whitepaper.
When you send emails to the mailbox simulator, you will be limited by your maximum send rate. You
will also be billed for your emails. However, emails to the mailbox simulator will not affect your email
deliverability metrics for bounces and complaints or count against your sending quota.

225

Amazon SES and Security Protocols
The mailbox simulator supports labeling, which enables you to send emails to the same mailbox
simulator address in multiple ways, or to test your support for Variable Envelope Return Path (VERP).
For example, you can send an email to [email protected] and bounce
[email protected] to test how your setup matches a bounce message with the
undeliverable address that caused the bounce. For more information about VERP, see https://
en.wikipedia.org/wiki/Variable_envelope_return_path.
You can send emails to the mailbox simulator even if you are in the sandbox.
Amazon SES and Security Protocols

This topic describes the security protocols that you can use when you connect to Amazon SES, as well
as when Amazon SES delivers an email to a receiver.
Email Sender to Amazon SES

The security protocol that you use to connect to Amazon SES depends on whether you are using the
Amazon SES API or the Amazon SES SMTP interface, as described next.
HTTP
If you are using the Amazon SES API (either directly or through an AWS SDK), then all
communications are encrypted by TLS through the Amazon SES HTTPS endpoint. The Amazon SES
HTTPS endpoint supports TLS 1.2, TLS 1.1, and TLS 1.0.
SMTP Interface
If you are accessing Amazon SES through the SMTP interface, you are required to encrypt your
connection using Transport Layer Security (TLS). Note that TLS is often referred to by the name of its
predecessor protocol, Secure Sockets Layer (SSL).
Amazon SES supports two mechanisms for establishing a TLS-encrypted connection: STARTTLS and
TLS Wrapper.
STARTTLSSTARTTLS is a means of upgrading an unencrypted connection to an encrypted
connection. There are versions of STARTTLS for a variety of protocols; the SMTP version is defined
in RFC 3207. For STARTTLS connections, Amazon SES supports TLS 1.2, TLS 1.1, TLS 1.0 and
SSLv2Hello.
TLS WrapperTLS Wrapper (also known as SMTPS or the Handshake Protocol) is a means of
initiating an encrypted connection without first establishing an unencrypted connection. With TLS
Wrapper, the Amazon SES SMTP endpoint does not perform TLS negotiation: it is the client's
responsibility to connect to the endpoint using TLS, and to continue using TLS for the entire
conversation. TLS Wrapper is an older protocol, but many clients still support it. For TLS Wrapper
connections, Amazon SES supports TLS 1.2, TLS 1.1 and TLS 1.0.
For information about connecting to the Amazon SES SMTP interface using these methods, see
Connecting to the Amazon SES SMTP Endpoint (p. 61).
If your software does not support STARTTLS or TLS Wrapper, you can set up a secure tunnel to allow
your software to communicate with the Amazon SES SMTP endpoint. For information about how to set
up a secure tunnel, see Setting Up a Secure Tunnel to Connect to Amazon SES (p. 68).
226

Amazon SES to Receiver
Amazon SES to Receiver

Amazon SES sends messages over a TLS-protected connection (TLS version 1.0 only) by default. This
method, called opportunistic TLS, means that when Amazon SES establishes an SMTP connection
with a receiving mail server, Amazon SES upgrades the connection using the STARTTLS protocol if
the receiving mail server supports TLS. If the receiving server does not advertise STARTTLS or if TLS
negotiation fails, the connection proceeds in plaintext.
Amazon SES supports opportunistic TLS in all regions and you don't need to take any action to enable
it.
Best Practices with Amazon SES

This section contains the following topics on best practices for sending email using Amazon Simple
Email Service (Amazon SES):
For tips on how to improve the chances that your emails will be delivered to your recipients' inboxes,
see Improving Deliverability with Amazon SES (p. 227).
For ways to keep your mailing list from containing invalid addresses and recipients who do not want
your mail, see Obtaining and Maintaining Your Recipient List (p. 228).
For guidance on how to handle bounces and complaints, see Processing Bounces and
For factors to consider when you send email through Amazon SES using multiple AWS accounts,
see Using Multiple Amazon SES Accounts (p. 229).
Improving Deliverability with Amazon SES

The following recommendations can help improve your deliverability when you use Amazon SES.
Only send email to recipients who have requested itCollect recipients' email addresses
yourself, and with the recipients' permission. Do not buy mailing lists from third parties. Keep your
mailing lists up-to-date and provide a mechanism for recipients to unsubscribe. If your mailing list is
associated with a discussion group, consider unsubscribing recipients who have not interacted with
you for a long period of time (for example, 180 days).
Keep your number of bounces and complaints lowHigh numbers of bounces indicate to ISPs
that you do not know your recipients very well. High numbers of complaints indicate that recipients
do not want to receive your emails. If an email bounces or is marked as spam by a recipient, make
sure to remove that recipient from your list. For information about how to be notified of bounces and
complaints, see Monitoring Using Amazon SES Notifications (p. 106).
Authenticate your emailAuthentication is a way to show ISPs that your emails are genuine and
have not been modified in transit. For more information, see Authenticating Your Email in Amazon
SES (p. 92).
Send high-quality emailHigh-quality email is email that your recipients expect and find valuable.
Value means different things to different recipients and can come in the form of offers, order
confirmations, receipts, newsletters, etc. Inform your recipients of what you plan to send and
understand what your recipients expect from an email program.
Check your sending statisticsRegularly monitor your number of delivery attempts, bounces,
complaints, and rejected emails so that you can identify and correct problems right away. To check
your sending statistics, see Monitoring Your Amazon SES Sending Activity (p. 103).
Watch your sending limitsIf you attempt to exceed your sending limits, your calls to the Amazon
SES API will fail. Check the Amazon SES console or call GetSendQuota. If you need to raise your
sending limits, see Increasing Your Amazon SES Sending Limits (p. 194).
227

Obtaining and Maintaining Your Recipient List
Watch for upward trends in rejected emails. Amazon SES will generate a MessageRejected error
for any message that it does not accept; if you see a large number of rejections, make sure that none
of your applications are trying to send the same rejected message repeatedly.
For a more in-depth discussion of these and other best practices, see the Amazon Simple Email
Service Email Sending Best Practices whitepaper.
Obtaining and Maintaining Your Recipient List

Ultimately, you want to make sure that the recipient addresses on your mailing list are valid and that
your recipients want and expect your mail. Emails to invalid recipient addresses will bounce, and if
valid recipients do not want your mail, they may mark your email as spam in their email client. High
bounce and complaint rates put your account at risk of being shut down.
The following list includes, but is not limited to, ways that will help you keep your recipient list clean.
For more detailed information, see the Amazon Simple Email Service Email Sending Best Practices
whitepaper.
Set up a process to monitor bounces and complaints, and when a recipient address bounces or
complains, remove it from your mailing list. For more information, see Processing Bounces and
Do not buy email lists.
Only send emails to recipients who have interacted with your site recently (for example, within the
last 180 days).
When a recipient signs up for your list, make it clear what type of mail they are signing up for, and do
not send them other types of mail. For example, recipients who sign up to receive notifications about
particular events might not appreciate your marketing mail.
You can use double opt-in to ensure that you don't repeatedly send email to a bad address. With
double opt-in, a subscriber must first request to be subscribed to your list. Then, the subscriber
receives a verification email. They must click on the link in the email to confirm that they want to be
subscribed.
One way to prevent bots from signing up for your mailing list is to use CAPTCHA during your signup process. CAPTCHA is an automated challenge-response test that is designed to verify that
a human, rather than a computer, is entering the information. For more information, see http://
www.captcha.net.
Do not use Amazon SES as a way to clean your recipient list.
Processing Bounces and Complaints

High bounce and complaint rates put your account at risk of being shut down, so you need to make
sure that you have a process in place to remove recipient addresses that have bounced or complained
from your recipient list. For tips on preventing the inclusion of invalid email addresses on your list, see
Obtaining and Maintaining Your Recipient List (p. 228). The following guidelines pertain to handling
bounces and complaints. For more detailed information, see the Amazon Simple Email Service Email
Sending Best Practices whitepaper.
Monitor your bounces and complaints and remove any bounced or complained recipient addresses
from your mailing list. You can be notified of bounces and complaints in one of two ways: by email
or by Amazon Simple Notification Service (Amazon SNS) notifications. For more information, see
If your recipient list is large, you should probably set up an automated process. For .NET example
code on how you might manage your email list using the information in Amazon SNS notifications,
see Handling Bounces and Complaints on the Amazon SES blog.
228

Using Multiple Accounts
Treat suppression list bounces like any other hard bounce. Although it is possible to remove
addresses from the suppression list by using the Amazon SES console, only do that if you are 100%
sure that the email address is valid. In most cases, the email address is not valid, and you should
remove it from your list.
If you need to test your bounce and complaint handling process, use the Amazon SES mailbox
simulator. Emails that you send to the mailbox simulator do not affect your bounce and complaint
rates. For more information, see Testing Amazon SES Email Sending (p. 224).
Using Multiple Amazon SES Accounts

When you need to send distinctly different streams of email, you can send emails through Amazon
SES using multiple AWS accounts. For example, you might send marketing emails from one account
and transactional emails from another account, or you might use separate accounts to send email on
behalf of different clients. When you use multiple AWS accounts to send emails through Amazon SES,
keep the following in mind:
Make sure to monitor the emails you receive at the email address associated with each AWS
account you are using. We send notifications about the status of your accounts, such as Amazon
SES probation and suspension notices, to the email address associated with each particular AWS
account. It is important to pay attention to the status of all of your accounts, because the suspension
of one account puts the other accounts at risk of suspension.
If you are sending through multiple accounts, make sure that you send (and continue to send)
different types of email through your different accounts. Using multiple accounts to send very similar
content can be indicative of sending spam, and puts your accounts at risk of suspension.
Troubleshooting Amazon SES

When you use Amazon Simple Email Service (Amazon SES), you might encounter problems when you
attempt to send email. The most common problems are parsing errors; however, there could be other
reasons why the service cannot accept your request, or you may not be able to reach your maximum
send rate. Even if your request is successful, it's still possible that your email will not be delivered due
to circumstances beyond the control of Amazon SES.
This section contains the following topics that may help you when you encounter problems:
For a list of common delivery problems that you might encounter when you send email, along with
corrective actions that you can take, see Amazon SES Delivery Problems (p. 230).
For a description of issues recipients may see when they receive an email that was sent through
Amazon SES, see Problems with Emails Received from Amazon SES (p. 231).
For a list of errors that can occur when you send an email with Amazon SES, see Amazon SES
Email Sending Errors (p. 231).
For information about domain verification problems that you might encounter, see Amazon SES
Domain Verification Problems (p. 233).
For solutions to Easy DKIM issues, see Amazon SES DKIM Problems (p. 235).
For solutions to problems with bounce, complaint, and delivery notifications, see Amazon SES
Notification Problems (p. 236).
For information about how to remove an email address from the suppression list, see Removing an
Email Address from the Amazon SES Suppression List (p. 236).
229

Delivery Problems
For tips on how to increase your email sending speed when you make multiple calls to Amazon SES
using either the API or the SMTP interface, see Increasing Throughput with Amazon SES (p. 237).
For solutions to common problems that you might encounter when you use Amazon SES through its
Simple Mail Transfer Protocol (SMTP) interface, see Amazon SES SMTP Issues (p. 238).
For a list of SMTP response codes that a client application can receive from Amazon SES, see
SMTP Response Codes Returned by Amazon SES (p. 240).
For a list of error codes that are returned by the Amazon SES Query (HTTPS) API, see API Error
Codes Returned by Amazon SES (p. 242).
For a description of common enforcement issues and how to handle them, see Amazon SES
Enforcement FAQs (p. 245).
For a discussion about how IP blacklists affect your sending with Amazon SES, see Amazon SES IP
Blacklist FAQ (p. 257).
If you are calling the Amazon SES API directly, see the Amazon Simple Email Service API Reference
for the HTTP errors that you might receive.
Amazon SES Delivery Problems

After you make a successful request to Amazon SES, your message is often sent immediately. At other
times, there might be a short delay. In any case, you can be assured that your email will be sent.
When Amazon SES sends your message, however, several factors can prevent it from being delivered
successfully, and in some cases you will become aware that delivery failed only when the message
you send does not arrive. Use the following process to resolve this situation.
If an email does not arrive, try the following:
Verify that you made a SendEmail or SendRawEmail request for the email in question and that
you received a successful response. (See Structure of a Successful Response (p. 330) for an
example.) If you are making these requests programmatically, check your software logs to ensure
that the program made the request and received a successful response.
Read the blog article Three places where your email could get delayed when sending through SES
because the problem might actually be a delay rather than a nondelivery.
Check the sender's email address (the "From" address) to verify that it is valid. Also check the
Return-Path address, which is where bounce messages are sent. If your mail bounced, there will be
an explanatory error message there.
Check the AWS Service Health Dashboard to confirm that there is not a known problem with
Amazon SES.
Contact the email recipient or the recipient's ISP. Verify that the recipient is using the correct email
address, and inquire whether there have been any known delivery problems with the recipient's ISP.
Also, determine whether the email did arrive but was filtered as spam.
If you have signed up for a paid AWS Support Plan, you can open a new technical support case.
In your correspondence with us, please provide any relevant recipient addresses, along with any
request IDs or message IDs returned from the SendEmail or SendRawEmail responses.
Wait to see if the problem is actually a delay, not a permanent delivery failure. To combat spammers,
some ISPs temporarily reject incoming messages from unknown sending mail servers. This
process, called greylisting, can cause a delay in delivery. Amazon SES will retry these messages. If
greylisting is the issue, the ISP might accept the email on one of these retry attempts.
230

Problems with Received Emails
Problems with Emails Received from Amazon SES

The following issue can arise when a recipient receives an email sent through Amazon SES. If you are
looking for troubleshooting information that talks about when a recipient does not receive an email at
all, see Amazon SES Delivery Problems (p. 230).
A recipient's email client displays "sent via amazonses.com" as the source of the email
Some email clients display the "via" domain when the sender's domain does not match the domain
that the email was actually sent from (in this case, amazonses.com). For more information on why,
see this explanation from Google. As a workaround, you can set up Domain Keys Identified Mail
(DKIM), which is good practice anyway. When you authenticate your emails using DKIM, email
clients will typically not show the "via" domain because the DKIM signature shows that the email is
from the domain it claims to be from. For information about how to set up DKIM, see Authenticating
Email with DKIM in Amazon SES (p. 93).
Your email is not displaying correctly in a recipient's email client
If your email contains non-ASCII characters, you must construct the email in Multipurpose Internet
Mail Extensions (MIME) format and send it using the SendRawEmail API. For more information,
see Sending Raw Email Using the Amazon SES API (p. 88).
Your email might contain improperly formatted MIME. Ensure that it complies with RFC 2047. For
example, it must use appropriate header fields and message body encoding.
The recipient's email server or email client might impose limitations on the rendered content.
Amazon SES Email Sending Errors

This topic reviews the types of email sending-specific errors that you may encounter when you send an
email through Amazon SES. If you try to send an email through Amazon SES and the call to Amazon
SES fails, Amazon SES returns an error message to your application and does not send the email. The
way that you observe this error message depends on the way that you call Amazon SES.
If you call the Amazon SES API directly, the Query action will return an error. The error may be
MessageRejected or one of the errors specified in the Common Errors topic of the Amazon Simple
Email Service API Reference.
If you call Amazon SES using an AWS SDK that uses a programming language that supports
exceptions, Amazon SES may throw an exception. The type of exception depends on the SDK and
on the error. For example, the exception could be an Amazon SES MessageRejectedException
(the actual name may vary depending on the SDK) or a general AWS exception. Regardless of
the type of exception, the error type and the error message in the exception will give you more
information.
If you call Amazon SES through its SMTP interface, the way that you experience the error depends
on the application. Some applications may display a specific error message, some may not. For a list
of SMTP response codes, see SMTP Response Codes Returned by Amazon SES (p. 240).
Note
When your call to Amazon SES to send an email fails, you are not billed for that email.
The following are the types of Amazon SES-specific problems that can cause Amazon SES to return
an error when you try to send an email. These errors are in addition to general AWS errors like
MalformedQueryString as specified in the Common Errors topic of the Amazon Simple Email
Email address is not verified. The following identities failed the check in region <region>:
<identity1>, <identity2>, <identity3>You are trying to send email from an email address or
domain that you have not verified with Amazon SES (p. 39). This error could apply to the "From",
"Source", "Sender", or "Return-Path" address. If your account is still in the sandbox, you also must
231

Email Sending Errors
verify every recipient email address except for the recipients provided by the Amazon SES mailbox
simulator (p. 224). If Amazon SES is not able to show all of the failed identities, the error message
ends with an ellipsis.
Note
Amazon SES has endpoints in multiple AWS regions (p. 332), and email address
verification status is separate for each AWS region. You must complete the verification
process for each sender in the AWS region(s) you want to use.
Customer is suspendedYour AWS account has been blocked from sending email using
Amazon SES. You can still access the Amazon SES console and perform any activity (e.g., view
your metrics) except for email sending; if you attempt to send an email, you will receive this error
message.
If this happens, you should have received an email from Amazon SES to the email address
associated with your AWS account informing you of the problem. To appeal your suspension and
reinstate email sending privileges, follow the instructions in the email. You will need to explain in
detail why you believe that the suspension itself was an error, or the changes you have made to
ensure that the same problem does not occur again.
ThrottlingAmazon SES is limiting the rate at which you can send messages. Your application may
be trying to send too much email, or to send email at too fast a rate. In these cases, the error may be
similar to the following:
Daily message quota exceededYou have sent the maximum number of messages that you are
permitted in a 24-hour period. If you have exceeded your daily quota, you will have to wait until the
next 24-hour period before you can send more email.
Maximum sending rate exceededYou are attempting to send more emails per second than is
permitted by your maximum send rate. If you have exceeded your sending rate, you can continue
to send email, but will need to reduce your send rate. For more information, see How to handle a
"Throttling - Maximum sending rate exceeded" error on the Amazon SES blog.
You should regularly monitor your sending activity to see how close you are to your sending limits.
For more information, see Monitoring Your Amazon SES Sending Limits (p. 193). For general
information about sending limits, see Managing Your Amazon SES Sending Limits (p. 192). For
information about how to increase your sending limits, see Increasing Your Amazon SES Sending
Limits (p. 194).
Important
If the error text that explains the throttling error is not related to you exceeding your daily
quota or maximum send rate, then there might be a system-wide problem that is causing
reduced sending capabilities. For information about the service status, go to the AWS
Service Health Dashboard.
There are no recipients specifiedNo recipients were provided.
There are non-ASCII characters in the email addressThe email address string must be 7-bit
ASCII. If you want to send to or from email addresses that contain Unicode characters in the domain
part of an address, you must encode the domain using Punycode. Punycode is not permitted in the
local part of the email address (i.e., the part before the @) nor in the "friendly from" name. If you
want to use Unicode characters in the "friendly from" name, you must encode the "friendly from"
name using MIME encoded-word syntax, as described in Sending Raw Email Using the Amazon
SES API (p. 88). For more information about Punycode, see RFC 3492.
Mail FROM domain is not verifiedAmazon SES could not read the MX record required to use
the specified MAIL FROM domain. For information about editing the custom MAIL FROM domain
settings for an identity, see Editing a MAIL FROM Domain with Amazon SES (p. 51).
Configuration set does not existThe configuration set that you specified does not exist. A
configuration set is an optional parameter that you use to publish email sending events. For more
information, see Monitoring Using Amazon SES Event Publishing (p. 127).

232

Domain Verification Problems
Amazon SES Domain Verification Problems

To verify a domain with Amazon SES, you initiate the process using either the Amazon SES console
or the Amazon SES API, and then publish a TXT record to your DNS server as described in Verifying
Domains in Amazon SES (p. 41). This section contains the following topics that might help you if you
encounter problems:
To verify that the TXT record is correctly published to your DNS server, see How to Check Domain
Verification Settings (p. 233).
For some common problems you may encounter when you attempt to verify your domain with
Amazon SES, see Common Domain Verification Problems (p. 234).
How to Check Domain Verification Settings

You can check that your Amazon SES domain verification TXT record is published correctly to your
DNS server by using the following procedure. This procedure uses the nslookup tool, which is available
for Windows and Linux. On Linux, you can also use dig.
The commands in these instructions were executed on Windows 7, and the example domain we use is
ses-example.com.
In this procedure, you first find the DNS servers that serve your domain, and then query those servers
to view the TXT records. You query the DNS servers that serve your domain because those servers
contain the most up-to-date information for your domain, which can take time to propagate to other
DNS servers.
To verify that your domain verification TXT record is published to your DNS server
1.
Find the name servers for your domain by taking the following steps.
a.
Go to the command line. To get to the command line on Windows 7, choose Start and then
type cmd. On Linux-based operating systems, open a terminal window.
b.
At the command prompt, type the following, where <domain> is your domain. This will list all
of the name servers that serve your domain.
nslookup -type=NS <domain>
If your domain was ses-example.com, this command would look like:

nslookup -type=NS ses-example.com
The command's output will list the name servers that serve your domain. You will query one of
these servers in the next step.
2.
Verify that the TXT record is correctly published by taking the following steps.
a.
At the command prompt, type the following, where <domain> is your domain, and <name
server> is one of the name servers you found in step 1.
nslookup -type=TXT
_amazonses.<domain> <name server>
In our ses-example.com example, if a name server that we found in step 1 was called
ns1.name-server.net, we would type the following:
233

Domain Verification Problems
nslookup -type=TXT
b.
_amazonses.ses-example.com ns1.name-server.net
In the output of the command, verify that the string that follows text = matches the TXT
value you see when you choose the domain in the Identities list of the Amazon SES console.
In our example, we are looking for a TXT record under _amazonses.ses-example.com with a
value of fmxqxT/icOYx4aA/bEUrDPMeax9/s3frblS+niixmqk=. If the record is correctly
published, we would expect the command to have the following output:
_amazonses.ses-example.com text = "fmxqxT/icOYx4aA/bEUrDPMeax9/s3frblS
+niixmqk="
Common Domain Verification Problems

If you attempt to verify a domain using the procedure in Verifying Domains in Amazon SES (p. 41) and
you encounter problems, review the possible causes and solutions below.
Your DNS provider does not allow underscores in TXT record namesYou can omit the
_amazonses from the TXT record name.
You want to verify the same domain multiple times and you can't have multiple TXT records
with the same nameYou might need to verify your domain more than once because you're
sending in different regions or you're sending from multiple AWS accounts from the same domain
in the same region. If your DNS provider does not allow you to have multiple TXT records with the
same name, there are two workarounds. The first workaround, if your DNS provider allows it, is to
assign multiple values to the TXT record. For example, if your DNS is managed by Amazon Route
53, you can set up multiple values for the same TXT record as follows:
1. In the Amazon Route 53 console, choose the _amazonses TXT record you added when you
verified your domain in the first region.
2. In the Value box, press Enter after the first value.
3. Add the value for the additional region, and save the record set.
The other workaround is that if you only need to verify your domain twice, you can verify it once with
_amazonses in the TXT record name and the other time you can omit _amazonses from the record
name entirely. We recommend the previous solution as a best practice, however.
Your email address is provided by a web-based email service you do not have control over
You cannot successfully verify a domain that you do not own. For example, if you want to send email
through Amazon SES from a gmail address, you need to verify that email address specifically; you
cannot verify gmail.com. For information about individual email address verification, see Verifying
Email Addresses in Amazon SES (p. 39).
Amazon SES reports that domain verification failedYou receive a "Domain Verification Failure"
email from Amazon SES, and the domain displays a status of "failed" in the Domains tab of the
Amazon SES console. This means that Amazon SES cannot find the necessary TXT record on your
DNS server. Verify that the required TXT record is correctly published to your DNS server by using
the procedure in How to Check Domain Verification Settings (p. 233), and look for the following
possible errors:
Your DNS provider appended the domain name to the end of the TXT recordAdding a TXT
record that already contains the domain name (such as _amazonses.example.com) may result in
the duplication of the domain name (such as _amazonses.example.com.example.com). To avoid
duplication of the domain name, add a period to the end of the domain name in the TXT record.
This will indicate to your DNS provider that the record name is fully qualified (that is, no longer
relative to the domain name), and prevent the DNS provider from appending an additional domain
name.
234

DKIM Problems
You receive an email from Amazon SES that says your domain verification has been (or will
be) revokedAmazon SES can no longer find the required TXT record on your DNS server. The
notification email will inform you of the length of time in which you must re-publish the TXT record
before your domain verification status is revoked.
Note
You can review the required TXT record information in the Amazon SES console by using
the following instructions. In the navigation pane, under Identities, choose Domains. In
the list of domains, choose (not just expand) the domain to display the domain verification
settings, which include the TXT record name and value.
If your domain verification status is revoked, you must restart the verification procedure in Verifying
Domains in Amazon SES (p. 41) from the beginning, just as if the revoked domain were an entirely
new domain. After you publish the TXT record to your DNS server, verify that the TXT record is
correctly published by using How to Check Domain Verification Settings (p. 233).
Amazon SES DKIM Problems

If you attempt to set up Easy DKIM using the procedure in Easy DKIM in Amazon SES (p. 94) and
you encounter problems, review the possible causes and solutions below.
You set up Easy DKIM successfully, but your messages are not being DKIM-signedPossible
problems are:
Make sure that Easy DKIM is enabled for the appropriate identity. To enable Easy DKIM for an
identity in the Amazon SES console, choose the email address or domain in the Identities list.
On the Details page for the email address or domain, expand DKIM, and then choose Enable to
enable DKIM.
You could be sending from an individually verified email address that does not have DKIM-signing
enabled. If you set up Easy DKIM for a domain, it will apply to all email addresses in that domain
except for email addresses that you individually verified. Individually verified email addresses use
separate settings. If this is your issue, either remove the email address from your identity list (its
settings will then be inherited from the verified domain's settings) or enable Easy DKIM for the
email address as explained above.
If you are using Amazon SES in multiple regions or with multiple AWS accounts, you must perform
the Easy DKIM set-up procedure described in Easy DKIM in Amazon SES (p. 94) for each
region and account for which you want to use Easy DKIM. Amazon SES will generate a unique
set of DNS records for each domain/account/region combination. You will need to add all of these
records to your DNS server. If you remove the necessary DNS records for a specific region or
account, Amazon SES will disable DKIM signing only for that account in that region, and notify you
by email so that you can take action.
Your domain's DKIM details in the Amazon SES console show DKIM: waiting on sender
verification... DKIM Verification Status: pending verificationYour DKIM status is pending,
which means that Amazon SES has not yet detected the required CNAME records on your DNS
server, which you should have published during the Easy DKIM set-up procedure (Easy DKIM in
Amazon SES (p. 94)). If your DKIM status is pending, see the following articles on the Amazon
SES blog:
DKIM Troubleshooting Series: Your DKIM Status is Pending
DKIM Troubleshooting Series: Your DKIM Status is Still Pending
When queried, your DNS servers successfully return the Amazon SES DKIM CNAME records,
but return SERVFAIL for the TXT recordsYour DNS provider might have problems redirecting
CNAME records. Note that Amazon SES and ISPs query for TXT records. To comply with the DKIM
specification, your DNS servers must be able to respond to TXT record queries as well as CNAME
record queries. If your DNS provider cannot respond to TXT record queries, an alternative is to use
Amazon Route 53 for your DNS hosting.
235

Notification Problems
Your emails are being DKIM-signed, but the DKIM signature is not validatingSee DKIM
Troubleshooting Series: Why is My Signature Not Validating? on the Amazon SES blog.
You receive an email from Amazon SES that says your DKIM setup has been (or will be)
revokedThis means that Amazon SES can no longer find the required CNAME records on your
DNS server. The notification email will inform you of the length of time in which you must re-publish
the CNAME records before your DKIM setup status is revoked and DKIM signing is disabled. If
your DKIM setup is revoked, you must restart the DKIM set-up procedure in Easy DKIM in Amazon
SES (p. 94) from the beginning.
You do not have DKIM-signing enabled, yet your message headers contain a DKIM
signatureThe DKIM signature you are seeing contains d=amazonses.com and is automatically
added by Amazon SES.
Your emails contain two DKIM signaturesThe extra DKIM signature, which contains
d=amazonses.com, is automatically added by Amazon SES. You can ignore it.
Amazon SES Notification Problems

If you encounter a problem with bounce, complaint, or delivery notifications, review the possible causes
and solutions below.
You receive bounce notifications via Amazon SNS, but you don't know which recipients the
notifications correspond toIn the future, to associate a bounce notification with a given recipient,
you have the following options:
Since Amazon SES doesn't retain any custom message IDs that you have added, store a mapping
between an identifier and the Amazon SES message ID that Amazon SES passes back to you
when it accepts the email.
In each call to Amazon SES, send to a single recipient, rather than sending a single message to
multiple recipients.
You can enable feedback forwarding via email, which will forward the full bounce message to you.
You receive complaint notifications via Amazon SNS or email feedback forwarding, but you
don't know which recipients the notifications correspond toSome ISPs redact the complained
recipient's email address before passing the complaint notification to Amazon SES. To enable you
to find the recipient's email address, your best option is to store your own mapping between an
identifier and the Amazon SES message ID that Amazon SES passes back to you when it accepts
the email. Note that Amazon SES does not retain any custom message IDs that you add.
You want to set up notifications to go to an Amazon SNS topic you don't ownThe owner
of that topic must configure an Amazon SNS access policy that allows your account to call the
SNS:Publish action on their topic. For information about how to control access to your Amazon
SNS topic through the use of IAM policies, see Managing Access to Your Amazon SNS Topics in the
Amazon Simple Notification Service Developer Guide.
Removing an Email Address from the Amazon SES

Suppression List
Amazon SES maintains a suppression list of recipient email addresses that have recently caused a
hard bounce for any Amazon SES customer. If you try to send an email through Amazon SES to an
address that is on the suppression list, the call to Amazon SES succeeds, but Amazon SES treats
the email as a hard bounce instead of attempting to send it. Like any hard bounce, suppression list
bounces count towards your sending quota and your bounce rate. An email address can remain on the
suppression list for up to 14 days.
The only way you will know if an address is on the suppression list is that you will receive a
suppression list bounce when you send to it. There is no way to query the suppression list in advance.
236

Increasing Throughput
Important
As with any email address that hard bounces, you should remove addresses that cause a
suppression list bounce from your mailing list unless you are absolutely sure the address
is valid, because suppression list bounces count towards your bounce rate and a high
bounce rate puts your account at risk of being shut down. If you remove an address from the
suppression list when it is indeed undeliverable, then the next time you or another Amazon
SES customer sends an email to that address, it will hard bounce and the address will go back
on the suppression list.
If you are sure that an address on the suppression list is valid, you can remove it from the list by using
the following procedure. Although each AWS region has a separate suppression list, if you remove an
address from the suppression list of one region, the address is removed from the suppression list of all
regions.
To remove an email address from the suppression list

1.
2.
3.
In the Navigation pane, choose Suppression List Removal.
4.
In the Email Address field, type the email address that you want to remove from the suppression
list.
In the Type characters field, type the characters that you see in the image above it.
5.
Choose Submit.
After you submit the form, you can fill out the form for another email address. Suppression list removal
requests are processed immediately.
Increasing Throughput with Amazon SES

When you send emails, you can call Amazon SES as frequently as your maximum send rate allows.
(For more information about your maximum send rate, see Managing Your Amazon SES Sending
Limits (p. 192).) However, each call to Amazon SES takes time to complete.
If you are making multiple calls to Amazon SES using the Amazon SES API or the SMTP interface, you
may want to consider the following tips to help you improve your throughput:
Measure your current performance to identify bottlenecksA possible performance test
involves sending multiple test emails as quickly as possible within a code loop in your application.
Measure the round-trip latency of each SendEmail request. Then, incrementally launch additional
instances of the application on the same machine, and watch for any impact on network latency. You
may also want to run this test on multiple machines and on different networks to help pinpoint any
possible machine resource bottlenecks or network bottleneck that may exist.
(API only) Consider using persistent HTTP connectionsRather than incurring the overhead
of establishing a separate new HTTP connection for each API request, use persistent HTTP
connections. That is, reuse the same HTTP connection for multiple API requests.
Consider using multiple threadsWhen an application uses a single thread, the application
code calls the Amazon SES API and then synchronously waits for an API response. Sending
emails is typically an I/O-bound operation, and doing the work from multiple threads provides better
throughput. You can send concurrently using as many threads of execution as you wish.
Consider using multiple processesUsing multiple processes can help increase your throughput
because you will have more concurrent active connections to Amazon SES. For example, you can
segment your intended emails into multiple buckets, and then run multiple instances of your email
sending script simultaneously.
Consider using a local mail relayYour application can quickly transmit messages to your local
mail server, which can then help to buffer the messages and asynchronously transmit them to
Amazon SES. Some mail servers support delivery concurrency, which means that even if your
237

SMTP Issues
application is generating emails to the mail server in a single-threaded fashion, the mail server will
use multiple threads when sending to Amazon SES. For more information, see Integrating Amazon
SES with Your Existing Email Server (p. 67).
Consider hosting your application closer to the Amazon SES API endpointYou may wish to
consider hosting your application in a data center close to the Amazon SES API endpoint, or on an
Amazon EC2 instance in the same AWS Region as the Amazon SES API endpoint. This may help to
decrease network latency between your application and Amazon SES, and improve throughput. For
a list of Amazon SES endpoints, see Regions and Amazon SES (p. 332).
Consider using multiple machinesDepending on the system configuration on your host
machine, there may be a limit on the number of simultaneous HTTP connections to a single IP
address, which may limit the benefits of parallelism once you exceed a certain number of concurrent
connections on a single machine. If this is a bottleneck, you may wish to consider making concurrent
Amazon SES requests using multiple machines.
Consider using the Amazon SES query API instead of the SMTP endpointUsing the Amazon
SES query API enables you to submit the email send request using a single network call, whereas
interfacing with the SMTP endpoint involves an SMTP conversation which consists of multiple
network requests (for example, EHLO, MAIL FROM, RCPT TO, DATA, QUIT). For more information
about the Amazon SES query API, see Using the Amazon SES API to Send Email (p. 87).
Use the Amazon SES mailbox simulator to test your maximum throughputTo test any
changes you may implement, you can use the mailbox simulator. The mailbox simulator can help
you to determine your systems maximum throughput without using up your daily sending quota. For
information about the mailbox simulator, see Testing Amazon SES Email Sending (p. 224).
If you are accessing Amazon SES through its SMTP interface, see Amazon SES SMTP
Issues (p. 238) for specific SMTP-related issues that may affect throughput.
Amazon SES SMTP Issues

If you are having problems sending email through the Amazon SES Simple Mail Transfer Protocol
(SMTP) interface, review the possible causes and solutions below. For general information about
sending email through the Amazon SES SMTP interface, see Using the Amazon SES SMTP Interface
to Send Email (p. 56).
You are unable to connect to the Amazon SES SMTP endpoint
Verify that you are using the right credentials. Your SMTP credentials are different than your
AWS credentials. To obtain your SMTP credentials, see Obtaining Your Amazon SES SMTP
Credentials (p. 57). For more information about credentials, see Using Credentials With Amazon
SES (p. 323).
Your network might be blocking outbound connections over the port you're trying to send email
from. Try the following command: telnet email-smtp.us-west-2.amazonaws.com <port>,
where <port> is the port you're trying to use (typically 25, 465, 587, 2465, or 2587). If that works,
and you are trying to connect to Amazon SES using TLS Wrapper or STARTTLS, try the openssl
commands shown in Using the Command Line to Send Email Through the Amazon SES SMTP
Interface (p. 85). If you cannot connect to the Amazon SES SMTP endpoint using telnet or
openssl, then something in your network (for example, a firewall) is blocking outbound connections
over the port you're trying to use. Work with your network administrator to diagnose and fix the
problem.
You are sending to Amazon SES from an Amazon EC2 instance via port 25 and you cannot
reach your Amazon SES sending limits or you are receiving time outsAmazon EC2 imposes
default sending limits on email sent via port 25 and throttles outbound connections if you attempt
to exceed those limits. To remove these limits, submit an Amazon EC2 Request to Remove Email
Sending Limitations. You can also connect to Amazon SES via port 465 or port 587, neither of which
is throttled.
Network errors are causing dropped emailsEnsure that your application uses retry logic when
it connects to the Amazon SES SMTP endpoint, and that your application can detect and retry
238

SMTP Issues
message delivery in case of a network error. SMTP is a verbose protocol and submitting an email
using this protocol requires several network round trips. Because of the nature of this protocol, the
potential of transient network errors increases. A message is accepted by Amazon SES for delivery
only when Amazon SES responds with an Amazon SES message ID.
You lose connection with the SMTP endpoint
If you receive a time-out error message, the maximum transmission unit (MTU) size on the
network interface of the computer you're using to connect to the Amazon SES SMTP interface
might be too large. To mitigate this, you can try setting the MTU size on that computer to 1500. For
instructions on how to set the MTU size on Microsoft Windows, Linux, and Mac OS X operating
systems, see Queries Appear to Hang in the Client and Do Not Reach the Cluster in the Amazon
Redshift Cluster Management Guide. Users connecting to Amazon SES from an Amazon EC2
instance can alternatively try the workaround described in Security Group Rules for Path MTU
Discovery in the Amazon EC2 User Guide for Linux Instances.
Do not attempt to maintain long-lived connections with the Amazon SES SMTP endpoint. The
Amazon SES SMTP endpoint runs on a fleet of Amazon EC2 instances behind an Elastic Load
Balancer (ELB). In order to ensure that the system is up-to-date and fault tolerant, active Amazon
EC2 instances are periodically terminated and replaced with new instances. Because your
application connects to an Amazon EC2 instance through the ELB, the connection becomes
invalid when the Amazon EC2 instance is terminated. You should establish a new SMTP
connection after you have delivered a fixed number of messages via a single SMTP connection,
or if the SMTP connection has been active for some amount of time. You will need to experiment
to find appropriate thresholds depending on where your application is hosted and how it submits
email to Amazon SES.
You want to know the IP addresses of the Amazon SES SMTP mail servers so that you can
whitelist the IP addresses with your networkWe are unable to provide a specific set of IP
addresses for the Amazon SES SMTP endpoints because they reside behind load balancers and the
IP addresses can change frequently. We recommend that you only whitelist based on DNS and not
static IP addresses.
You are integrating Amazon SES with a Sendmail or Postfix mail server using the instructions
in Integrating Amazon SES with Your Existing Email Server (p. 67), and your mail server
cannot authenticate with the Amazon SES SMTP endpoint because the hostname does not
match. In this case, try the following steps.
SendmailIn Step 1 of Integrating Amazon SES with Sendmail (p. 72), put the following
additional line in /etc/mail/authinfo, depending on the AWS region of the Amazon SES endpoint
you are using. Note that you must replace USERNAME and PASSWORD with your SMTP user
name and password.
Region name
Add this line to /etc/mail/authinfo
US East (N.
Virginia)
AuthInfo:ses-smtp-prod-335357831.useast-1.elb.amazonaws.com "U:root" "I:USERNAME"

US West
(Oregon)
AuthInfo:ses-smtp-us-west-2-prod-14896026.uswest-2.elb.amazonaws.com "U:root" "I:USERNAME"

EU (Ireland)
AuthInfo:ses-smtp-eu-west-1-prod-345515633.euwest-1.elb.amazonaws.com "U:root" "I:USERNAME"

In Step 4 of Integrating Amazon SES with Sendmail (p. 72), add the following to /etc/mail/access:

239

SMTP Response Codes
Region name
Add this line to /etc/mail/access
US East (N.
Virginia)
Connect:ses-smtp-prod-335357831.useast-1.elb.amazonaws.com RELAY
US West
(Oregon)
Connect:ses-smtp-us-west-2-prod-14896026.uswest-2.elb.amazonaws.com RELAY
EU (Ireland)
Connect:ses-smtp-eu-west-1-prod-345515633.euwest-1.elb.amazonaws.com RELAY
PostfixIn Step 3 of Integrating Amazon SES with Postfix (p. 69), put the following additional line
in /etc/postfix/sasl_passwd, depending on the AWS region of the Amazon SES endpoint you are
using. Note that you must replace USERNAME and PASSWORD with your SMTP user name and
password.
Region name
Add this line to /etc/postfix/sasl_passwd
US East (N.
Virginia)
ses-smtp-prod-335357831.us-east-1.elb.amazonaws.com:25
USERNAME:PASSWORD
US West
(Oregon)
ses-smtp-us-west-2-prod-14896026.uswest-2.elb.amazonaws.com:25 USERNAME:PASSWORD
EU (Ireland)
ses-smtp-eu-west-1-prod-345515633.euwest-1.elb.amazonaws.com:25 USERNAME:PASSWORD
SMTP Response Codes Returned by Amazon SES

This topic contains a list of SMTP response codes that are returned by Amazon SES. The way in which
errors are handled depends on the SMTP client that you use; some SMTP clients may not display error
codes at all.
You should retry SMTP requests that receive 4xx errors. In this case, to reduce the likelihood
of generating duplicates, we recommend that you implement an exponential retry method with
progressively longer waits (5, 10, and 30 seconds) between consecutive timeouts. If the third retry call
does not succeed, perform another set of retries after 20 minutes. For an example implementation
that uses an exponential retry policy with Amazon SES, see How to handle a "Throttling - Maximum
sending rate exceeded" error on the Amazon SES blog.
Note
AWS SDKs implement retry logic automatically, although they use the HTTPS interface
instead of SMTP.
SMTP client errors (5xx) indicate that you need to revise the request to correct the problem before
trying again. For example, if your AWS authentication credentials are invalid, you must update your
setup to use the proper credentials before trying to send the email again.
Description
Response code
More information
Authentication successful
235 Authentication successful
N/A
Successful delivery
250 Ok <Message ID>
<Message ID> is a string of

characters that Amazon SES uses
to uniquely identify a message.
Daily sending quota

exceeded
454 Throttling failure: Daily

message quota exceeded
You have exceeded the maximum

number of emails that Amazon

240

SMTP Response Codes
Description
Response code
More information
SES permits you to send in a 24hour period. For more information,
see Managing Your Amazon SES
Maximum send rate

exceeded
454 Throttling failure: Maximum

sending rate exceeded
You have exceeded the maximum

number of emails that Amazon
SES permits you to send per
second. For more information,
see Managing Your Amazon SES
Amazon SES issue

when validating SMTP
credentials
454 Temporary authentication

failure
Possible reasons include, but are

not limited to:
There is a problem with the
encryption between your emailsending application and Amazon
SES. Note that you need to
use an encrypted connection
when you connect to Amazon
SES. For more information, see
Connecting to the Amazon SES
SMTP Endpoint (p. 61).
Amazon SES could be
experiencing an issue. Check
the AWS Service Health
Dashboard for updates.
Problem receiving the

request
454 Temporary service failure
Amazon SES did not successfully

receive the request and therefore
did not send the message. Please
retry the request.
Incorrect credentials
530 Authentication required
Your email-sending application

did not attempt to authenticate
with Amazon SES when it tried
to connect to the Amazon SES
SMTP interface. For an example
of how to set up an email-sending
application to authenticate with
Amazon SES, see Configuring
Email Clients to Send Through
Amazon SES (p. 62).
Authentication Credentials
Invalid
535 Authentication Credentials

Invalid
Your email-sending application

did not provide the correct SMTP
credentials to Amazon SES.
Note that your SMTP credentials
are not the same as your AWS
credentials. For more information,
see Obtaining Your Amazon SES
Account not subscribed to

Amazon SES
535 Account not subscribed to

SES
The AWS account that owns the

SMTP credentials is not signed up
for Amazon SES.

241

API Error Codes
Description
Response code
More information
User not authorized to call

the Amazon SES SMTP
endpoint
554 Access denied: User <User

ARN> is not authorized to
perform ses:SendRawEmail on
resource <Identity ARN>
The AWS Identity and Access

Management (IAM) policy or
the Amazon SES sending
authorization policy of the
user who owns the SMTP
credentials is not allowed to
call the Amazon SES SMTP
endpoint. For information about
how to get SMTP credentials
for an existing IAM user, see
Obtaining Amazon SES SMTP
Credentials by Converting AWS
Unverified email address
554 Message rejected: Email

address is not verified. The
following identities failed the
check in region <region>:
<identity1>, <identity2>,
<identity3>
You are trying to send email from

an email address or domain that
you have not verified with Amazon
SES (p. 39). This error could apply
to the "From", "Source", "Sender",
or "Return-Path" address. If your
account is still in the sandbox, you
also must verify every recipient
email address except for the
recipients provided by the Amazon
SES mailbox simulator (p. 224).
If Amazon SES is not able to show
all of the failed identities, the error
message ends with an ellipsis.
Note
Amazon SES has
endpoints in multiple
AWS regions (p. 332),
and email address
verification status is
separate for each
AWS region. You must
complete the verification
process for each sender
in the AWS region(s) you
want to use.
API Error Codes Returned by Amazon SES

This topic contains a list of error codes that are returned by the Amazon SES Query (HTTPS) API. For
more information about the Amazon SES API, see the Amazon Simple Email Service API Reference.
You should retry HTTPS requests that receive 5xx errors. In this case, to reduce the likelihood
of generating duplicates, we recommend that you implement an exponential retry method with
progressively longer waits (5, 10, and 30 seconds) between consecutive timeouts. If the third retry call
does not succeed, perform another set of retries after 20 minutes. For an example implementation
that uses an exponential retry policy with Amazon SES, see How to handle a "Throttling - Maximum
sending rate exceeded" error on the Amazon SES blog.

242

API Error Codes
Note
AWS SDKs implement retry logic automatically.
HTTPS client errors (4xx) indicate that you need to revise the request to correct the problem before
trying again. For example, if your AWS authentication credentials are invalid, you must update your
setup to use the proper credentials before trying to send the email again.
Error
Description
HTTPS Status Code
Actions That Return

This Code
ConfigurationSetDoesNotExist
The specified
configuration set
does not exist. A
configuration set is
an optional parameter
that you use to publish
email sending events.
For more information,
see Monitoring Using
Amazon SES Event
Publishing (p. 127).
400
SendEmail,
SendRawEmail
IncompleteSignature
The request signature

does not conform to
AWS standards.
400
All
InternalFailure
The request processing 500

has failed because
of an unknown error,
exception, or failure.
All
InvalidAction
The requested action

or operation is invalid.
Verify that the action is
typed correctly.
400
All
InvalidClientTokenId
The X.509 certificate

or AWS access key ID
provided does not exist
in our records.
403
All
InvalidParameterCombination
Parameters that must
not be used together
were used together.
400
All
InvalidParameterValue
An invalid or outof-range value was

supplied for the input
parameter.
400
All
InvalidQueryParameter
The AWS query string

is malformed, does
not adhere to AWS
standards.
400
All
400
SendEmail,
SendRawEmail
MailFromDomainNotVerified
The message could
not be sent because
Amazon SES could
not read the MX record
required to use the

243

API Error Codes
Error
Description
HTTPS Status Code
Actions That Return

This Code
specified MAIL FROM

domain.
MalformedQueryString
The query string

contains a syntax error.
404
All
MessageRejected
Indicates that the

action failed, and
the message could
not be sent. Check
the error stack for a
description of what
caused the error.
For more information
about problems
that can cause this
error, see Amazon
SES Email Sending
Errors (p. 231).
400
SendEmail,
SendRawEmail
MissingAction
The request is missing

an action or a required
parameter.
400
All
MissingAuthenticationToken
The request must
contain either a valid
(registered) AWS
access key ID or X.509
certificate.
403
All
MissingParameter
A required parameter
for the specified action
is not supplied.
400
All
OptInRequired
The AWS access key

403
ID needs a subscription
for the service.
All
RequestExpired
The request reached

the service more than
15 minutes after the
date stamp on the
request or more than
15 minutes after the
request expiration date
(such as for pre-signed
URLs), or the date
stamp on the request is
more than 15 minutes
in the future.
400
All
ServiceUnavailable
The request failed due

to a temporary failure
of the server.
503
All

244

Enforcement FAQs
Error
Description
HTTPS Status Code
Actions That Return

This Code
Throttling
The request was

denied due to request
throttling.
400
All
Amazon SES Enforcement FAQs

If the emails you send result in excessive bounces, complaints, or other issues, your sending abilities
might be placed on probation or suspended. This process is called enforcement. In these cases, you
will receive a notification at the email address associated with your AWS account.
This section contains FAQs on the following enforcement-related topics:
Probations (p. 245)
Suspensions (p. 247)
Bounces (p. 248)
Complaints (p. 250)
Spamtraps (p. 254)
Manual Investigations (p. 256)
Amazon SES Probation FAQ

Q1. I received a probation notice. What does that mean?
We have detected a significant issue with the sending on your account and we're giving you time to
fix it. You can still send normally for now, but if you don't fix the problem in the allotted timeframe or
sending allowance, your Amazon SES sending privileges might be suspended.
Q2. Will I always be notified if I am put on probation?

Yes. You will receive a notification at the email address of the AWS account associated with the
Amazon SES probation.
Q3. Will the Amazon SES probation affect my use of other AWS services?
No.
Q4. What should I do if I'm on probation?

You should do the following:
If your situation allows it, stop sending mail until you fix the problem. Although probation does not
affect your ability to send mail through Amazon SES, if you continue to send mail without first making
changes, you are putting your continued sending at risk.
Look at the email you received from us for a summary of the issue.
Investigate your sending to determine what aspect of your sending specifically triggered the issue.
Once you have made your fixes, send us an appeal telling us about the fixes you made (see Q6.
How do I submit an appeal? (p. 246)). Note that you should appeal your probation only after you've
made your changesdo not submit an appeal outlining changes you plan to make. If you do, we
will ask you to contact us again once the fixes are actually in place. If we find that you have fixed the
problem, we'll take you off probation.
245

Enforcement FAQs
Be sure to provide any information we specifically request. We need this information to evaluate your
case.
Q5. What is an appeal?

An appeal is when you reply to a probation or suspension notification (or email [email protected] from the email address associated with your AWS account) and provide
the specific information we need to determine whether we can remove the probation or suspension.
For a list of information to provide, see Q6. How do I submit an appeal? (p. 246).
Q6. How do I submit an appeal?

Just reply to the probation notification. If you cannot find the probation notification, send your appeal
to [email protected] from the email address associated with your AWS account. In your
appeal, you should explain in as much detail as possible the following three things:
An explanation of how and why you think the problem occurred.
A list of changes you have already made to address the issue (not changes you plan to make).
An explanation of why you believe these changes will prevent the problem from happening again.
Please read the FAQ specific to your issue (for example, bounces) to see if there is additional
information you need to provide in your appeal.
Note
Failure to provide this information will delay the appeal process because we will request the
remaining information before we can make a decision. In addition, be sure to provide any
additional information we specifically request during the appeal correspondence.
Q7. What if my appeal isn't accepted?

We will respond to you explaining why your appeal wasn't accepted, and you will often have the option
of appealing again after you address the issue. For example, we might ask you for more information,
and once you provide the information, your appeal might be accepted. As another example, if you tell
us how you will fix the problem and haven't actually fixed it, we'll ask you to contact us again once
you've actually fixed the issue.
Q8. Can you help me diagnose the problem?

Typically we can give you only a high-level overview of your issue (for example, that you have a
problem with bounces). You will need to investigate the root cause on your end.
Q9. How will I know if I'm off probation?

We will provide this information in our response to your appeal, or in some cases you will receive an
automated notification at the email address associated with your AWS account. The notification will
indicate either that you're off probation, or that your account has been suspended because you haven't
fixed the problem.
Q10. Will I always have a probation period if there's a problem?

No. There are two cases in which you might not be provided a probation period:
If your sending problem is very severe, you might be immediately suspended. As with any
suspension, we will send you a notification at that time.
If you show a pattern of repeated probations, eventually you might be suspended rather than being
put on probation again. For this reason, it is important to address the underlying problem rather
246

Enforcement FAQs
than just the specific incident that caused a specific probation. For instance, if a particular campaign
triggers a probation, you must do more than simply stop that campaign. You need to determine
which properties of the campaign were problematic and ensure that you have processes in place so
that your future campaigns won't have the same issue.
Q11. What if I make my fixes shortly before the probation is due to expire?
Contact us through the appeal process to let us know that you fixed the problem.
Q12. Can I get help from my AWS representative or Premium Support?

If you are actively working with an AWS account representative, we will contact him or her regarding
your probation, and he or she might be able to help you to better understand the problem. Feel free to
contact your representative directly as well. If you are signed up for Premium Support, you might also
want to engage that team to help with this process.
Amazon SES Suspension FAQ

Q1. I received a suspension notice. What does that mean?
We had to shut down your account due to a critical issue with your sending, so you can no longer send
emails. There are three scenarios in which a suspension can occur:
You are put on probation for a sending problem (for example, bounces), the probation expires, and
the issue has not been resolved.
Your problem is so severe that you were immediately suspended without a probation period.
You have a history of repeated probations for a particular issue, and the issue reoccurred.
Q2. Will I always be notified if I am suspended?

Yes. You will receive a notification at the email address of the AWS account associated with the
Amazon SES suspension.
Q3. Will the Amazon SES suspension affect my use of other AWS services?
No.
Q4. What should I do if my account has been suspended?

You should do the following:
Look at the email you received from us for a summary of the issue.
Investigate your sending to determine what aspect of your sending specifically triggered the issue.
Once you have fixed the issue, send us an appeal telling us about the fixes you made (see Q6. How
do I submit an appeal? (p. 248)). Note that you should appeal your suspension only after you've
made your changes do not submit an appeal outlining changes you plan to make. If you do, we will
ask you to contact us again once the fixes are actually in place.
Be sure to provide any information we specifically request. We need this information to evaluate your
case.
Q5. What is an appeal?

An appeal is when you reply to a probation or suspension notification (or email [email protected] from the email address associated with your AWS account) and provide
247

Enforcement FAQs
the specific information we need to determine whether we can remove the probation or suspension.
For a list of information to provide, see Q6. How do I submit an appeal? (p. 248).
Q6. How do I submit an appeal?

Just reply to the suspension notification. If you cannot find the suspension notification, send your
appeal to [email protected] from the email address associated with your AWS account.
In your appeal, you should explain in as much detail as possible the following three things:
An explanation of how and why you think the problem occurred.
A list of changes you have already made to address the issue (not changes you plan to make).
An explanation of why you believe these changes will prevent the problem from happening again.
Read the FAQ specific to your issue (for example, bounces) to see if there is additional information you
need to provide in your appeal.
Note
Failure to provide this information will delay the appeal process because we will request the
remaining information before we can make a decision. In addition, be sure to provide any
additional information we specifically request during the appeal correspondence.
Q7. What if my appeal isn't accepted?

We will respond to you explaining why your appeal wasn't accepted, and you will often have the option
of appealing again after you address the issue. For example, we might ask you for more information,
and once you provide the information, your appeal might be accepted. As another example, if you tell
us how you will fix the problem and haven't actually fixed it, we'll ask you to contact us again once
you've actually fixed the issue.
Q8. Can you help me diagnose the problem?

Typically we can give you only a high-level overview of your issue (for example, that you have a
problem with bounces). You will need to investigate the root cause on your end.
Q9. How will I know if my account has been reinstated?

We will provide this information in our response to your appeal, or in some cases you will receive
an automated notification at the email address associated with your AWS account. You can also try
sending an email to yourself through Amazon SES (for example, using the Amazon SES console). If
the attempt is successful, then you have been reinstated.
Q10. Can I get help from my AWS representative or Premium Support?

If you are actively working with an AWS account representative, we will contact him or her regarding
your probation, and he or she might be able to help you to better understand the problem. Feel free to
contact your representative directly as well. If you are signed up for Premium Support, you might also
want to engage that team to help with this process.
Amazon SES Bounce FAQ

Q1. Why do you care about my bounces?
High bounce rates are often used by entities such as ISPs, mailbox providers, and anti-spam
organizations as indicators that senders are engaging in low-quality email-sending practices and their
email should be blocked or sent to the spam folder.
248

Enforcement FAQs
Q2. What should I do if I receive a probation or suspension notice for my

bounce rate?
Fix the underlying problem and appeal to get your case reevaluated. For information about the appeal
process, see the FAQs on probation and suspension. In your appeal, in addition to the information
requested in the probation and suspension FAQs, tell us the following:
The method you use to track your bounces
How you ensure that the email addresses of new recipients are valid prior to sending to them.
For example, which of the recommendations are you following in Q11. What can I do to minimize
bounces? (p. 250)
Q3. What types of bounces count toward my bounce rate?

Your bounce rate includes only hard bounces to domains you have not verified. Hard bounces are
permanent delivery failures such as "address does not exist." Temporary and intermittent failures such
as "mailbox full," or bounces due to blocked IP addresses, do not count toward your bounce rate.
Q4. Do you disclose the Amazon SES bounce rate limits that trigger probation
and suspension?
No, but you can find general bounce rate guidelines and tips on how to avoid bounces in the Amazon
Simple Email Service Email Sending Best Practices whitepaper.
Q5. Over what period of time is my bounce rate calculated?

We don't calculate your bounce rate based on a fixed period of time, because different senders send
at different rates. Instead, we look at what is called a representative volume, which represents a
reasonable amount of mail with which to evaluate your sending practices. To be fair to both highvolume and small-volume senders, the representative volume is different for each user and changes as
the user's sending patterns change.
Q6. Can I calculate my own bounce rate by using the information from the
Amazon SES console or the GetSendStatistics API?
No. The bounce rate is calculated using representative volume (see Q5. Over what period of time is
my bounce rate calculated? (p. 249)). Depending on your sending rate, your bounce rate can stretch
farther back in time than the Amazon SES console or GetSendStatistics can retrieve. In addition,
only emails to non-verified domains are considered when calculating your bounce rate. However, if you
regularly monitor your bounce rates using those methods, you should still have a good indicator that
you can use to catch problems before they get to levels that trigger a probation or suspension.
Q7. How can I find out which email addresses bounced?

Examine the bounce notifications that Amazon SES sends you. The email address to which Amazon
SES forwards the notifications depends on how you sent the original messages, as described at
Amazon SES Notifications Through Email (p. 107). You can also set up bounce notifications through
Amazon Simple Notification Service (Amazon SNS), as described at Monitoring Using Amazon SES
Notifications (p. 106). Note that simply removing bounced addresses from your list without any
additional investigation might not solve the underlying problem. For information about what you can do
to reduce bounces, see Q11. What can I do to minimize bounces? (p. 250).
Q8. If I haven't been monitoring my bounces, can you give me a list of

addresses that have bounced?
No. We cannot give you a comprehensive list. You should be regularly monitoring your bounces by
email or through Amazon SNS.
249

Enforcement FAQs
Q9. How should I handle bounces?

You need to remove bounced addresses from your mailing list and stop sending mail to them
immediately. If you are a small sender, it might be sufficient to simply monitor bounces through email
and manually remove bounced addresses from your mailing list. If your volume is higher, you will
probably want to set up automation for this process, either by programmatically processing the mailbox
where you receive bounces, or by setting up bounce notifications through Amazon SNS. For more
information, see Monitoring Using Amazon SES Notifications (p. 106).
Q10. Could my emails be bouncing because I've reached my sending limits?

No. Bounces have nothing to do with sending limits. If you try to exceed your sending limits, you will
receive an error from the Amazon SES API or SMTP interface when you try to send an email.
Q11. What can I do to minimize bounces?

First, be sure that you are aware of your bounces (see Q7. How can I find out which email addresses
bounced? (p. 249)). Then follow these guidelines:
Do not buy, rent, or share email addresses. Use only addresses that specifically requested your mail.
Remove bounced email addresses from your list.
When you ask for email addresses, ask twice and require a match to minimize typos.
Use double opt-in to sign up new users. That is, when a new users sign up, send them a
confirmation email that they need to click before receiving any additional mail. This prevents people
from signing up other people as well as accidental signups.
If you must send to addresses that you haven't mailed lately (and thus you can't be confident that
the addresses are still valid), do so only with a small portion of your overall sending. For more
information, see our blog post Never send to old addresses, but what if you have to?.
Ensure that you are not structuring signups to encourage people to use fictional addresses. Either do
not provide any value to new users until their email address is verified, or ask for their address only
when they specifically sign up to receive mail.
If you have an "email a friend" feature, be sure you use CAPTCHA or a similar mechanism to
discourage automated use of the feature, and do not allow arbitrary content to be inserted by the
user. For more information about CAPTCHA, see http://www.captcha.net/.
If you are using Amazon SES for system notifications, ensure that you are sending the notifications
to real addresses that can receive mail. Also consider turning off notifications that you do not need.
If you are testing a new system, be sure you are either sending to real addresses that can receive
email, or you are using the Amazon SES mailbox simulator. For more information, see Testing
Amazon SES Email Sending (p. 224).
Amazon SES Complaint FAQ

Q1. What is a complaint?
A complaint occurs when a recipient reports that they do not want to receive an email. They might
have clicked the "This is spam" button in their email client, complained to their email provider, notified
Amazon SES directly, or through some other method. This topic includes general information about
complaints. If your notification contains specific information about the source of the complaints, also
read the relevant topic: Amazon SES Complaints Through ISP Feedback Loops FAQ (p. 251),
Amazon SES Complaints Directly from Recipients FAQ (p. 253), or Amazon SES Complaints
Through Email Providers FAQ (p. 253).
Q2. Why do you care about my complaints?

High complaint rates are often used by entities such as ISPs, email providers, and anti-spam
organizations as indicators that a sender is sending to recipients who did not specifically sign up to
250

Enforcement FAQs
receive emails, or that the sender is sending content that is different from the type that recipients
signed up for.
Q3. What should I do if I receive a probation or suspension notice for my

complaint rate?
Review your list acquisition process and the content of your emails to try to understand why your
recipients might not appreciate your email. Once you have determined the cause, fix the underlying
problem and appeal to get your case reevaluated. For information about the appeal process, see the
FAQs on probation and suspension.
Q4. What can I do to minimize complaints?

First, be sure that you monitor the complaints that Amazon SES can notify you about, which are
complaints that Amazon SES receives through ISP feedback loops (see the Amazon SES Complaints
Through ISP Feedback Loops FAQ (p. 251)). Then follow these guidelines:
Use double opt-in to sign up new users. That is, when users sign up, send them a confirmation email
that they need to click before receiving any additional mail. This prevents people from signing up
other people as well as accidental signups.
Monitor engagement with the mail you send and stop sending to recipients who do not open or click
your messages.
When new users sign up, be clear about the type of email they will receive from you, and ensure
that you send only the type of mail that they signed up for. For example, if users sign up for news
updates, do not send them advertisements.
Ensure that your mail is well-formatted and looks professional.
Ensure that your mail is clearly from you and cannot be confused for something else.
Provide users an obvious and easy way to unsubscribe from your mail.
Amazon SES Complaints Through ISP Feedback Loops FAQ

This topic provides information about complaints that Amazon SES receives through feedback loops.
For general information that applies to all types of complaints, see the Amazon SES Complaint
FAQ (p. 250).
Q1. How is this type of complaint reported?

Most email client programs provide a button labeled "Mark as Spam," or similar, which moves the
message to a spam folder and forwards it to the ISP. Additionally, most ISPs maintain an abuse
address (e.g., [email protected]), where users can forward unwanted emails and request that the
ISP take action to prevent them. If the Amazon SES has a feedback loop (FBL) set up with the ISP,
then the ISP will send the complaint back to Amazon SES.
Q2. Are these complaints included in the complaint rate statistic shown in the Amazon SES
console and returned by the GetSendStatistics API?
Yes. Note, however, that the complaint rate statistic does not include complaints from ISPs that do
not provide feedback to Amazon SES. Nevertheless, the complaint rate from domains that provide
feedback is likely to be representative of the rest of your sending as well.
Q3. How can I be notified of these complaints?

You can be notified through email or through Amazon SNS notifications. See the set-up instructions in
251

Enforcement FAQs
Q4. What should I do if I receive a complaint notification through email or through Amazon
SNS?
First, you need to remove addresses that generated complaints from your mailing list and stop sending
mail to them immediately. Do not even send an email that says you have received the request to
unsubscribe. You will probably want to set up automation for this process, either by programmatically
processing the mailbox where you receive complaints, or by setting up complaint notifications through
Amazon SNS. For more information, see Monitoring Using Amazon SES Notifications (p. 106).
Then, take a close look at your sending to determine why your recipients do not appreciate the mail
you are sending, and address that underlying problem. For every person who complains, there are
potentially dozens who didn't appreciate your mail who did not (or were not able to) complain. If all you
do is remove the recipients who actually complain, you are not addressing the underlying problem with
your sending.
Q5. Do you disclose the Amazon SES complaint rate limits that trigger probation and
suspension?
No, but you can find general complaint rate guidelines and tips on how to avoid complaints in the
Q6. Over what period of time is my complaint rate calculated?

We don't calculate your complaint rate based on a fixed period of time, because different senders
send at different rates. Instead, we look at what is called a representative volume, which represents
a reasonable amount of mail with which to evaluate your sending practices. To be fair to both highvolume and small-volume senders, the representative volume is different for each user and changes
as the user's sending patterns change. Additionally, the complaint rate isn't calculated based on every
email. It is calculated as the percentage of complaints on mail sent to domains that send complaint
feedback to Amazon SES.
Q7. Can I calculate my own complaint rate by using metrics from the Amazon SES console or
the GetSendStatistics API?
No. There are two primary reasons for this:
The complaint rate is calculated using representative volume (see Q6). Depending on your
sending rate, your complaint rate can stretch farther back in time than the Amazon SES console or
GetSendStatistics can retrieve. However, if you regularly monitor your complaint rates using
those methods, you should still have a good indicator that you can use to catch problems before they
get to levels that trigger a probation or suspension.
When calculating complaint rate, not every email counts. Complaint rate is calculated as the
percentage of complaints on mail sent to domains that send complaint feedback to Amazon SES.
Q8. How can I find out which email addresses complained?

Examine the complaint notifications that Amazon SES sends you through email or through Amazon
SNS (see Monitoring Using Amazon SES Notifications (p. 106)). However, different ISPs provide
differing amounts of information, and some ISPs redact the complained recipient's email address
before passing the complaint notification to Amazon SES. To enable you to find the recipient's email
address in the future, your best option is to store your own mapping between an identifier and the
Amazon SES message ID that Amazon SES passes back to you when it accepts the email. Note that
Amazon SES does not retain any custom message IDs that you add.
Q9. If I haven't been monitoring my complaints, can you give me a list of addresses that have
complained?
Unfortunately, we can't give you a comprehensive list. However, you can monitor future complaints by
email or through Amazon SNS.
252

Enforcement FAQs
Q10. Can I get a sample email?

We cannot send you a sample email upon request, but you might find this information in the complaint
notification. See the answer to Q8.
Amazon SES Complaints Directly from Recipients FAQ

This topic provides information about complaints that Amazon SES receives directly from recipients.
For general information that applies to all types of complaints, see the Amazon SES Complaint
FAQ (p. 250).

Multiple recipients directly contacted Amazon SES about your mail through email or some other
means.
No. The complaint rate statistic you retrieve using the Amazon SES console or the
GetSendStatistics API only includes complaints that Amazon SES receives through ISP feedback
loops. For more information about those types of complaints, see the Amazon SES Complaints
Through ISP Feedback Loops FAQ (p. 251).
Q3. Why haven't I heard about these complaints through email feedback notifications or
through Amazon SNS?
Email feedback forwarding and Amazon SNS notifications only include complaints that Amazon SES
receives through ISP feedback loops. You will not receive notifications for complaints that recipients
filed directly with Amazon SES.

We are unable to disclose the addresses of recipients who complained, but we can say that it is more
than one recipient, and the number of complaints is significant when taking your current sending
volume into consideration. However, rather than focusing on removing individual recipients from
your list, you need to focus on finding and fixing the underlying problem. Start by reviewing your list
acquisition process and the content of your emails to try to understand why your recipients might not
appreciate your email.

Unfortunately, we are unable to provide an example of an email that triggered a recipient to directly
complain.
Q6. I have received a probation notice for direct recipient complaints. What should I do?
As soon as possible, fix your system so that your mailing list only includes recipients who have
specifically signed up to receive your mail, and ensure you are sending content that your recipients
actually want. Then, please email us with the details of your changes so that we can start the process
of re-evaluating your case. If three weeks pass and we don't hear from you at all, we will have to
disable your sending if we are still getting complaints about your mail.
Amazon SES Complaints Through Email Providers FAQ

This topic provides information about complaints that Amazon SES receives through email providers
(also called mailbox providers). For general information that applies to all types of complaints, see the
Amazon SES Complaint FAQ (p. 250).
253

Enforcement FAQs

An email provider reported to Amazon SES that a significant number of its customers marked your
emails as spam. The report was provided to Amazon SES through a means other than the feedback
loops described in the Amazon SES Complaints Through ISP Feedback Loops FAQ (p. 251).
No. The complaint rate statistic you retrieve using the Amazon SES console or the
GetSendStatistics API only includes complaints that Amazon SES receives through ISP feedback
loops.
Q3. Why haven't I heard about these complaints through email feedback notifications or
through Amazon SNS?
Email feedback forwarding and Amazon SNS notifications only include complaints that Amazon SES
receives through ISP feedback loops.

Email providers typically do not disclose this information. However, rather than focusing on removing
individual recipients from your list, you need to focus on finding and fixing the underlying problem. Start
by reviewing your list acquisition process and the content of your emails to try to understand why your
recipients might not appreciate your email.

No. Email providers typically do not provide an example email.
Q6. I have received a probation or shutdown notice for this type of complaint. What should I
do?
Fix your system so that your mailing list only includes recipients who have specifically signed up to
receive your mail, and ensure that the email content itself is something your recipients actually want.
Then, please email us with the details of your changes so that we can start the process of re-evaluating
your case. If you are on probation and three weeks pass and we don't hear from you at all, we will have
to disable your sending if we are still getting complaints about your mail. If you appealing a shutdown,
then the information you send us needs to convince us that if you start sending again, the problem will
no longer occur.
Amazon SES Spamtrap FAQ

Q1. What are spamtraps?
A spamtrap is a special email address maintained by an email provider, ISP, or anti-spam organization
that is guaranteed not to have a human being behind it. Because that address will never legitimately
be signed up to receive email, the organizations that maintain these spamtraps know that anyone who
sends mail to any of these addresses is likely engaging in questionable email practices.
Q2. How are spamtraps set up?

Spamtrap addresses can be set up in multiple ways. They can be converted from addresses that were
once valid, but have been unused (and bouncing) for an extended period of time. They can also be
addresses that were set up just to be spamtraps. They can be unusual addresses that are hard to
guess, and sometimes they are addresses that are close to real addresses (for example, introducing
a typo into a common domain name). Often, but not always, spamtraps are "seeded" into the world by
putting them on the internet in a variety of ways.
254

Enforcement FAQs
Q3. How does Amazon SES know if I am sending to spamtraps?

Certain organizations that operate spamtraps send Amazon SES notifications when their spamtraps
are hit by Amazon SES senders.
Q4. How does Amazon SES use the spamtrap reports?

We review the reports, and if we find enough evidence that you have a problem with sending to
spamtraps, we will put you on probation and ask you to fix the underlying problem. If you do not fix the
problem in the probation period, your account will be suspended. Also, if your spamtrap problem is very
severe, you might be immediately suspended without a probation period. As with any suspension, we
will send you a notification at that time.
Q5. What should I do if I receive a probation or suspension notice for sending

to spamtraps?
Fix the underlying problem and appeal to get your case reevaluated. For information about the appeal
process, see the FAQs on probation and suspension. Due to the way spamtrap sending is reported,
it will take a minimum of three weeks before we can confirm that a fix you have put in place has
succeeded.
Q6. How many spamtrap hits can I have before I am put on probation or
suspended?
Spamtrap hits are a very negative sign, so it takes only a small number of them to indicate that you are
engaging in questionable sending practices.
Q7. Do you disclose the spamtrap addresses?

No. Spamtrap organizations disclose only the occurrence of spamtrap hits, not the actual spamtrap
addresses. This is one of the measures they take to keep spamtrap addresses confidential and
effective.
Q8. What can I do to avoid sending to spamtraps?

To reduce the risk of sending to spamtraps, follow these guidelines:
Ensure that you ask for the email address twice to reduce the chance of typos.
Use double opt-in to sign up new users. That is, when users sign up, send them a confirmation email
that they need to click before receiving any additional mail.
Ensure that you remove addresses that hard bounce from your list, so that they are removed long
before they are converted to spamtraps.
Ensure that you are monitoring engagement by your recipients, and stop sending to recipients who
have not engaged with your emails or website recently. Time frames for what an "engaged user" is
depend on your use case, but generally speaking if users haven't opened or clicked your emails in
several months, you should consider removing them unless you have evidence that they do want
your mail.
Be very careful with reengagement campaigns where you intentionally contact people who have not
interacted with you recently. These efforts tend to be highly risky, and can often cause problems not
only with spamtrap sending, but also with bounces and complaints.
Send an opt-in message to your entire mailing list and keep only the recipients who click on the
verification link. In addition to removing inactive recipients from your list, this procedure will remove
spamtrap addresses as well. However, we do not recommend using this technique if you think
that your mailing list might contain a lot of bad addresses and/or you already have a problem with
bounces, because it might cause your bounce rate to reach the point at which your sending is put on
probation or shut down.
255

Enforcement FAQs
Amazon SES Manual Investigation FAQ

Q1. I received a probation or shutdown notice for a manual investigation. What
does that mean?
An Amazon SES investigator has identified a significant problem with your sending. Typical problems
include, but are not limited to, the following:
Your sending violates the AWS Acceptable Use Policy (AUP).
Your emails appear to be unsolicited.
Your content is associated with a use case that Amazon SES does not support.
If the problem is correctable, your account is put on probation and you are given a certain amount of
time (rather than a certain volume of mail, as with bounces and complaints) to correct the problem. If
the problem is uncorrectable, your account is suspended without a probation period.
Q2. Why would you do a manual investigation?

There are a variety of reasons. These include, but are not limited to, the following:
Recipients contact Amazon SES to complain about your emails.
We detect a significant change in your sending patterns.
The spam filters of Amazon SES flag a significant portion of your emails.
The probation or suspension notification indicates the issue at a high level. For some problems, we are
able to provide more specific details.
Q3. What are "unsolicited" emails?

Unsolicited emails are emails that the recipient did not specifically sign up for. This includes cases in
which a recipient signs up for a certain type of mail (for example, notifications), and instead is sent a
different type of mail (for example, advertisements). If the probation or suspension notice indicates that
unsolicited sending is your problem, you should provide the following information in your appeal:
Are all the messages that you send specifically requested by the recipient, and do they comply with
the AUP?
Have you acquired email addresses in any way other than a customer specifically interacting with
you or your website and requesting emails from it? You should explain how you accumulated your
mailing list.
How do your subscribe and unsubscribe processes work? You should include your opt-in and opt-out
links.
Also, feel free to provide any other information you might have to assure us that your email list was
accumulated and is managed using the practices described in the Amazon Simple Email Service Email
Sending Best Practices whitepaper.
Q4. What should I do if I receive a probation or suspension notice for a manual

investigation?
As with any probation or suspension, fix the underlying problem that is causing the issue specified
in the probation or suspension notice, and then appeal to get your case reevaluated. For information
about the appeal process, see the FAQs on probation and suspension.
256

IP Blacklist FAQ
Q5. What types of problems do you view as "correctable?"

Generally, we believe the situation is correctable if you have a history of good sending practices,
and if there are steps you can take to eliminate the problematic sending while continuing the bulk
of your sending. For example, if you are sending three different types of email and only one type is
problematic, you might be able to simply stop the problematic sending and continue with the rest of
your sending.
Q6. What if I cannot find the source of the problem?

You can respond to the notification (or email [email protected] from the email address
associated with your AWS account) and request a sample of the mail that caused the issue.
Amazon SES IP Blacklist FAQ

Mailbox providers aim to protect their users from receiving spam. To determine whether an incoming
email is spam, mailbox providers examine various characteristics of the email. One of the methods
they use is to check whether the IP address that sent the email is on an IP blacklist. An IP blacklist,
also known as realtime blackhole list (RBL) or DNS-based blackhole list (DNSBL), is a list of IP
addresses suspected to send spam. If the IP address from which the email was sent is on a blacklist
that a mailbox provider uses, the mailbox provider might bounce the email or drop it entirely. Various
organizations compile blacklists. Mailbox providers choose which of these blacklists they use. Some
blacklists are more widely used than others.
As with IP addresses of other email service providers, Amazon SES IP addresses occasionally appear
on blacklists. This topic describes how blacklists impact your sending with Amazon SES.
Note
This topic is about blacklists that mailbox providers use to block incoming mail from email
service providers such as Amazon SES. If you are looking for information about how Amazon
SES blocks outgoing mail to recipient addresses that have previously bounced, see Removing
an Email Address from the Amazon SES Suppression List (p. 236).
Q1. How do I know if blacklisting is preventing recipients from

receiving my emails?
If your sending is impacted by the blacklisting of an Amazon SES IP address, you will most likely
receive a bounce notification (p. 106) that contains a message indicating that your email was rejected
because of a listing on a blacklist. In most cases, the bounce message includes the name or URL of
the blacklist. An example of this type of message is "Message rejected due to IP [0.0.0.0] listed on RBL
[X]". If you do not see this type of message in your bounce notifications, it is unlikely that a blacklist is
impacting your sending.
Q2. What does Amazon SES do about blacklisting?

We carefully and continually monitor the reputation of our IP address space. We work closely with
mailbox providers and blacklist operators to identify and mitigate blacklistings in parallel with our
routine compliance processes to remove offending users from our system.
Blacklist operators set their own listing and delisting policies, which do not always comply with the
recommendations in RFC 6471, so we cannot provide a guarantee or timeframe in which a blacklisting
will be resolved. In particular, we are aware that portions of our IP address space are sometimes listed
on SORBS and UCEPROTECT. We frequently work with blacklist data to mitigate and resolve the
listings, but we cannot estimate the time to resolution.
There are some blacklists, such as SORBS and SpamCannibal, that we are not currently working with
to resolve listings. Our data indicates that the impact of these blacklists is extremely low. We are not
257

IP Blacklist FAQ
aware of any major mailbox provider using SORBS or SpamCannibal to reject messages. If you are
particularly concerned about SORBS, we recommend doing an internet search of "SORBS reliability" to
get an idea of why ISPs should never use this blacklist as the sole criteria for rejecting mail.
Q3. Are all blacklists equally important?

No. Large mailbox providers typically use reputable blacklists such as Spamhaus, whereas smaller
mailbox providers who aren't aware of which blacklists are reputable might use less reputable
blacklists. A Spamhaus listing is likely to result in mail being blocked at major mailbox providers, while
a listing on SORBS, UCEPROTECT, or SpamCannibal might not have much impact on your sending.
A service that asks you to pay for delisting or does not accept delist requests is unlikely to be used by
major mailbox providers.
Q4. What should I do if I notice that an Amazon SES IP

address is on a blacklist?
Rest assured that we are aware of the listing, and are working towards a resolution. However,
remember that if you do not receive bounce notifications that contain a message about blacklisting, it is
very unlikely that a blacklisting is impacting your sending. If your bounce notifications do indicate that
a SORBS, UCEPROTECT, or SpamCannibal listing is impacting your sending, we recommend that
you contact the mailbox provider and make sure that it is not using any of these as the sole criteria for
blocking IP addresses.
Q5. Emails I send are being put in the junk folder. Could this
be because an Amazon SES IP address is on a blacklist?
It is unlikely that your sending is impacted by blacklisting unless your bounce notifications contain a
message indicating that blacklisting is the reason for the rejection of the message.

258

Email-Receiving Concepts
Receiving Email with Amazon SES

Amazon Simple Email Service (Amazon SES) is a mail server that can both send and receive mail
on behalf of your domain. When you use Amazon SES to receive your mail, Amazon SES handles
underlying mail-receiving operations, such as:
communicating with other mail servers
scanning for spam and viruses
rejecting mail from untrusted sources
accepting mail for recipients in your domain
As part of the AWS infrastructure, Amazon SES can also take action on your mail, such as delivering
it to an Amazon S3 bucket, publishing it to an Amazon SNS topic, calling your custom code through
AWS Lambda, integrating with Amazon WorkMail, or bouncing the mail back to the sender.
The following sections contain the information you need to understand, set up, and use Amazon SES
to receive your mail.
Email-Receiving Concepts (p. 259)
Getting Started Receiving Email (p. 261)
Setting Up Email Receiving (p. 273)
Managing Email Receiving (p. 290)
Amazon SES Email-Receiving Concepts

When you use Amazon SES as your email receiver, you must tell the service what to do with your mail.
The primary method, which gives you fine-grained control over your mail, is to specify the actions to
take based on the recipient. The other method is to block or allow mail based on the originating IP
address. This topic describes both methods.
Recipient-Based Control
The primary way to control your incoming mail is to specify how mail is handled based on its recipient.
For example, if you own example.com, you can specify that mail for [email protected] should
259

IP Address-Based Control
bounce, and that all other mail for example.com and its subdomains should be delivered. The list of
recipients you provide is called the condition.
You set up receipt rules to specify how to handle the mail when a condition is satisfied. A receipt rule
consists of a condition and an ordered list of actions. If the recipient to whom the incoming mail is
addressed matches a recipient specified in the condition, then Amazon SES performs the actions
specified in the rule. The following actions are available:
S3 actionDelivers the mail to an Amazon S3 bucket and, optionally, notifies you through Amazon
SNS.
SNS actionPublishes the mail to an Amazon SNS topic.
Note
The SNS action includes a complete copy of the email content in the Amazon SNS
notifications. The other Amazon SNS notifications mentioned here simply notify you of email
delivery; they contain information about the email, not the email content itself.
Lambda actionCalls your code through a Lambda function and, optionally, notifies you through
Amazon SNS.
Bounce actionRejects the email by returning a bounce response to the sender and, optionally,
notifies you through Amazon SNS.
Stop actionTerminates the evaluation of the receipt rule set and, optionally, notifies you through
Amazon SNS.
Add header actionAdds a header to the received email. You typically use this action only in
combination with other actions.
WorkMail actionHandles the mail with Amazon WorkMail. You will typically not use this action
directly because Amazon WorkMail takes care of the setup.
Receipt rules are grouped together into receipt rule sets. You can define multiple receipt rule sets for
your AWS account, but only one receipt rule set is active at any time. The following figure shows how
receipt rules, receipt rule sets, and actions relate to each other.
IP Address-Based Control
You can control your mail flow on a broader level by setting up IP address filters. IP address filters
are optional and enable you to specify whether to accept or reject mail originating from an IP address
or range of IP addresses. Your IP address filters can include block lists (IP addresses from which
you want to block incoming mail) and allow lists (IP addresses from which you want to always accept
mail). IP address filters are useful for blocking spam. Amazon SES maintains its own block list of
IP addresses known to send spam, but you can choose to receive mail from those IP addresses by
adding them to your allow list.
260

Email-Receiving Process
Note
If you want to allow mail that originates from an Amazon EC2 IP address, you must add it to
your allow list. All mail originating from Amazon EC2 is blocked by default.
Email-Receiving Process
When Amazon SES receives an email for your domain, the following events occur:
1. Amazon SES first looks at the IP address of the sender. Amazon SES allows the mail to pass this
stage unless:
The IP address is in your block list.
The IP address is in the Amazon SES block list and not on your allow list.
2. Amazon SES examines your active receipt rule set to determine whether any of your receipt rules
contain a condition that matches any of the incoming email's recipients.
3. If there aren't any matches, Amazon SES rejects the mail. Otherwise, Amazon SES accepts the
mail.
4. If Amazon SES accepts the mail, it evaluates your active receipt rule set. All of the receipt rules that
match at least one of the recipient conditions are applied in the order that they are defined, unless
an action or a receipt rule explicitly terminates evaluation of the receipt rule set.
Now that you have an overview of the process, you can get started by going to Setting Up Email
Receiving (p. 273).
Getting Started Receiving Email with Amazon

SES
In this tutorial, you will set up Amazon SES to receive email for a domain that you have registered with
Amazon Route 53, and deliver the email to an Amazon S3 bucket.
Topics
Step 1: Before You Begin (p. 261)
Step 2: Verify Your Domain (p. 262)
Step 3: Set up a Receipt Rule (p. 265)
Step 4: Send an Email (p. 269)
Step 5: View the Received Email (p. 269)
Step 6: Clean Up (p. 273)
Step 1: Before You Begin

Before you can start this tutorial, you must sign up for an AWS account (if you don't already have one),
and register the domain you want to receive email for with Amazon Route 53. The following sections
describe where to accomplish those tasks.
Sign Up
If you already have an AWS account, skip to the next section: Register a Domain with Amazon Route
53 (p. 262). Otherwise, follow these steps.
261

Step 2: Verify Your Domain
To sign up for an AWS account

1.
Open https://aws.amazon.com/, and then choose Create an AWS Account.
2.
Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone
keypad.
Register a Domain with Amazon Route 53

In this tutorial, you will receive email for a domain that you have registered with Amazon Route 53. To
get this domain, you can either register a new domain or transfer an existing domain. Transferring an
existing domain can take several days.
Next step: Step 2: Verify Your Domain (p. 262)

Before you can receive email for a domain using Amazon SES, you must prove that you own the
domain by verifying it with Amazon SES. Although Amazon SES enables you to verify single email
addresses, you must verify a domain if you want to use Amazon SES for email receiving. You can
verify and receive email with Amazon SES for any domain that you own, but it is easier to set up a
domain that you have registered with Amazon Route 53.
To verify a domain with Amazon SES

1.
Sign in to the AWS Management Console using the AWS account that you used to register
your domain with Amazon Route 53, and open the Amazon SES console at https://
2.
In the left navigation pane, under Identity Management, choose Domains. Then, in the content
pane, choose Verify a New Domain.
3.
Enter the name of the domain that is registered in Amazon Route 53, leave Generate DKIM
Settings unselected (it is for email sending), and then choose Verify This Domain.
262

4.
On the Verify a New Domain page, which displays the records you must add to your DNS server,
choose Use Route 53.
Note
If you do not see Use Route 53, then your domain is not registered with Amazon Route
53, which is a prerequisite for this tutorial.
5.
On the Use Route 53 page, choose Domain Verification Record, choose Email Receiving
Record, and choose the hosted zone you want to use.
Important
If you have already set up mail exchanger (MX) records for your domain, the next step will
replace your old MX records with new records. MX records specify the mail server that
you want to accept emails on behalf of your domain.

263

6.
Choose Create Record Sets. You will go back to the Domain Identities list.
7.
Wait a few minutes, and then refresh the Domain Identities list by using the refresh button near
the top right of the content pane. Confirm that the status of the domain is verified.
Next step: Step 3: Set up a Receipt Rule (p. 265)

264

Step 3: Set up a Receipt Rule

To use Amazon SES as your email receiver, you must have at least one active receipt rule set. A
receipt rule set is an ordered collection of receipt rules that specify what Amazon SES should do with
mail it receives across all of your verified domains. Because you are setting up email receiving with
Amazon SES for the first time, Amazon SES automatically creates a default receipt rule set for you, so
you can jump into creating a receipt rule. The receipt rule you create will belong to the default receipt
rule set.
To create a receipt rule

1.
In the left navigation pane, under Email Receiving, choose Rule Sets. Then, in the content pane,
choose Create a Receipt Rule.
2.
On the Recipients page, choose Next Step. Because you aren't adding any recipients, this
receipt rule will handle mail for all recipients in all of your verified domains.

265

3.
From the Add action menu, choose S3.
4.
For S3 bucket, choose Create S3 bucket.

266

5.
For Bucket Name, enter a new bucket name. Bucket names must comply with the following
requirements.
Can contain lowercase letters, numbers, periods (.), and hyphens (-).
Must be unique across all of AWS.
Must start with a number or letter.
Must be between 3 and 63 characters long.
Must not contain underscores (_), end with a hyphen, or be formatted as an IP address (e.g.,
192.168.5.4).
Cannot contain two, adjacent periods or dashes next to periods.
Next, choose Create Bucket.
Note
Because you are creating the Amazon S3 bucket using the Amazon SES console,
Amazon SES automatically sets up the policy required to give Amazon SES permission to
write to the bucket. However, if you choose an Amazon S3 bucket that already exists, you
267

must explicitly give Amazon SES permission to write to the bucket by attaching a policy to
the bucket using the Amazon S3 console or API.
6.
Leave all other options at their default settings for the simplicity of this tutorial, and choose Next
Step.
7.
On the Rule Details page, for the rule name, type my-rule, leave all other options at their default
settings, and then choose Next Step.
8.
On the Review page, choose Create Rule.

268

Step 4: Send an Email
Next step: Step 4: Send an Email (p. 269)
Step 4: Send an Email

Sign in to the email client that you use to send email, and then send an email to an email address in
the domain for which you set up email receiving.
Next step: Step 5: View the Received Email (p. 269)
Step 5: View the Received Email

1. In the upper left of the AWS Management Console, choose the AWS icon, and then, under Storage
& Content Delivery, choose S3.

269

2. In the Amazon S3 console, choose the bucket that you created when you set up Amazon SES email
receiving earlier in this tutorial.

270

3. In the bucket, find the received email. The name of the email will be an alphanumeric string. The
bucket will also contain an item with the name AMAZON_SES_SETUP_NOTIFICATION, which you
can ignore.
4. To download the email to your computer, choose the box to the left of the email, and then choose
Download from the menu.

271

5. Open the email in a text editor. The email will be in a raw format, which is typically Multipurpose
Internet Mail Extensions (MIME). To decode MIME, you must use your own application.

272

Step 6: Clean Up
Next step: Step 6: Clean Up (p. 273)
Step 6: Clean Up
After you have completed this tutorial, you should clean up the following settings and resources to
avoid incurring additional charges.
Amazon SES Receipt Rule Set

If you no longer want Amazon SES to receive mail for your domain, you must disable your active
receipt rule set (p. 291).
Amazon S3 Bucket
If you no longer want the Amazon S3 bucket that you created, you can delete it. However, you cannot
delete an Amazon S3 bucket that has items in it, so you must first delete the contents of the bucket,
and then delete the bucket. For more information about deleting folders and buckets, see Delete an
Object and Bucket in the Amazon S3 Getting Started Guide.
Amazon Route 53 Domain

If you no longer want Amazon Route 53 to register your domain, you can delete the registration or
transfer your domain to another registrar.
Setting Up Amazon SES Email Receiving

This section describes what you need to do to configure Amazon SES to receive your mail. For
example, you should first consider how you want to receive, filter, and process your mail, because
those decisions will affect how you configure Amazon SES. You also need to verify your domain with
Amazon SES to prove that you own it, and point your domain to Amazon SES for incoming mail.
Another step is to give Amazon SES permission to access any required AWS resources. Then you
configure email receiving by creating a receipt rule set, receipt rules, and optionally, IP address filters.
All of these steps are explained in the following topics.
1. Considering Your Use Case (p. 273)
2. Verifying Your Domain (p. 275)
3. Publishing an MX Record (p. 276)
4. Giving Permissions (p. 276)
5. Creating IP Address Filters (p. 278)
6. Creating a Receipt Rule Set (p. 279)
7. Creating Receipt Rules (p. 279)
To see where these tasks fit into the overall email-receiving process, see Email-Receiving
Concepts (p. 259).
Considering Your Use Case for Amazon SES Email

Receiving
Before you set up Amazon SES to receive your mail, you might find it helpful to consider the following
questions.
273

Considering Your Use Case
Email Content
How do you want Amazon SES to pass you the email content?
Amazon SES can provide you the email content in two ways: it can store the emails in an Amazon
S3 bucket that you specify, or it can send you an Amazon SNS notification that contains a copy of
the email. Amazon SES delivers you the raw, unmodified email, which is typically in Multipurpose
Internet Mail Extensions (MIME) format. For more information about MIME format, see RFC 2045.
How large of a limit on email size do you need?
If you choose to store emails in an Amazon S3 bucket, the maximum email size (including headers)
is 30 MB. If you choose to receive your emails through Amazon SNS notifications, the maximum
email size (including headers) is 150 KB.
How do you want to trigger the processing of your mail?
After your mail is delivered, you will want to process it with your own code. For example, your
application might convert the base 64-encoded email into a displayable format and then make
it available to an end user through an email client. There are a couple of ways you can start the
process:
If your emails are delivered to Amazon S3, your application can listen for Amazon SNS
notifications generated by S3 actions, extract the message ID of the email from the notifications,
and then use the message ID to retrieve the email from Amazon S3.
Alternatively, you can incorporate email processing into your receipt rules by writing a Lambda
function. In this case, your receipt rule should first write the email to Amazon S3, and then trigger
the Lambda function. Lambda actions can be executed synchronously or asynchronously from
within your receipt rules, depending on whether the Lambda function needs to return a result that
influences how other actions are executed. We recommend that you use asynchronous execution
unless synchronous is absolutely necessary for your use case. For more information about AWS
Lambda, see the AWS Lambda Developer Guide.
If your emails are delivered through an Amazon SNS notification by using the SNS action, your
application can listen for Amazon SNS notifications, and then extract the email messages from the
notifications.
Do you want the emails to be encrypted?
Amazon SES integrates with AWS Key Management Service (AWS KMS) to optionally encrypt the
mail it writes to your Amazon S3 bucket. Amazon SES uses client-side encryption to encrypt your
mail before writing it to Amazon S3. This means that you must decrypt the content on your side
after retrieving the mail from Amazon S3. The AWS SDK for Java and AWS SDK for Ruby provide a
client that can handle the decryption for you. Amazon SES can encrypt the emails for you only if you
choose for your emails to be delivered to an Amazon S3 bucket.
Unwanted Mail
At what point in the email-receiving process do you want to reject unwanted mail?
You can reject emails at two points in the email-receiving process: during the SMTP conversation
with the sender's mail server, and after delivery when you can examine the email's properties. You
are not billed for any mail that is rejected during the SMTP conversation, so it is to your advantage
to reject as much unwanted mail as possible at that time. You can reject emails during the SMTP
conversation with IP address filters and receipt rules, both of which are described in Email-Receiving
Concepts (p. 259).
After the SMTP conversation, Amazon SES performs virus scanning, spam scanning, and
authentication checks for DomainKeys Identified Mail (DKIM) and Sender Policy Framework (SPF)
and makes the verdicts available to you so you can decide whether you trust the email. If you don't
274

Verifying Your Domain
trust the email, you can drop it or send a bounce response to the sender. You will be billed for the
email because this decision point occurs after Amazon SES delivered the email to you.
Do you want to filter your emails based on any property other than recipient or IP address?
You can write complex message-matching conditions using synchronously-executed Lambda
functions (invoked as "RequestResponse") and then incorporate the Lambda functions into your
receipt rules. The return value of the Lambda function indicates whether the evaluation of the receipt
rule and receipt rule set should continue. For example, you can have a receipt rule that drops mail
that Amazon SES flags as spam.
Using Other AWS Services

Have you set up the appropriate permissions?
If you want your mail to be delivered to an Amazon S3 bucket, published to an Amazon SNS topic
you don't own, trigger a Lambda function, or use a custom master AWS KMS key, you need to
give Amazon SES permission to access those resources. To give Amazon SES access, you create
policies on resources from the consoles or APIs for those AWS services. For more information
Giving Permissions (p. 276).
Mail Streams
How do you want to divide your mail stream?
Your domain most likely receives different classes of mail. For example, some of your domain's mail,
such as an email to [email protected], might be intended for a personal inbox. Other mail, such
as an email to [email protected], might be better directed to automated systems instead.
You can use receipt rules to divide your incoming mail so that it can be processed differently. For
information about how to set up receipt rules, see Creating Receipt Rules (p. 279).
Verifying Your Domain for Amazon SES Email

Receiving
As with any domain you want to use for sending or receiving email with Amazon SES, you must first
prove that you own it. The verification procedure, which includes initiating domain verification with
Amazon SES and then publishing a TXT record to your DNS server, is described in Verifying Domains
in Amazon SES (p. 41).
Note
Although Amazon SES enables you to verify single email addresses, you must verify a domain
if you want to use Amazon SES for email receiving.
You can also start the domain verification process when you set up receipt rules in Creating Receipt
Rules (p. 279). The recipient list will indicate which recipients are not verified, and enable you to
initiate verification. In any case, you must complete domain verification by publishing a TXT record to
your DNS server, as described in Amazon SES Domain Verification TXT Records (p. 45).
You can confirm that your email address or domain is verified by looking at its status in the Email
Address Identities or Domain Identities list in the Amazon SES console or by using the Amazon
SES GetIdentityVerificationAttributes API.

275

Publishing an MX Record
Publishing an MX Record for Amazon SES Email

Receiving
A mail exchanger (MX) record is a record on your domain's name server that points to a mail server
to handle your domain's email. To specify Amazon SES as your email receiver, you can publish an
MX record to point to the Amazon SES email-receiving endpoint for the region you want to use. (For
example, the endpoint for US West (Oregon) is inbound-smtp.us-west-2.amazonaws.com.) For a list of
Amazon SES endpoints, see Regions and Amazon SES (p. 332).
Although you are not required to publish an MX record to receive mail through Amazon SES, if you
don't publish the record, Amazon SES will receive mail for your domain only if you explicitly route it to
Amazon SES.
Giving Permissions to Amazon SES for Email

Receiving
To enable Amazon SES to write emails to your Amazon S3 bucket, use an AWS KMS key to encrypt
your emails, call your Lambda function, or publish to an Amazon SNS topic of another account,
Amazon SES must have permission to access those resources. You give permission by attaching a
policy to the resource. This topic provides example policies.
Give Amazon SES Permission to Write to Your Amazon S3

Bucket
To allow Amazon SES to write to your Amazon S3 bucket, use the Amazon S3 console or API to
attach a policy to the bucket. The following policy gives Amazon SES permission to write objects to an
Amazon S3 bucket. Replace ACCOUNT-ID-WITHOUT-HYPHENS with your 12-digit AWS account ID,
and BUCKET-NAME with the name of your Amazon S3 bucket. For more information about attaching
policies to Amazon S3 buckets, see the Amazon Simple Storage Service Developer Guide.
{
"Version": "2008-10-17",
"Statement": [
{
"Sid": "GiveSESPermissionToWriteEmail",
"Effect": "Allow",
"Principal": {
"Service": [
"ses.amazonaws.com"
]
},
"Action": [
"s3:PutObject"
],
"Resource": "arn:aws:s3:::BUCKET-NAME/*",
"Condition": {
"StringEquals": {
"aws:Referer": "ACCOUNT-ID-WITHOUT-HYPHENS"
}
}
}
]
}

276

Giving Permissions
Give Amazon SES Permission to Use Your AWS KMS Master

Key
For Amazon SES to encrypt your emails, it must have permission to use the AWS KMS key that you
specified when you set up your receipt rule. You can either use the default master key (aws/ses) in
your account or a custom master key you create. If you use the default master key, you don't need
to perform any steps to give Amazon SES permission to use it. If you use a custom master key, you
need to give Amazon SES permission to use it by adding a statement to the key's policy. The policy
statement includes conditions that are designed to ensure that Amazon SES can only use your custom
master key when certain values are present in the request to AWS KMS; specifically:
aws:ses:source-accountThe AWS account ID on behalf of which Amazon SES received the
email.
aws:ses:message-idThe Amazon SES message ID of the received email.
aws:ses:rule-nameThe name of the receipt rule that was used to encrypt the email.
Paste the following policy statement into the key policy to permit Amazon SES to use your custom
master key when Amazon SES receives email on behalf of your AWS account. Replace ACCOUNT-IDWITHOUT-HYPHENS with your 12-digit AWS account ID.
{
"Sid": "AllowSESToEncryptMessagesBelongingToThisAccount",
"Effect": "Allow",
"Principal": {"Service":"ses.amazonaws.com"},
"Action": ["kms:Encrypt", "kms:GenerateDataKey*"],
"Resource": "*",
"Condition": {
"Null": {
"kms:EncryptionContext:aws:ses:rule-name": "false",
"kms:EncryptionContext:aws:ses:message-id": "false"
},
"StringEquals": {
"kms:EncryptionContext:aws:ses:source-account": "ACCOUNT-IDWITHOUT-HYPHENS"
}
}
}
For more information about attaching policies to AWS KMS keys, see the AWS Key Management
Service Developer Guide.
Give Amazon SES Permission to Invoke Your Lambda

Function
To enable Amazon SES to call your Lambda function, you can either configure the Lambda function
using the Amazon SES console during receipt-rule setup (in which case Amazon SES automatically
adds the necessary permissions to the function) or you can use the AWS Lambda AddPermission
API to attach a policy to the function. The following AddPermission API call gives Amazon SES
permission to invoke your Lambda function. Replace ACCOUNT-ID-WITHOUT-HYPHENS with your 12digit AWS account ID. For more information about attaching policies to Lambda functions, see the
AWS Lambda Developer Guide.
{
"Action": "lambda:InvokeFunction",
277

Creating IP Address Filters
"Principal": "ses.amazonaws.com",
"SourceAccount": "ACCOUNT-ID-WITHOUT-HYPHENS",
"StatementId": "GiveSESPermissionToInvokeFunction"
}
Give Amazon SES Permission to Publish to an Amazon SNS

Topic of Another Account
If the Amazon SNS topic you want to use is owned by the same AWS account you are using for
Amazon SES, no setup is required to allow Amazon SES to publish to the topic. However, if you want
to publish notifications to a topic that you do not own, use the Amazon SNS console or API to attach a
policy to the Amazon SNS topic. The following policy gives Amazon SES permission to publish to an
Amazon SNS topic. Replace ACCOUNT-ID-WITHOUT-HYPHENS with your 12-digit AWS account ID,
and TOPIC-NAME with the name of the Amazon SNS topic. For more information about writing policies
for Amazon SNS topics, see the Amazon Simple Notification Service Developer Guide.
{
"Version": "2008-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "ses.amazonaws.com"
},
"Action": "SNS:Publish",
"Resource": "arn:aws:sns:us-east-1:ACCOUNT-ID-WITHOUTHYPHENS:TOPIC-NAME"
}
]
}
Creating IP Address Filters for Amazon SES Email

Receiving
An IP address filter enables you to optionally specify whether to accept or reject mail originating from
an IP address or range of IP addresses.
You can use the Amazon SES console or the CreateReceiptFilter API to create an IP address
filter.
Note
If you only want to receive mail from a finite list of known IP addresses, then set up a block
list that contains 0.0.0.0/0, and set up an allow list that contains the IP addresses that you
trust. This configuration blocks all IP addresses by default, and only allows mail from the IP
addresses that you explicitly specify.
To create an IP address filter (console)

1.
2.
3.
4.
In the left navigation pane, under Email Receiving, choose IP Address Filters.
In the content pane, choose Create Filter.
For Filter Name, type a name for the IP address filter. The name must contain less than 64
alphanumeric, hyphen (-), underscore (_), and period (.) characters. The name must start and end
with a letter or number.
278

Creating a Receipt Rule Set
5.
For IP Address Range, type a single IP address or a range of IP addresses that you want to block
or allow, specified in Classless Inter-Domain Routing (CIDR) notation. An example of a single IP
address is 10.0.0.1. An example of a range of IP addresses is 10.0.0.1/24. For more information
about CIDR notation, see RFC 2317.
6.
For Policy Type, choose Allow or Block.
7.
Choose Create Filter.
For information about how to use the CreateReceiptFilter API to create an IP address filter, see
the Amazon Simple Email Service API Reference.
Creating a Receipt Rule Set for Amazon SES Email

Receiving
A receipt rule set is an ordered collection of receipt rules that specify what Amazon SES should do
with mail it receives across all of your domains. To use Amazon SES as your email receiver, you must
create at least one receipt rule set for your account. You can set up multiple receipt rule sets, but only
one receipt rule set in each AWS region can be active at any given time. For more information about
the role of receipt rule sets in the email-receiving process, see Email-Receiving Concepts (p. 259).
Note
If you do not want to use Amazon SES as your email receiver, simply disable all of your
receipt rule sets. For information about how to disable receipt rule sets, see Managing Receipt
Rule Sets (p. 291).
You can use the Amazon SES console or API to create a receipt rule set.
Using the Amazon SES console
Receipt rules exist in receipt rule sets only, so to create a receipt rule set, you can start by creating
a receipt rule. For more information, see Creating Receipt Rules (p. 279). When you reach the
end of this procedure, you can create a new receipt rule set.
Copy an existing receipt rule set as explained in Managing Receipt Rule Sets (p. 291).
In the left navigation pane, under Email Receiving, choose Rule Sets, and then choose Create a
New Rule Set.
Using the Amazon SES APIUse the CreateReceiptRuleSet API to create an empty receipt
rule set, as described in the Amazon Simple Email Service API Reference. Then, you can use the
Amazon SES console or the CreateReceiptRule API to add receipt rules to it.
Creating Receipt Rules for Amazon SES Email

Receiving
A receipt rule enables you to specify what you want Amazon SES to do with mail it receives for one or
more recipients or domains. The receipt rule consists of a condition and an ordered list of actions. If the
recipient to which the incoming mail is addressed matches a recipient specified in the condition, then
Amazon SES performs the actions specified in the receipt rule. For more information about the role of
receipt rules in the email-receiving process, see Email-Receiving Concepts (p. 259).
Note
Receipt rules exist in receipt rule sets only, which is why you must have at least one receipt
rule set. Each receipt rule can belong to only one receipt rule set.
This topic shows you how to create a receipt rule and describes options for each action type.
279

Creating Receipt Rules
Setting Up a Receipt Rule

You can use the Amazon SES console or the CreateReceiptRule API to create rules.
To create a receipt rule (console)

1.
2.
In the left navigation pane, under Email Receiving, choose Rule Sets.
3.
Choose a receipt rule set. For example, to go to your active receipt rule set, choose View Active
Rule Set. If you have not created any receipt rule sets yet, you can create one by choosing Create
a New Rule Set.
4.
From your receipt rule set, choose Create Rule.
5.
Use the following procedure to add one or more recipients. Collectively, these recipients are the
condition. You can have a maximum of 100 recipients per receipt rule.
a.
Under Recipients, type an email address or domain that you own. You may use a leading dot
to capture all subdomains of a domain. Using example.com for demonstration purposes:
To match a specific [email protected]. This will match any form of the address
with a label. Addresses that contain labels are of the form [email protected], with
user-specified text between the plus sign (+) and the at sign (@). If you specify a label, then
only messages with the same label will match.
For example, if you want a receipt rule to apply to [email protected], ticket
[email protected], and [email protected], simply set the recipient of the receipt
rule to [email protected]. In contrast, if you set the recipient of the receipt rule to ticket
[email protected], then the rule will only apply to [email protected] it will not
capture [email protected] and [email protected].
To match all addresses within a domain but not its subdomainsexample.com
To match all addresses within all subdomains, but not the domain itself.example.com
(note the leading period)
To match all addresses within a domain and all of its subdomainsTwo recipients:
example.com, .example.com
All recipients within all verified domainsEmpty. (Do not specify any recipients.)
6.
7.
b.
Choose Add Recipient.
c.
If you have not yet verified the domain of the recipient, choose Verify. To complete domain
verification, you need to publish a TXT record to your DNS server, as described in Verifying
d.
Add additional recipients as needed, and then choose Next Step.
Use the following procedure to add one or more actions to the receipt rule.
a.
Choose an action from the menu.
b.
Choose the action settings. For information about the options for each action, see Action
Options (p. 281).
c.
Add additional actions as needed, and then choose Next Step.
For Rule Details, use the following procedure to choose settings.

a.
For Rule Name, type a name for the receipt rule. The name must contain less than 64
alphanumeric, hyphen (-), underscore (_), and period (.) characters. The name must start and
end with a letter or number.
b.
If you want to enable the receipt rule, leave the Enabled option selected.
c.
If you want Amazon SES to reject any incoming emails that are not sent over a connection
that is encrypted with Transport Layer Security (TLS), select TLS.
280

d.
If you want Amazon SES to scan incoming emails for spam and viruses, select Enable Spam
and Virus Scanning.
8.
For Rule Set, choose an existing receipt rule set or click Create New Rule Set.
9.
For Rule Position, choose where to place the receipt rule in the ordered list of receipt rules. The
receipt rules are evaluated sequentially.
10. Choose Next Step, and then choose Create Rule.

For information about how to use the CreateReceiptRule API to create rules, see the Amazon
Action Options
Each receipt rule for Amazon SES email receiving contains an ordered list of actions. The overall
setup procedure for receipt rules is described in Creating Receipt Rules for Amazon SES Email
Receiving (p. 279). This section describes the specific options for each action type.
The action types are the following:
Add Header Action (p. 281)
Bounce Action (p. 281)
Lambda Action (p. 282)
S3 Action (p. 288)
SNS Action (p. 289)
Stop Action (p. 289)
WorkMail Action (p. 290)
Add Header Action

The Add Header action adds a custom header to the received email. You typically use this action only
in combination with another action. This action has the following options.
Header nameThe name of the header to add. It must be between 1 and 50 characters, inclusive,
and consist of alphanumeric (a-z, A-Z, 0-9) characters and dashes only.
Header valueThe value of the header to add. It must be less than 2048 characters, and must not
contain newline characters ("\r" or "\n").
Bounce Action
The Bounce action rejects the email by returning a bounce response to the sender and, optionally,
notifies you through Amazon SNS. This action has the following options.
SMTP Reply CodeThe SMTP reply code, as defined by RFC 5321.
SMTP Status CodeThe SMTP enhanced status code, as defined by RFC 3463.
MessageHuman-readable text to include in the bounce email.
Reply SenderThe email address of the sender of the bounced email. This is the address from
which the bounce email will be sent. It must be verified with Amazon SES.
SNS TopicThe name or ARN of the Amazon SNS topic to optionally notify when a bounce email is
sent. An example of an Amazon SNS topic ARN is arn:aws:sns:us-west-2:123456789012:MyTopic.
You can also create an Amazon SNS topic when you set up your action by choosing Create SNS
Topic. For more information about Amazon SNS topics, see the Amazon Simple Notification Service
Developer Guide.
281

Note
The Amazon SNS topic you choose must be in the same AWS region as the Amazon SES
endpoint you use to receive email.
You can type in your own values for these fields, or you can choose a template that fills in the SMTP
Reply Code, SMTP Status Code, and Message fields with values based on the bounce reason. The
following templates are available:
Mailbox Does Not Exist SMTP Reply Code = 550, SMTP Status Code = 5.1.1
Message Too Large SMTP Reply Code = 552, SMTP Status Code = 5.3.4
Message Full SMTP Reply Code = 552, SMTP Status Code = 5.2.2
Message Content Rejected SMTP Reply Code = 500, SMTP Status Code = 5.6.1
Unknown Failure SMTP Reply Code = 554, SMTP Status Code = 5.0.0
Temporary Failure SMTP Reply Code = 450, SMTP Status Code = 4.0.0
For additional bounce codes that you might use by typing custom values in the fields, see RFC 3463.
Lambda Action
The Lambda action calls your code through a Lambda function and, optionally, notifies you through
Amazon SNS. This action has the following options.
Lambda functionThe ARN of the Lambda function. An example of a Lambda function ARN is
arn:aws:lambda:us-west-2:account-id:function:MyFunction. For information about AWS Lambda, see
the AWS Lambda Developer Guide.
Invocation typeThe invocation type of the Lambda function. An invocation type of
RequestResponse means that the execution of the function will immediately result in a response,
and a value of Event means that the function will be invoked asynchronously. We recommend that
you use Event invocation type unless synchronous execution is absolutely necessary for your use
case.
Note
There is a 30-second timeout on RequestResponse invocations.
For information about AWS Lambda invocation types, see the AWS Lambda Developer Guide.
SNS TopicThe name or ARN of the Amazon SNS topic to notify when the specified
Lambda function is triggered. An example of an Amazon SNS topic ARN is arn:aws:sns:uswest-2:123456789012:MyTopic. You can also create an Amazon SNS topic when you set up your
action by choosing Create SNS Topic. For more information about Amazon SNS topics, see the
Note
Writing Your Lambda Function

To process your email, your Lambda function can be invoked asynchronously (that is, using the Event
invocation type). The event object passed to your Lambda function will contain metadata pertaining
to the inbound email event. You can also use the metadata to access the message content from your
Amazon S3 bucket.
If you want to actually control the mail flow, your Lambda function must be invoked synchronously (that
is, using the RequestResponse invocation type) and your Lambda function must call the callback
282

method with two arguments: the first argument is null, and the second argument is a disposition
property that is set to either STOP_RULE, STOP_RULE_SET, or CONTINUE. If the second argument is
null or does not have a valid disposition property, the mail flow continues and further actions and
rules are processed, which is the same as with CONTINUE.
For example, you can stop the receipt rule set by writing the following line at the end of your Lambda
function code:
callback( null, { "disposition" : "STOP_RULE_SET" });
For AWS Lambda code samples, see Lambda Function Examples (p. 286). For examples of highlevel use cases, see Use Case Examples (p. 283).
Input Format
Amazon SES passes information to the Lambda function in JSON format. The top-level object contains
a Records array, which is populated with properties eventSource, eventVersion, and ses. The
ses object contains receipt and mail objects, which are in exactly the same format as in the
Amazon SNS notifications described in Notification Contents (p. 297).
The following is a high-level view of the structure of the input that Amazon SES provides to the Lambda
function.
{
"Records": [
{
"eventSource": "aws:ses",
"eventVersion": "1.0",
"ses": {
"receipt": {
<same contents as SNS notification>
},
"mail": {
<same contents as SNS notification>
}
}
}
]
}
Return Values
Your Lambda function can control mail flow by returning one of the following values:
STOP_RULENo further actions in the current receipt rule will be processed, but further receipt rules
can be processed.
STOP_RULE_SETNo further actions or receipt rules will be processed.
CONTINUE or any other invalid valueThis means that further actions and receipt rules can be
processed.
Use Case Examples

The following examples outline some rules that you might set up to use Lambda function outcomes to
control your mail flow. For demonstration purposes, many of these examples use the S3 action as the
outcome.
283

Use Case 1: Drops Spam Across All Domains

This example demonstrates a global rule that drops spam across all of your domains. Rules 2 and 3
are included to show that you can apply domain-specific rules after the spam is dropped over all the
domains.
Rule 1
Recipient list: Empty. This rule will therefore apply to all recipients under all of your verified domains.
Actions
1. Lambda action (synchronous) that returns STOP_RULE_SET if the email is spam. Otherwise, it
returns CONTINUE. See the example Lambda function for dropping spam in Lambda Function
Examples (p. 286).
Rule 2
Recipient list: example1.com
Actions
1. Any action.
Rule 3
Actions
1. Any action.
Use Case 2: Bounces Spam Across All Domains

This example demonstrates a global rule that bounces spam across all of your domains. Rules 2 and
3 are included to show that you can apply domain-specific rules after the spam is bounced over all the
domains.
Rule 1
Recipient list: Empty. This rule will therefore apply to all recipients under all of your verified domains.
Actions
1. Lambda action (synchronous) that returns CONTINUE if the email is spam. Otherwise, it returns
STOP_RULE.
2. Bounce action ("500 5.6.1. Message content rejected").
3. Stop action.
Rule 2
Actions
1. Any action
284

Rule 3
Actions
1. Any action
Use Case 3: Applies the Most Specific Rule

This example demonstrates how you can use the Stop action to prevent emails from being processed
by multiple rules. In this example, you have one rule for a specific address, and another rule for all
email addresses under the domain. By using the Stop action, messages that match the rule for the
specific email address are not processed by the more generic rule that applies to the domain.
Rule 1
Recipient list: [email protected]
Actions
1. Lambda action (asynchronous).
2. Stop action.
Rule 2
Recipient list: example.com
Actions
1. Any action.
Use Case 4: Logs Mail Events to CloudWatch

This example demonstrates how to keep an audit log of all mail going through your system before
saving the mail to Amazon SES.
Rule 1
Actions
1. Lambda action (asynchronous) that writes the event object to a CloudWatch log. The example
Lambda functions in Lambda Function Examples (p. 286) log to CloudWatch.
2. S3 action.
Use Case 5: Drops Mail That Fails DKIM

This example demonstrates how you can save all incoming email to an Amazon S3 bucket, but
only send email that goes to a specific email address, and passes DKIM, to your automated email
application.
Rule 1
Actions
285

1. S3 action.
2. Lambda action (synchronous) that returns STOP_RULE_SET if the message fails DKIM. Otherwise, it
returns CONTINUE.
Rule 2
Actions
1. Lambda action (asynchronous) that triggers the automated application.
Use Case 6: Filters Mail Based on Subject Line

This example demonstrates how you can drop all of a domain's incoming mail that contains the word
"discount" in the subject line, and then process mail intended for an automated system one way, and
process mail addressed to all other recipients in the domain a different way.
Rule 1
Actions
1. Lambda action (synchronous) that returns STOP_RULE_SET if the subject line contains the word
"discount". Otherwise, it returns CONTINUE.
Rule 2
Actions
1. S3 action with bucket 1.
2. Lambda action (asynchronous) that triggers the automated application.
3. Stop action.
Rule 3
Actions
1. S3 action with bucket 2.
2. Lambda action (asynchronous) that processes email for the rest of the domain.
Lambda Function Examples

This topic contains examples of Lambda functions that control mail flow.
Example 1: Drops Spam

This example stops processing messages that have at least one spam indicator.
exports.handler = function(event, context, callback) {
console.log('Spam filter');

286

var sesNotification = event.Records[0].ses;

console.log("SES Notification:\n", JSON.stringify(sesNotification, null,
2));
// Check if any spam check failed
if (sesNotification.receipt.spfVerdict.status === 'FAIL'
|| sesNotification.receipt.dkimVerdict.status === 'FAIL'
|| sesNotification.receipt.spamVerdict.status === 'FAIL'
|| sesNotification.receipt.virusVerdict.status === 'FAIL') {
console.log('Dropping spam');
// Stop processing rule set, dropping message
callback(null, {'disposition':'STOP_RULE_SET'});
} else {
callback(null, null);
}
};
Example 2: Continues if Particular Header

This example continues processing the current rule only if the email contains a specific header value.
console.log('Header matcher');
2));
// Iterate over the headers
for (var index in sesNotification.mail.headers) {
var header = sesNotification.mail.headers[index];
// Examine the header values
if (header.name === 'X-Header' && header.value === 'X-Value') {
console.log('Found header with value.');
return;
}
}
// Stop processing the rule if the header value wasn't found
callback(null, {'disposition':'STOP_RULE'});
};
Example 3: Retrieves Email from Amazon S3

This example gets the raw email from Amazon S3 and processes it.
Note
You must first write the email to Amazon S3 using an S3 Action.
var AWS = require('aws-sdk');
var s3 = new AWS.S3();
var bucketName = '<YOUR BUCKET GOES HERE>';
console.log('Process email');
287


2));
// Retrieve the email from your bucket
s3.getObject({
Bucket: bucketName,
Key: sesNotification.mail.messageId
}, function(err, data) {
if (err) {
console.log(err, err.stack);
callback(err);
} else {
console.log("Raw email:\n" + data.Body);
// Custom email processing goes here
}
});
};
S3 Action
The S3 action delivers the mail to an Amazon S3 bucket and, optionally, notifies you through Amazon
SNS. This action has the following options.
S3 BucketThe name of the Amazon S3 bucket to which to save received emails. You can also
create a new Amazon S3 bucket when you set up your action by choosing Create S3 Bucket.
Amazon SES provides you the raw, unmodified email, which is typically in Multipurpose Internet Mail
Extensions (MIME) format. For more information about MIME format, see RFC 2045.
Important
When you save your emails to an Amazon S3 bucket, the maximum email size (including
headers) is 30 MB.
Object Key PrefixA key name prefix to use within the Amazon S3 bucket. Key name prefixes
enable you to organize your Amazon S3 bucket in a folder structure. For example, if you use Email
as your Object Key Prefix, your emails will appear in your Amazon S3 bucket in a folder named
Email.
KMS Key (if "Encrypt Message" is selected in the Amazon SES console)The customer master
key that Amazon SES should use to encrypt your emails before saving them to the Amazon S3
bucket. You can use the default master key or a custom master key you created in AWS KMS.
Note
The master key you choose must be in the same AWS region as the Amazon SES endpoint
you use to receive email.
To use the default master key, choose aws/ses when you set up the receipt rule in the Amazon
SES console. If you use the Amazon SES API, you can specify the default master key by providing
an ARN in the form of arn:aws:kms:REGION:ACCOUNT-ID-WITHOUT-HYPHENS:alias/
aws/ses. For example, if your AWS account ID is 123456789012 and you want to use the
default master key in the US West (Oregon) region, the ARN of the default master key would be
arn:aws:kms:us-west-2:123456789012:alias/aws/ses. If you use the default master key,
you don't need to perform any extra steps to give Amazon SES permission to use the key.
To use a custom master key you created in AWS KMS, provide the ARN of the master key and
ensure that you add a statement to your key's policy to give Amazon SES permission to use it.
For more information about giving permissions, see Giving Permissions to Amazon SES for Email
Receiving (p. 276).
288

For more information about using AWS KMS with Amazon SES, see the AWS Key Management
Service Developer Guide. If you do not specify a master key in the console or API, Amazon SES will
not encrypt your emails.
Important
Your mail is encrypted by Amazon SES using the Amazon S3 encryption client before the
mail is submitted to Amazon S3 for storage. It is not encrypted using Amazon S3 serverside encryption. This means that you must use the Amazon S3 encryption client to decrypt
the email after retrieving it from Amazon S3, as the service has no access to use your AWS
KMS keys for decryption. This encryption client is available with the AWS Java SDK and
AWS Java Ruby only. For more information about client-side encryption using AWS KMS
master keys, see the Amazon Simple Storage Service Developer Guide.
SNS TopicThe name or ARN of the Amazon SNS topic to notify when an email is saved
to the Amazon S3 bucket. An example of an Amazon SNS topic ARN is arn:aws:sns:uswest-2:123456789012:MyTopic. You can also create an Amazon SNS topic when you set up your
Note
SNS Action
The SNS action publishes the mail using an Amazon SNS notification. The notification includes the
complete email content. This action has the following options.
SNS TopicThe name or ARN of the Amazon SNS topic to which to publish the emails. The
Amazon SNS notifications will contain a raw, unmodified copy of the email, which is typically in
Multipurpose Internet Mail Extensions (MIME) format. For more information about MIME format, see
RFC 2045.
Important
If you choose to receive your emails through Amazon SNS notifications, the maximum email
size (including headers) is 150 KB. Larger emails will bounce. If you anticipate emails larger
than this size, save the emails to an Amazon S3 bucket instead.
An example of an Amazon SNS topic ARN is arn:aws:sns:us-west-2:123456789012:MyTopic.
You can also create an Amazon SNS topic when you set up your action by choosing Create SNS
Topic. For more information about Amazon SNS topics, see the Amazon Simple Notification Service
Developer Guide.
Note
EncodingThe encoding to use for the email within the Amazon SNS notification. UTF-8 is easier
to use, but may not preserve all special characters when a message was encoded with a different
encoding format. Base64 preserves all special characters. For information about UTF-8 and Base64,
see RFC 3629 and RFC 4648, respectively.
Stop Action
The Stop action terminates the evaluation of the receipt rule set and, optionally, notifies you through
Amazon SNS. This action has the following options.
SNS TopicThe name or ARN of the Amazon SNS topic to notify when the Stop
action is performed. An example of an Amazon SNS topic ARN is arn:aws:sns:usAPI Version 2010-12-01
289

Managing Email Receiving
west-2:123456789012:MyTopic. You can also create an Amazon SNS topic when you set up your
Note
WorkMail Action
The WorkMail action integrates with Amazon WorkMail. If Amazon WorkMail performs all of your email
processing, you will typically not use this action directly because Amazon WorkMail takes care of the
setup. This action has the following options.
Organization ARNThe ARN of the Amazon WorkMail
organization. Amazon WorkMail organization ARNs are in the form
arn:aws:workmail:region:account_ID:organization/organization_ID, where:
region is the region in which you are using Amazon SES and Amazon WorkMail. (You must use
them from the same region.) An example is us-west-2.
account_ID is the AWS account ID. You can find your AWS account ID on the Account page of
the AWS Management Console.
organization_ID is a unique identifier that Amazon WorkMail generates when you create
an organization. You can find the organization ID in the Amazon WorkMail console on the
Organization Settings page of your organization.
An example of a complete Amazon WorkMail organization ARN is arn:aws:workmail:uswest-2:123456789012:organization/m-68755160c4cb4e29a2b2f8fb58f359d7. For information about
Amazon WorkMail organizations, see the Amazon WorkMail Administrator Guide.
SNS TopicThe name or ARN of the Amazon SNS topic to notify when the Amazon
WorkMail action is taken. An example of an Amazon SNS topic ARN is arn:aws:sns:uswest-2:123456789012:MyTopic. You can also create an Amazon SNS topic when you set up your
Note
Managing Amazon SES Email Receiving

After you create your receipt rule sets, receipt rules, and IP address filters, you can use the Amazon
SES console or API to edit, delete, and perform other operations. You can also examine the Amazon
SNS notifications you receive, and use Amazon CloudWatch to view your error metrics.
This section contains the following topics:
Managing Receipt Rule Sets (p. 291)
Managing Receipt Rules (p. 293)
Managing IP Address Filters (p. 295)
Viewing Error Metrics (p. 296)
Using Notifications (p. 297)

290

Managing Receipt Rule Sets
Managing Receipt Rule Sets for Amazon SES Email

Receiving
After you create a receipt rule set as described in Creating a Receipt Rule Set (p. 279), you can
update it as needed. Although editing a receipt rule set usually consists of editing individual receipt
rules as described in Managing Receipt Rules (p. 293), you can also delete, activate, disable, and
copy receipt rule sets. Additionally, you can reorder the receipt rules in a receipt rule set. These
operations are described in the following sections.
Deleting a Receipt Rule Set

You can use the Amazon SES console or the DeleteReceiptRuleSet API to delete a receipt rule
set.
Note
You cannot delete the receipt rule set that is currently active.
To delete a receipt rule set (console)

1.
2.
3.
In the Inactive Rule Sets list, select the receipt rule set that you want to delete.
4.
From the Actions menu, choose Delete, and then confirm that you want to delete the receipt rule
set.
For information about how to use the DeleteReceiptRuleSet API to delete a receipt rule set, see
Activating and Disabling a Receipt Rule Set

Each receipt rule set is in one of two states: active or disabled. Only one of your receipt rule sets can
be active at any given time. Disabled receipt rule sets can be useful in cases where you want to make
changes to your active receipt rule set, but you do not want those changes to be active until you are
sure your updates are correct. In that case, you can copy the active receipt rule set and make changes
to the copied, disabled receipt rule set. After you're satisfied with the changes, you can activate the
copied receipt rule set. When you activate a receipt rule set, all other receipt rule sets are disabled
automatically.
Note
To disable email receiving through Amazon SES completely, disable all of your receipt rule
sets.
You can use the Amazon SES console or the SetActiveReceiptRuleSet API to control which rule
set is active.
To activate a disabled receipt rule set (console)

1.
2.
3.
In the Inactive Rule Sets list, select the receipt rule set that you want to activate.
4.
Choose Set as Active Rule Set.

291

Managing Receipt Rule Sets
To disable the active receipt rule set (console)

1.
2.
3.
Under Active Rule Set, choose Disable Active Rule Set, and then confirm that you want to
disable the receipt rule set.
For information about how to use the SetActiveReceiptRuleSet API to activate or disable a rule
set, see the Amazon Simple Email Service API Reference.
Copying a Receipt Rule Set

You can use the Amazon SES console or the CloneReceiptRuleSet API to copy a receipt rule set. If
you use the Amazon SES console, the procedure differs slightly, depending on whether the receipt rule
set you want to copy is active or disabled.
To copy the active receipt rule set (console)

1.
2.
3.
In the content pane, choose Copy Active Rule Set.
4.
In the Copy Rule Set dialog box, type the name you want to assign to the copied receipt rule set.
5.
Choose Copy Rule Set. The copied receipt rule set will appear in the Inactive Rule Sets list.
To copy a disabled receipt rule set (console)

1.
2.
3.
In the Inactive Rule Sets list, select the receipt rule set that you want to copy.
4.
From the Actions menu, choose Copy.
5.
In the Copy Rule Set dialog box, type the name you want to assign to the copied receipt rule set.
6.
Choose Copy Rule Set. The copied receipt rule set will appear in the Inactive Rule Sets list.
For information about how to use the CloneReceiptRuleSet API to copy a receipt rule set, see the
Reordering Receipt Rules

You can use the Amazon SES console or the ReorderReceiptRuleSet API to reorder receipt rules
in a receipt rule set. If you use the Amazon SES console, the procedure differs slightly, depending on
whether the receipt rule set is active or disabled.
To reorder receipt rules in the active receipt rule set (console)

1.
2.
292

Managing Receipt Rules
3.
In the content pane, choose View Active Rule Set.
4.
Choose Reorder Rules.
5.
Use the up and down arrows next to the receipt rule names to reorder the receipt rules, and then
choose Save Order.
To reorder receipt rules in a disabled receipt rule set (console)

1.
2.
3.
In the Inactive Rule Sets list, select the receipt rule set.
4.
Choose Reorder Rules.
5.
choose Save Order.
For information about how to use the ReorderReceiptRuleSet API to reorder receipt rules in a
receipt rule set, see the Amazon Simple Email Service API Reference.
Managing Receipt Rules for Amazon SES Email

Receiving
In addition to creating receipt rules as described in Creating Receipt Rules (p. 279), you can edit,
delete, enable, disable, copy, and set the position of a receipt rule in its receipt rule set, as described in
the following sections.
Note
The instructions in this section assume that the receipt rule is in the active receipt rule set. To
edit the receipt rules of a disabled receipt rule set, choose a receipt rule set from the Inactive
Rule Sets list. From there, the instructions for editing receipt rules are the same as for the
active receipt rule set.
Editing a Receipt Rule

You can use the Amazon SES console or the Amazon SES API to edit a receipt rule. It is easier to use
the Amazon SES console.
To edit a receipt rule (console)

1.
2.
3.
In the content pane, choose View Active Rule Set or choose a receipt rule set from the Inactive
Rule Sets list.
4.
In the details pane, choose the receipt rule you want to edit.
5.
In the Edit Rule pane, edit the policy, and then choose Save Rule.
If you want to use the Amazon SES API instead, use the DescribeReceiptRule API to retrieve
the rule, use a text editor to edit the rule, and then use the UpdateReceiptRule API to overwrite
the previous version of the rule. For more information, see the Amazon Simple Email Service API
Reference.
293

Managing Receipt Rules
Deleting a Receipt Rule

You can use the Amazon SES console or the DeleteReceiptRule API to delete a receipt rule.
To delete a receipt rule (console)

1.
2.
3.
Rule Sets list.
4.
In the details pane, select the receipt rule.
5.
From the Actions menu, choose Delete, and then confirm that you want to delete the receipt rule.
For information about how to use the DeleteReceiptRule API to delete a rule, see the Amazon
Enabling and Disabling a Receipt Rule

You can use the Amazon SES console or the Amazon SES API to enable or disable a receipt rule. It is
easier to use the Amazon SES console.
To enable or disable a receipt rule (console)

1.
2.
3.
Rule Sets list.
4.
In the details pane, choose the receipt rule you want to edit.
5.
In the Edit Rule pane, select or clear Enabled, and then choose Save Rule.
If you want to use the Amazon SES API instead, you can use the DescribeReceiptRule API to
retrieve the receipt rule, use a text editor to edit the receipt rule's Enabled field, and then use the
UpdateReceiptRule API to overwrite the previous version of the receipt rule. For more information,
Copying a Receipt Rule

You can use the Amazon SES console or the Amazon SES API to copy a receipt rule. It is easier to
use the Amazon SES console.
To copy a receipt rule (console)

1.
2.
3.
Rule Sets list.
4.
In the details pane, select the receipt rule.
5.
From the Actions menu, choose Copy Rule.

294

Managing IP Address Filters
6.
In the Copy Rule dialog box, type a new receipt rule name and select the destination receipt rule
set. The new receipt rule will be inserted at the beginning of the receipt rule set, and it will initially
be disabled.
If you want to use the Amazon SES API instead, you can use the DescribeReceiptRule API to
retrieve the receipt rule, use a text editor to edit the receipt rule's name and receipt rule set (if desired),
and then pass that receipt rule to the CreateReceiptRule API. For more information, see the
Setting the Position of a Receipt Rule

You can use the Amazon SES console or the SetReceiptRulePosition API to change the position
of a receipt rule in the receipt rule set.
To set the position of a receipt rule (console)

1.
2.
3.
Rule Sets list.
4.
5.
In the content pane, choose Reorder Rules.

choose Save Order.
For information about how to use the SetReceiptRulePosition API to change the position of a
receipt rule in the receipt rule set, see the Amazon Simple Email Service API Reference.
Managing IP Address Filters for Amazon SES Email

Receiving
In addition to creating IP address filters as explained in Creating IP Address Filters (p. 278), you can
view and delete them, as described in the following sections.
Viewing IP Address Filters

You can use the Amazon SES console or the ListReceiptFilters API to get a list of your IP
address filters.
To view your IP address filters (console)

1.
2.
In the left navigation pane, under Email Receiving, choose IP Address Filters. You will see a list
of your IP address filters.
For information about how to use the ListReceiptFilters API to get a list of your IP address filters,
Deleting an IP Address Filter

You can use the Amazon SES console or the DeleteReceiptFilter API to delete an IP address
filter.
295

Viewing Error Metrics
To delete an IP address filter (console)

1.
2.
3.
In the left navigation pane, under Email Receiving, choose IP Address Filters.
In the details pane, select the IP address filter.
4.
Choose Delete, and then confirm that you want to delete the IP address filter.
For information about how to use the DeleteReceiptFilter API to delete an IP address filter, see
Viewing Metrics for Amazon SES Email Receiving

You can use Amazon CloudWatch (CloudWatch) to view failure metrics for your receipt rules. You'll
find the metrics under SES/Rule Metrics.
There are two failure metrics:
PublishFailureAmazon SES encountered an error when it tried to execute the actions you
configured.
PublishExpiredAmazon SES encountered an error when it tried to execute the actions you
configured, and Amazon SES will no longer retry to deliver the email. This failure can be permanent
or transient. Amazon SES will no longer retry because the action did not succeed within eight hours.
These errors can occur, for example, if you deleted or revoked permissions to an Amazon S3 bucket,
Amazon SNS topic, or Lambda function that an action in one of your receipt rules was configured to
use.
Important
Changes you make to fix your receipt rule set will apply only to emails that Amazon SES
receives after the update. Emails are always evaluated against the receipt rule set that was in
place at the time the email was received.
The following figure shows the metrics in the CloudWatch console.

296

Using Notifications
Using Notifications for Amazon SES Email

Receiving
There are two types of Amazon SNS notifications that you can use when you receive email using
Amazon SES: notifications that alert you that an action in a receipt rule was taken, and notifications
from the SNS action, which contain the content of the email.
This section describes the contents of the notifications and provides an example of each notification
type:
Notification Contents (p. 297)
Notification Examples (p. 301)
Contents of Notifications for Amazon SES Email Receiving

All notifications for email receiving are published to Amazon Simple Notification Service (Amazon SNS)
topics in JavaScript Object Notation (JSON) format.

The top-level JSON object contains the following fields.
Field Name
Description
notificationType
String that specifies the notification type. This

value will always be Received.
receipt
Object that contains information about the email

delivery.
mail
Object that contains information about the email

to which the notification pertains.
content
String that contains the raw, unmodified email,

which is typically in Multipurpose Internet Mail
Extensions (MIME) format. For more information
about MIME format, see RFC 2045.
Note
notification was triggered by an SNS
action. Notifications triggered by all
other actions do not contain this field.
receipt Object
The receipt object has the following fields.
Field Name
Description
action
Object that encapsulates information about the

action that was executed.
dkimVerdict
Object that indicates whether the DomainKeys

Identified Mail (DKIM) check passed.
297

Using Notifications
Field Name
Description
String that specifies the period, in milliseconds,

from the time Amazon SES received the
message to the time it triggered the action.
recipients
A list of the recipient addresses for this delivery.

This list might be a subset of the recipients to
which the mail was addressed.
spamVerdict
Object that indicates whether the message is

spam.
spfVerdict
Object that indicates whether the Sender Policy

Framework (SPF) check passed.
timestamp
String that specifies when the action was

triggered, in ISO8601 format.
virusVerdict
Object that indicates whether the message

contains a virus.
action Object
The action object has the following fields.
Field Name
Description
type
String that indicates the type of action that was

executed. Possible values are S3, SNS, Bounce,
Lambda, Stop, and WorkMail.
topicArn
String that contains the Amazon Resource Name

(ARN) of the Amazon SNS topic to which the
notification was published.
bucketName
String that contains the name of the Amazon S3

bucket to which the message was published.
Present only for the S3 action type.
objectKey
String that contains a name that uniquely

identifies the email in the Amazon S3 bucket.
This is the same as the messageId in the mail
object. Present only for the S3 action type.
smtpReplyCode
String that contains the SMTP reply code, as

defined by RFC 5321. Present only for the
bounce action type.
statusCode
String that contains the SMTP enhanced status

code, as defined by RFC 3463. Present only for
the bounce action type.
message
String that contains the human-readable text to

include in the bounce message. Present only for
the bounce action type.
sender
String that contains the email address of the

sender of the email that bounced. This is the
298

Using Notifications
Field Name
Description
address from which the bounce message was
sent. Present only for the bounce action type.
functionArn
String that contains the ARN of the Lambda

function that was triggered. Present only for the
Lambda action type.
invocationType
String that contains the invocation type of

the Lambda function. Possible values are
RequestResponse and Event. Present only for
the Lambda action type.
organizationArn
String that contains the ARN of the Amazon

WorkMail organization. Present only for the
WorkMail action type.
dkimVerdict Object
The dkimVerdict object has the following fields.
Field Name
Description
status
String that contains the DKIM verdict. Possible

values are as follows:
PASS The check succeeded.
FAIL The check failed.
GRAY The message is not DKIM-signed.
PROCESSING_FAILED There is an issue
that prevents Amazon SES from checking the
DKIM signature. For example, DNS queries
are failing or the DKIM signature header is not
formatted properly.
spamVerdict Object
The spamVerdict object has the following fields.
Field Name
Description
status
String that contains the result of spam scanning.

Possible values are as follows:
GRAY Amazon SES scanned the email but
could not determine with confidence whether it
is spam.
PROCESSING_FAILED Amazon SES is
unable to scan the content of the email.
For example, the email is not a valid MIME
message.

299

Using Notifications
spfVerdict Object
The spfVerdict object has the following fields.
Field Name
Description
status
String that contains the SPF verdict. Possible

values are as follows:
GRAY There is no SPF policy under the
domain used in the MAIL FROM command.
PROCESSING_FAILED There is an issue that
prevents Amazon SES from checking the SPF
record. For example, DNS queries are failing.
virusVerdict Object
The virusVerdict object has the following fields.
Field Name
Description
status
String that contains the result of virus scanning.

Possible values are as follows:
GRAY Amazon SES scanned the email but
could not determine with confidence whether it
contains a virus.
PROCESSING_FAILED Amazon SES is
unable to scan the content of the email.
For example, the email is not a valid MIME
message.
mail Object
The mail object has the following fields.
Field Name
Description
destination
A list of email addresses that are recipients of the

email.
messageId
String that contains the unique ID assigned to

the email by Amazon SES. If the email was
delivered to Amazon S3, the message ID is also
the Amazon S3 object key that was used to write
the message to your Amazon S3 bucket.
source
String that contains the email address from which

the email was sent (the envelope MAIL FROM
address).

300

Using Notifications
Field Name
Description
timestamp
String that contains the time at which the email

was received, in ISO8601 format.
headers
A list of Amazon SES headers and your custom

headers. Each header in the list has a name field
and a value field.
commonHeaders
A list of headers common to all emails. Each

header in the list is composed of a name and a
value.
headersTruncated
String that specifies whether the headers were

truncated in the notification, which will happen
if the headers are larger than 10 KB. Possible
values are true and false.
Examples of Notifications for Amazon SES Email Receiving

This section provides an example of a notification that alerts you that an action was taken, and a
notification from an SNS action, which contains the contents of the email.
Alert Notification (p. 301)
Notification of an SNS action (p. 303)
Alert Notification
This section contains an example of an Amazon SNS notification that can be triggered by an S3 action.
Notifications triggered by Lambda actions, bounce actions, stop actions, and Amazon WorkMail actions
are similar. Although the notification contains information about the email, it does not contain the
content of the email itself.
{
"notificationType": "Received",
"receipt": {
"timestamp": "2015-09-11T20:32:33.936Z",
"recipients": [
"[email protected]"
],
"spamVerdict": {
"status": "PASS"
},
"virusVerdict": {
"status": "PASS"
},
"spfVerdict": {
"status": "PASS"
},
"dkimVerdict": {
"status": "PASS"
},
"action": {
"type": "S3",
"topicArn": "arn:aws:sns:us-east-1:012345678912:example-topic",
301

Using Notifications
"bucketName": "my-S3-bucket",
"objectKey": "\email"
}
},
"mail": {
"timestamp": "2015-09-11T20:32:33.936Z",
"source":
"0000014fbe1c09cf-7cb9f704-7531-4e53-89a1-5fa9744f5eb6-000000@amazonses.com",
"messageId": "d6iitobk75ur44p8kdnnp7g2n800",
"destination": [
"[email protected]"
],
"headers": [
{
"name": "Return-Path",
"value":
"<0000014fbe1c09cf-7cb9f704-7531-4e53-89a1-5fa9744f5eb6-000000@amazonses.com>"
},
{
"name": "Received",
"value": "from a9-183.smtp-out.amazonses.com (a9-183.smtpout.amazonses.com [54.240.9.183]) by inbound-smtp.us-east-1.amazonaws.com
with SMTP id d6iitobk75ur44p8kdnnp7g2n800 for [email protected]; Fri, 11
Sep 2015 20:32:33 +0000 (UTC)"
},
{
"name": "DKIM-Signature",
"value": "v=1; a=rsa-sha256; q=dns/txt;
c=relaxed/simple; s=ug7nbtf4gccmlpwj322ax3p6ow6yfsug;
d=amazonses.com; t=1442003552; h=From:To:Subject:MIMEVersion:Content-Type:Content-Transfer-Encoding:Date:MessageID:Feedback-ID; bh=DWr3IOmYWoXCA9ARqGC/UaODfghffiwFNRIb2Mckyt4=;
b=p4ukUDSFqhqiub+zPR0DW1kp7oJZakrzupr6LBe6sUuvqpBkig56UzUwc29rFbJF
hlX3Ov7DeYVNoN38stqwsF8ivcajXpQsXRC1cW9z8x875J041rClAjV7EGbLmudVpPX
4hHst1XPyX5wmgdHIhmUuh8oZKpVqGi6bHGzzf7g="
},
{
"name": "From",
},
{
"name": "To",
},
{
"name": "Subject",
"value": "Example subject"
},
{
"value": "1.0"
},
{
"value": "text/plain; charset=UTF-8"
},
{
302

Using Notifications
"value": "7bit"
},
{
"name": "Date",
"value": "Fri, 11 Sep 2015 20:32:32 +0000"
},
{
"name": "Message-ID",
"value": "<[email protected]>"
},
{
"name": "X-SES-Outgoing",
"value": "2015.09.11-54.240.9.183"
},
{
"name": "Feedback-ID",
"value": "1.us-east-1.Krv2FKpFdWV+KUYw3Qd6wcpPJ4Sv/
pOPpEPSHn2u2o4=:AmazonSES"
}
],
"commonHeaders": {
"returnPath":
"from": [
"[email protected]"
],
"date": "Fri, 11 Sep 2015 20:32:32 +0000",
"to": [
"[email protected]"
],
"messageId": "<[email protected]>",
"subject": "Example subject"
}
}
}
Notification of an SNS action

This section contains an example of an SNS action notification. Unlike the alert notification shown
previously, it includes a content section that contains the email, which is typically in Multipurpose
Internet Mail Extensions (MIME) format.
{
"notificationType": "Received",
"receipt": {
"timestamp": "2015-09-11T20:32:33.936Z",
"recipients": [
"[email protected]"
],
"spamVerdict": {
"status": "PASS"
},
"virusVerdict": {
"status": "PASS"
},
"spfVerdict": {
303

Using Notifications
"status": "PASS"
},
"dkimVerdict": {
"status": "PASS"
},
"action": {
"type": "SNS",
"topicArn": "arn:aws:sns:us-east-1:012345678912:example-topic"
}
},
"mail": {
"timestamp": "2015-09-11T20:32:33.936Z",
"messageId": "d6iitobk75ur44p8kdnnp7g2n800",
"destination": [
"[email protected]"
],
"headers": [
{
"name": "Return-Path",
"value":
"<0000014fbe1c09cf-7cb9f704-7531-4e53-89a1-5fa9744f5eb6-000000@amazonses.com>"
},
{
"name": "Received",
"value": "from a9-183.smtp-out.amazonses.com (a9-183.smtpout.amazonses.com [54.240.9.183]) by inbound-smtp.us-east-1.amazonaws.com
with SMTP id d6iitobk75ur44p8kdnnp7g2n800 for [email protected]; Fri, 11
Sep 2015 20:32:33 +0000 (UTC)"
},
{
"name": "DKIM-Signature",
"value": "v=1; a=rsa-sha256; q=dns/txt;
c=relaxed/simple; s=ug7nbtf4gccmlpwj322ax3p6ow6yfsug;
d=amazonses.com; t=1442003552; h=From:To:Subject:MIMEVersion:Content-Type:Content-Transfer-Encoding:Date:MessageID:Feedback-ID; bh=DWr3IOmYWoXCA9ARqGC/UaODfghffiwFNRIb2Mckyt4=;
b=p4ukUDSFqhqiub+zPR0DW1kp7oJZakrzupr6LBe6sUuvqpBkig56UzUwc29rFbJF
hlX3Ov7DeYVNoN38stqwsF8ivcajXpQsXRC1cW9z8x875J041rClAjV7EGbLmudVpPX
4hHst1XPyX5wmgdHIhmUuh8oZKpVqGi6bHGzzf7g="
},
{
"name": "From",
},
{
"name": "To",
},
{
"name": "Subject",
"value": "Example subject"
},
{
"value": "1.0"
},
{
304

Using Notifications
"value": "text/plain; charset=UTF-8"
},
{
"value": "7bit"
},
{
"name": "Date",
"value": "Fri, 11 Sep 2015 20:32:32 +0000"
},
{
"name": "Message-ID",
"value": "<[email protected]>"
},
{
"name": "X-SES-Outgoing",
"value": "2015.09.11-54.240.9.183"
},
{
"name": "Feedback-ID",
"value": "1.us-east-1.Krv2FKpFdWV+KUYw3Qd6wcpPJ4Sv/
pOPpEPSHn2u2o4=:AmazonSES"
}
],
"commonHeaders": {
"returnPath":
"from": [
"[email protected]"
],
"date": "Fri, 11 Sep 2015 20:32:32 +0000",
"to": [
"[email protected]"
],
"messageId": "<[email protected]>",
"subject": "Example subject"
}
},
"content": "Return-Path: <[email protected]>\r\nReceived: from a9-183.smtpout.amazonses.com (a9-183.smtp-out.amazonses.com [54.240.9.183])\r
\n by inbound-smtp.us-east-1.amazonaws.com with SMTP id
d6iitobk75ur44p8kdnnp7g2n800\r\n for [email protected];\r\n Fri,
11 Sep 2015 20:32:33 +0000 (UTC)\r\nDKIM-Signature: v=1; a=rsa-sha256;
q=dns/txt; c=relaxed/simple;\r\n\ts=ug7nbtf4gccmlpwj322ax3p6ow6yfsug;
d=amazonses.com; t=1442003552;\r\n\th=From:To:Subject:MIMEVersion:Content-Type:Content-Transfer-Encoding:Date:Message-ID:FeedbackID;\r\n\tbh=DWr3IOmYWoXCA9ARqGC/UaODfghffiwFNRIb2Mckyt4=;\r\n
\tb=p4ukUDSFqhqiub+zPR0DW1kp7oJZakrzupr6LBe6sUuvqpBkig56UzUwc29rFbJF\r\n
\thlX3Ov7DeYVNoN38stqwsF8ivcajXpQsXRC1cW9z8x875J041rClAjV7EGbLmudVpPX\r
\n\t4hHst1XPyX5wmgdHIhmUuh8oZKpVqGi6bHGzzf7g=\r\nFrom: [email protected]
\r\nTo: [email protected]\r\nSubject: Example subject\r\nMIMEVersion: 1.0\r\nContent-Type: text/plain; charset=UTF-8\r\nContentTransfer-Encoding: 7bit\r\nDate: Fri, 11 Sep 2015 20:32:32 +0000\r
\nMessage-ID: <[email protected]>\r\nX-SESOutgoing: 2015.09.11-54.240.9.183\r\nFeedback-ID: 1.us-east-1.Krv2FKpFdWV
+KUYw3Qd6wcpPJ4Sv/pOPpEPSHn2u2o4=:AmazonSES\r\n\r\nExample content\r\n"
305

Using Notifications

306

Creating IAM Policies for Access to Amazon SES
Controlling Access to Amazon SES
You can use AWS Identity and Access Management (IAM) with Amazon Simple Email Service
(Amazon SES) to specify which Amazon SES API actions an IAM user, group, or role can perform. (In
this topic we refer to these entities collectively as user.) You can also control which email addresses
the user can use for the "From", recipient, and "Return-Path" addresses of emails.
For example, you can create an IAM policy that allows users in your organization to send email, but not
perform administrative actions such as checking sending statistics. As another example, you can write
a policy that allows a user to send emails through Amazon SES from your account, but only if they use
a specific "From" address.
To use IAM, you define an IAM policy, which is a document that explicitly defines permissions, and
attach the policy to a user. To learn how to create IAM policies, see the IAM User Guide. Other than
applying the restrictions you set in your policy, there are no changes to how users interact with Amazon
SES or in how Amazon SES carries out requests.
Note
You can also control access to Amazon SES by using sending authorization policies. Whereas
IAM policies constrain what individual IAM users can do, sending authorization policies
constrain how individual verified identities can be used. Further, only sending authorization
policies can grant cross-account access. For more information about sending authorization,
see Using Sending Authorization with Amazon SES (p. 196).
If you are looking for information about how to generate Amazon SES SMTP credentials for an existing
IAM user, see Obtaining Your Amazon SES SMTP Credentials (p. 57).
Creating IAM Policies for Access to Amazon SES

This section explains how you can use IAM policies specifically with Amazon SES. To learn how to
create IAM policies in general, see the IAM User Guide.
There are three reasons you might use IAM with Amazon SES:
To restrict the email-sending action.
To restrict the "From", recipient, and "Return-Path" addresses of the emails that the user sends.
307

Restricting the Action
To control general aspects of API usage such as the time period during which a user is permitted to
call the APIs that they are authorized to use.
Restricting the Action

To control which Amazon SES actions a user can perform, you use the Action element of an
IAM policy. You can set the Action element to any Amazon SES API action by prefixing the API
name with the lowercase string ses:. For example, you can set the Action to ses:SendEmail,
ses:GetSendStatistics, or ses:* (for all actions).
Then, depending on the Action, specify the Resource element as follows:
If the Action element only permits access to email-sending APIs (that is, ses:SendEmail and/
or ses:SendRawEmail):
To allow the user to send from any identity in your AWS account, set Resource to *
To limit the identities that the user can send from, set Resource to the ARN(s) of the identities that
you are permitting the user to use.
If the Action element permits access to all APIs:
If you do not want to limit the identities that the user can send from, set Resource to *
If you do want to limit the identities that the user can send from, you need to create two policies (or
two statements within one policy):
One with Action set to an explicit list of the permitted non-email-sending APIs and Resource set
to *
One with Action set to one of the email-sending APIs (ses:SendEmail and/or
ses:SendRawEmail), and Resource set to the ARN(s) of the identities you are permitting the
user to use.
For a list of available Amazon SES actions, see the Amazon Simple Email Service API Reference. If
the IAM user will be using the SMTP interface, you must allow access to ses:SendRawEmail at a
minimum.
Restricting Email Addresses

If you want to restrict the user to specific email addresses, you can use a Condition block. In the
Condition block, you specify conditions by using condition keys as described in the IAM User Guide.
By using condition keys, you can control the following email addresses:
Note
These email address condition keys apply only to the APIs noted in the following table.
Condition Key
Description
API
ses:Recipients
Restricts the recipient

addresses, which include
the To:, "CC", and "BCC"
addresses.
SendEmail, SendRawEmail
ses:FromAddress
Restricts the "From" address.
SendEmail, SendRawEmail,
SendBounce
ses:FromDisplayName
Restricts the "From" address

that is used as the display
name.

308

Restricting General API Usage
Condition Key
Description
API
ses:FeedbackAddress
Restricts the "Return-Path"

address, which is the address
where bounces and complaints
can be sent to you by email
feedback forwarding. For
information about email
feedback forwarding, see
Amazon SES Notifications
Through Email (p. 107).
Restricting General API Usage

By using AWS-wide keys in conditions, you can restrict access to Amazon SES based on aspects such
as the date and time that user is permitted access to APIs. Amazon SES implements only the following
AWS-wide policy keys:
aws:CurrentTime
aws:EpochTime
aws:SecureTransport
aws:SourceIp
aws:UserAgent
For more information about these keys, see the IAM User Guide.
Example IAM Policies for Amazon SES

This topic provides examples of policies that permit a user access to Amazon SES, but only under
certain conditions.
Allowing Full Access to All Amazon SES Actions (p. 309)
Allowing Access to Email-Sending Actions Only (p. 310)
Restricting the Time Period of Sending (p. 310)
Restricting the Recipient Addresses (p. 310)
Restricting the "From" Address (p. 311)
Restricting the Display Name of the Email Sender (p. 311)
Restricting the Destination of Bounce and Complaint Feedback (p. 312)
Allowing Full Access to All Amazon SES Actions

The following policy allows a user to call any Amazon SES action.
{
"Version": "2012-10-17",
"Statement":[{
"Effect": "Allow",
"Action": ["ses:*"],
"Resource":"*"
309

Allowing Access to Email-Sending Actions Only
}
]
}
Allowing Access to Email-Sending Actions Only

The following policy permits a user to send email using Amazon SES, but does not permit the user to
perform administrative actions such as accessing Amazon SES sending statistics.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["ses:SendEmail", "ses:SendRawEmail"],
"Resource":"*"
}
]
}
Restricting the Time Period of Sending

The following policy permits a user to call Amazon SES email-sending APIs only during the month of
September 2015.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Resource":"*",
"Condition": {
"DateGreaterThan": {
},
"DateLessThan": {
}
}
}
]
}
Restricting the Recipient Addresses

The following policy permits a user to call the Amazon SES email-sending APIs, but only to recipient
addresses in domain example.com.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
310


"Resource":"*",
"Condition": {
"ForAllValues:StringLike": {
"ses:Recipients": ["*@example.com"]
}
}
}
]
}

The following policy permits a user to call the Amazon SES email-sending APIs, but only if the "From"
address is [email protected].
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Resource":"*",
"Condition": {
"StringEquals": {
}
}
}
]
}
The following policy permits a user to call the SendBounce API, but only if the "From" address is
[email protected].
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["ses:SendBounce"],
"Resource":"*",
"Condition": {
"StringEquals": {
}
}
}
]
}
Restricting the Display Name of the Email Sender

The following policy permits a user to call the Amazon SES email-sending APIs, but only if the display
name of the "From" address includes Marketing.
311

Restricting the Destination of
Bounce and Complaint Feedback
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Resource":"*",
"Condition": {
"StringLike": {
"ses:FromDisplayName": "Marketing"
}
}
}
]
}
Restricting the Destination of Bounce and Complaint

Feedback
The following policy permits a user to call the Amazon SES email-sending APIs, but only if the "ReturnPath" of the email is set to [email protected].
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Resource":"*",
"Condition": {
"StringEquals": {
"ses:FeedbackAddress": "[email protected]"
}
}
}
]
}

312

Amazon SES Information in CloudTrail
Logging Amazon SES API Calls By

Using AWS CloudTrail
Amazon SES is integrated with CloudTrail, a service that captures API calls made by or on behalf of
Amazon SES in your AWS account and delivers the log files to an Amazon S3 bucket that you specify.
CloudTrail captures API calls made from the Amazon SES console or from the Amazon SES API.
Using the information collected by CloudTrail, you can determine what request was made to Amazon
SES, the source IP address from which the request was made, who made the request, when it was
made, and so on. To learn more about CloudTrail, including how to configure and enable it, see the
AWS CloudTrail User Guide.
Amazon SES Information in CloudTrail

When CloudTrail logging is enabled in your AWS account, API calls made to a subset of Amazon
SES actions are tracked in log files. Amazon SES records are written together with other AWS service
records in a log file. CloudTrail determines when to create and write to a new file based on a time
period and file size.
The following actions are supported:
CloneReceiptRuleSet
CreateReceiptFilter
CreateReceiptRule
CreateReceiptRuleSet
DeleteIdentity
DeleteIdentityPolicy
DeleteReceiptFilter
DeleteReceiptRule
DeleteReceiptRuleSet
DeleteVerifiedEmailAddress
DescribeActiveReceiptRuleSet
DescribeReceiptRule
DescribeReceiptRuleSet
313

Understanding Amazon SES Log File Entries
GetIdentityDkimAttributes
GetIdentityNotificationAttributes
GetIdentityPolicies
GetIdentityVerificationAttributes
GetSendQuota
GetSendStatistics
ListIdentities
ListIdentityPolicies
ListReceiptFilters
ListReceiptRuleSets
ListVerifiedEmailAddresses
PutIdentityPolicy
ReorderReceiptRuleSet
SetActiveReceiptRuleSet
SetReceiptRulePosition
SetIdentityDkimEnabled
SetIdentityFeedbackForwardingEnabled
SetIdentityHeadersInNotificationsEnabled
SetIdentityNotificationTopic
UpdateReceiptRule
VerifyDomainDkim
VerifyDomainIdentity
VerifyEmailAddress
VerifyEmailIdentity
Every log entry contains information about who generated the request. The user identity information
in the log helps you determine whether the request was made with root or IAM user credentials, with
temporary security credentials for a role or federated user, or by another AWS service. For more
information, see the userIdentity field in the CloudTrail Event Reference.
You can store your log files in your bucket for as long as you want, but you can also define Amazon
S3 lifecycle rules to archive or delete log files automatically. By default, your log files are encrypted by
using Amazon S3 server-side encryption (SSE).
You can choose to have CloudTrail publish Amazon SNS notifications when new log files are delivered
if you want to take quick action upon log file delivery. For more information, see Configuring Amazon
SNS Notifications.
You can also aggregate Amazon SES log files from multiple AWS regions and multiple AWS accounts
into a single Amazon S3 bucket. For more information, see Aggregating CloudTrail Log Files to a
Single Amazon S3 Bucket.

CloudTrail log files contain one or more log entries where each entry is made up of multiple JSONformatted events. A log entry represents a single request from any source and includes information
about the requested action, any parameters, the date and time of the action, and so on. The log entries
are not guaranteed to be in any particular order. That is, they are not an ordered stack trace of the
public API calls.
314

The following example shows a CloudTrail log.

{
"Records": [
{
"awsRegion": "us-west-2",
"eventID": "0ffa308d-1467-4259-8be3-c749753be325",
"eventName": "DeleteIdentity",
"eventSource": "ses.amazonaws.com",
"eventTime": "2015-02-02T21:34:50Z",
"eventType": "AwsApiCall",
"recipientAccountId": "111122223333",
"requestID": "50b87bfe-ab23-11e4-9106-5b36376f9d12",
"requestParameters": {
"identity": "amazon.com"
},
"responseElements": null,
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-sdk-java/unknown-version",
"userIdentity": {
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"accountId": "111122223333",
"arn": "arn:aws:iam::111122223333:root",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "17bb827a-dc8c-4156-90b1-c214e1d135c9",
"eventName": "DeleteVerifiedEmailAddress",
"eventTime": "2015-02-04T00:57:15Z",
"requestID": "c29fb5c1-ac08-11e4-8ff5-a56a3119e253",
},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "0b311e38-b5c6-43b3-9a39-5fbf0c2d0d99",
"eventName": "GetIdentityDkimAttributes",
"eventTime": "2015-02-02T21:34:50Z",
315

"requestID": "50f92e80-ab23-11e4-9106-5b36376f9d12",
"identities": [
"example.com"
]
},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "bf695be8-1c67-45b0-8f10-fd56afee09dd",
"eventName": "GetIdentityNotificationAttributes",
"eventTime": "2015-02-02T21:34:50Z",
"requestID": "5133ed92-ab23-11e4-9106-5b36376f9d12",
"identities": [
"example.com"
]
},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "8f9aed63-b03a-4d30-a880-33ae0c6b7786",
"eventName": "GetIdentityVerificationAttributes",
"eventTime": "2015-02-04T00:57:16Z",
"requestID": "c2d23773-ac08-11e4-8ff5-a56a3119e253",
"identities": [
"example.com"
]
316

},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "60ef4f01-9826-4fb4-828e-8c36dda81f40",
"eventName": "GetSendQuota",
"eventTime": "2015-02-04T01:03:27Z",
"requestID": "a0760648-ac09-11e4-8ff5-a56a3119e253",
"requestParameters": null,
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "0fe5eef3-0c28-4480-808e-307b21404a78",
"eventName": "GetSendStatistics",
"eventTime": "2015-02-02T21:34:51Z",
"requestID": "51644c64-ab23-11e4-9106-5b36376f9d12",
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "6eb8178e-69c3-4a93-8af0-2a5a0f5f209e",
317

"eventName": "ListIdentities",
"eventTime": "2015-02-04T01:03:27Z",
"requestID": "a0a4de7a-ac09-11e4-8ff5-a56a3119e253",
"identityType": "Domain",
"maxItems": 10
},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "a18a9745-d06a-43e9-aad0-8eee4de50f48",
"eventName": "ListVerifiedEmailAddresses",
"eventTime": "2015-02-02T21:34:51Z",
"requestID": "51ad8a66-ab23-11e4-9106-5b36376f9d12",
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "da975f45-e68b-4499-8e3f-31a89140e0c9",
"eventName": "SetIdentityDkimEnabled",
"eventTime": "2015-02-04T01:01:24Z",
"requestID": "5731c4ab-ac09-11e4-8ff5-a56a3119e253",
"dkimEnabled": true,
"identity": "example.com"
},
318

"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "5d817126-dadb-436f-b480-f9843289f487",
"eventName": "SetIdentityFeedbackForwardingEnabled",
"eventTime": "2015-02-02T21:34:51Z",
"requestID": "51dd4cf8-ab23-11e4-9106-5b36376f9d12",
"forwardingEnabled": true,
"identity": "example.com"
},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "5d817126-dadb-436f-b480-f9843289f487",
"eventName": "SetIdentityHeadersInNotificationsEnabled",
"eventTime": "2015-02-02T21:34:51Z",
"requestID": "51dd4cf8-ab23-11e4-9106-5b36376f9d12",
"enabled": true,
"identity": "example.com",
"notificationType": "Bounce"
},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
319

}
},
{
"eventID": "1a31fd43-55ba-4ce7-b3fe-55659e8144c0",
"eventName": "SetIdentityNotificationTopic",
"eventTime": "2015-02-04T00:59:21Z",
"requestID": "0d553aac-ac09-11e4-8ff5-a56a3119e253",
"identity": "example.com",
"notificationType": "Bounce",
"snsTopic": "arn:aws:sns:us-west-2:123456789100:MyTopic"
},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "aec73edb-6dac-4503-81bb-cca1102f959e",
"eventName": "VerifyDomainDkim",
"eventTime": "2015-02-02T21:34:52Z",
"requestID": "52215ada-ab23-11e4-9106-5b36376f9d12",
"domain": "example.com"
},
"responseElements": {
"dkimTokens": [
"3r2ultrqtelopya3v2apjulcvz7z5n5o",
"yexya47xmy5f3j3e7vgm6pcrcmayu6nu",
"wtlduqduorhmb2vdt2m53yqlcj2m6tpw"
]
},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
320

"eventID": "33b3e2eb-7ba3-460b-a127-a5f4cedb4469",
"eventName": "VerifyDomainIdentity",
"eventTime": "2015-02-04T00:59:21Z",
"requestID": "0d9c2ebe-ac09-11e4-8ff5-a56a3119e253",
"disableEmailNotifications": false,
"domain": "example.com"
},
"responseElements": {
"verificationToken":
"pmBGN/7MjnfhTKUZ06Enqq1PeGUaOkw8lGhcfwefcHU="
},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "eb2e1616-2b7b-4cd2-b6dc-29f83fc1789f",
"eventName": "VerifyEmailAddress",
"eventTime": "2015-02-02T21:34:53Z",
"requestID": "5265ddec-ab23-11e4-9106-5b36376f9d12",
},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
},
{
"eventID": "5613b0ff-d6c6-4526-9b53-a603a9231725",
"eventName": "VerifyEmailIdentity",
"eventTime": "2015-02-04T01:05:33Z",
321

"requestID": "eb2ff803-ac09-11e4-8ff5-a56a3119e253",
},
"userIdentity": {
"accountId": "111122223333",
"principalId": "111122223333",
"type": "Root"
}
}
]
}

322
Using Credentials With Amazon

SES
To interact with Amazon Simple Email Service (Amazon SES), you use security credentials to verify
who you are and whether you have permission to interact with Amazon SES. There are different types
of credentials, and the credentials you use depend on what you want to do. For example, you use AWS
access keys when you send an email using the Amazon SES API, and SMTP credentials when you
send an email using the Amazon SES SMTP interface.
The following table lists the types of credentials you might use with Amazon SES, depending on what
you are doing.
If you want to
access the...
Use these
credentials
What the
How to get the credentials
credentials consist
of
Amazon SES API
AWS access keys
Access key ID and

secret access key
(You might access

the Amazon SES
API directly, or
indirectly through
an AWS SDK, the
AWS Command
Line Interface, or
the AWS Tools
for Windows
PowerShell.)
See Access Keys in the AWS

General Reference.
Note
For security best
practice, use AWS
Identity and Access
Management (IAM)
user access keys
instead of AWS account
access keys. Your AWS
account credentials
grant full access to all
your AWS resources,
so you should store
them in a safe place
and instead use IAM
user credentials for
day-to-day interaction
with AWS. For more
information, see Root
Account Credentials vs.
IAM User Credentials
in the AWS General
Reference.
323
If you want to
access the...
Use these
credentials
What the
How to get the credentials
credentials consist
of
Amazon SES SMTP

interface
SMTP credentials
User name and

password
See Obtaining Your Amazon

SES SMTP Credentials (p. 57).
Note
Although your Amazon
SES SMTP credentials
are different than your
AWS access keys
and IAM user access
keys, Amazon SES
SMTP credentials
are actually a type of
IAM credentials. An
IAM user can create
Amazon SES SMTP
credentials, but the
root account owner
must ensure that the
IAM user's policy
gives them permission
to access the
following IAM actions:
"iam:ListUsers",
"iam:CreateUser",
"iam:CreateAccessKey",
and
"iam:PutUserPolicy".
Amazon SES
console
IAM user name and

password
IAM user name and

password
OR
OR
Email address and

password
Email address and

password

324
See IAM User Name and

Password and Email Address
and Password of the AWS
General Reference.
Note
For security best
practice, use an
IAM user name and
password instead of
an email address and
password. The email
address and password
combination are for
your AWS account, so
you should store them
in a safe place instead
of using them for dayto-day interaction
with AWS. For more
information, see Root
Account Credentials vs.
IAM User Credentials
in the AWS General
Reference.
For more information about different types of AWS security credentials (except for SMTP credentials,
which are used only for Amazon SES), see AWS Security Credentials in the AWS General Reference.

325

Query API

You can use the Amazon SES API by using an AWS SDK, which wraps the low-level functionality of
the Amazon SES API with higher-level data types and function calls that take care of the details for
you, or you can make raw requests to Amazon SES over HTTPS by using the Query API. For general
information about the Query API, see Amazon SES Query API (p. 326). Individual APIs are described
in the Amazon Simple Email Service API Reference.
Amazon SES Query API

This section describes how to make Query requests to Amazon SES. The various topics acquaint you
with the Amazon SES Query interface, the components of a request, how to authenticate a request,
and the content of responses.
For information about Query requests, see Query Requests and Amazon SES (p. 326).
For information about request authentication, see Request Authentication and Amazon
SES (p. 329).
For examples of GET and POST requests, see GET and POST Examples for Amazon
SES (p. 329).
For information about Query responses, see Query Responses and Amazon SES (p. 330).
Query Requests and Amazon SES

Amazon SES supports Query requests for service actions. Query requests are simple HTTPS requests
that use the GET or POST method. Query requests must contain an Action parameter to indicate the
action to be performed.
Important
For security reasons, Amazon SES does not support HTTP requests. You must use HTTPS
instead.
Structure of a GET Request

This guide presents the Amazon SES GET requests as URLs. Each URL consists of the following:
EndpointThe resource the request is acting on. For a list of Amazon SES endpoints, see Regions
and Amazon SES (p. 332).
ActionThe action you want to perform on the endpoint, such as sending a message.
ParametersAny request parameters.
326

Query Requests
The following is an example GET request to send a message using the Amazon SES endpoint in the
US West (Oregon) region.
https://email.us-west-2.amazonaws.com?Action=SendEmail&Source=user
%40example.com&Destination.ToAddresses.member.1=allan
%40example.com&Message.Subject.Data=This%20is%20the%20subject
%20line.&Message.Body.Text.Data=Hello.%20I%20hope%20you%20are%20having%20a
%20good%20day.
Important
Because the GET requests are URLs, you must URL-encode the parameter values. For
example, in the preceding example request, the value for the Source parameter is actually
[email protected]. However, the "@" character is not allowed in URLs, so each "@" is
URL-encoded as "%40".
To make the GET examples easier to read, this guide presents them in the following parsed format.
https://email.us-west-2.amazonaws.com
?Action=SendEmail
&Source=user%40example.com
&Destination.ToAddresses.member.1=allan%40example.com
&Message.Subject.Data=This%20is%20the%20subject%20line.
&Message.Body.Text.Data=Hello.%20I%20hope%20you%20are%20having%20a%20good
%20day.
The first line represents the endpoint of the request. After the endpoint is a question mark (?), which
separates the endpoint from the parameters. Each parameter is separated by an ampersand (&).
The Action parameter indicates the action to perform. For a complete list of actions, and the
parameters used with each action, see the Amazon Simple Email Service API Reference.
Some operations take lists of parameters. For example, when you send an email to multiple recipients,
you can provide a list of email addresses. You specify this type of list with param.n notation, where
values of n are integers starting from 1. For example, you would specify the first "To:" address using
Destination.ToAddresses.1, the second with Destination.ToAddresses.2, etc.
In Amazon SES, spaces are not allowed in any of the parameter values. In this guide, any example
Query request parameter value that includes spaces is displayed in one of two different ways:
URL-encoded (as %20).
Represented by a plus sign ("+"). Within a Query request, a plus sign is reserved as a shorthand
notation for a space. (If you want to include a literal, uninterpreted plus sign in any parameter, you
must URL-encode it as %2B.)
Note
Every request must be accompanied by an X-Amzn-Authorization HTTP header. For
more information, see Request Authentication and Amazon SES (p. 329).
Structure of a POST Request

Amazon SES also accepts POST requests. With a POST request, you send the query parameters as a
form in the HTTP request body as described in the following procedure.
To create a POST request

1.
Assemble the query parameter names and values into a form.

327

Query Requests
Put the parameters and values together as you would for a GET request (with an ampersand
separating each name-value pair). The following example shows a SendEmail request with the
line breaks we use in this guide to make the information easier to read.
Action=SendEmail
&[email protected]
&[email protected]
&Message.Subject.Data=This is the subject line.
&Message.Body.Text.Data=Hello. I hope you are having a good day.
2.
Form-URL-encode the form according to the Form Submission section of the HTML specification.
For more information, see http://www.w3.org/MarkUp/html-spec/html-spec_toc.html#SEC8.2.1.
Action=SendEmail
%20day.
3.
Provide the resulting form as the body of the POST request.
4.
Include the following HTTP headers in the request:

Content-Type, with the value set to application/x-www-form-urlencoded
Content-Length
Date
X-Amzn-Authorization (For more information, see Request Authentication and Amazon
SES (p. 329).)
5.
Send the completed request.
POST / HTTP/1.1
Date: Thu, 26 May 2011 06:49:50 GMT
Host: email.us-west-2.amazonaws.com
Content-Type: application/x-www-form-urlencoded
X-Amzn-Authorization: AWS3
AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE,Signature=lBP67vCvGlDMBQ=dofZxg8E8SUEXAMPLE,Algorit
Content-Length: 230
Action=SendEmail
%20day.
The X-Amzn-Authorization header you provide is the same header you would provide if you sent a
GET request.
Note
Your HTTP client typically adds other items to the HTTP request as required by the version
of HTTP that the client uses. We don't include those additional items in the examples in this
guide.
328

Request Authentication
Request Authentication and Amazon SES

When you make a request to the Amazon SES API, you must provide proof that you are truly the
account holder so that Amazon SES can verify your identity and whether you are registered to use
services offered by AWS. If either test fails, Amazon SES returns an error and does not process the
request.
Amazon SES supports signature version 3 and version 4. Version 4 is preferred. For information about
using signature version 4, see Signature Version 4 Signing Process in the AWS General Reference.
GET and POST Examples for Amazon SES

The following are examples of GET and POST requests, using the Query API.
Example GET Request

Here is an example of what a GET request might look like, including the calculated signature. Notice
that all of the parameters have been URL-encoded.
https://email.us-west-2.amazonaws.com/
?Action=SendEmail
%20day.
&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE
&Signature=RhU864jFu893mg7g9N9j9nr6h7EXAMPLE
&Algorithm=HMACSHA256
Example POST Request

Here is an example of what a POST request might look like, before calculating the signature. Notice
that all of the parameters have been URL-encoded.
POST / HTTP/1.1
Date: Tue, 25 May 2010 21:20:27 +0000
Content-Length: 174
Action=SendRawEmail
&Destinations.member.1=allan%40example.com
&RawMessage.Data=RnJvbTp1c2VyQGV4YW1wbGUuY29tDQpTdWJqZWN0OiBUZXN0DQoNCk1lc3 ...
The value for RawMessage.Data is a base64-encoded representation of the following text.

From:[email protected]
Subject: Test
Message sent using SendRawEmail.
Following is the complete POST request to SendRawEmail, with the X-Amzn-Authorization

header. None of the headers should be URL-encoded.
329

Query Responses
POST / HTTP/1.1
Date: Tue, 25 May 2010 21:20:27 +0000
Content-Length: 174
X-Amzn-Authorization: AWS3-HTTPS
AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE,Algorithm=HMACSHA256,Signature=lBP67vCvGl ...
Action=SendRawEmail
&Destinations.member.1=allan%40example.com
&RawMessage.Data=RnJvbTp1c2VyQGV4YW1wbGUuY29tDQpTdWJqZWN0OiBUZXN0DQoNCk1lc3 ...
Query Responses and Amazon SES

In response to a Query request, Amazon SES returns an XML data structure that contains the results
of the request.
Every Amazon SES response includes a request ID in a RequestId element. The value is a unique
string that AWS assigns. If you ever have issues with a particular request, AWS will ask for the request
ID to help troubleshoot the issue.
Successful Amazon SES responses also include one or more message IDs. You can think of a
message ID as a receipt for an email message that Amazon SES sends. If a message is rejected or
bounced, the message ID will appear in any complaint or bounce notifications that you receive; you
can then use the message ID to identify any problematic email messages that you have sent, and take
corrective action.
Structure of a Successful Response

If the request succeeded, the main response element is named after the action, but with "Response"
appended. For example, SendEmailResponse is the response element returned for a successful
SendEmail request. This element contains the following child elements:
ResponseMetadata, which contains the RequestId child element.
An optional element containing action-specific results. For example, the SendEmailResponse
element includes an element called SendEmailResult.
The XML schema describes the XML response message for each Amazon SES action.
The following is an example of a successful response.
<SendEmailResponse xmlns="https://email.amazonaws.com/doc/2010-03-31/">
<SendEmailResult>
<MessageId>000001271b15238a-fd3ae762-2563-11df-8cd4-6d4e828a9ae8-000000</
MessageId>
</SendEmailResult>
<ResponseMetadata>
<RequestId>fd3ae762-2563-11df-8cd4-6d4e828a9ae8</RequestId>
</ResponseMetadata>
</SendEmailResponse>

330

Query Responses
Structure of an Error Response

If a request is unsuccessful, the main response element is called ErrorResponse regardless of the
action that was called. This element contains an Error element and a RequestId element. Each
Error includes:
A Type element that identifies whether the error was a receiver or sender error
A Code element that identifies the type of error that occurred
A Message element that describes the error condition in a human-readable form
A Detail element that might give additional details about the error or might be empty
The following is an example of an error response.
<ErrorResponse>
<Error>
<Type>
Sender
</Type>
<Code>
ValidationError
</Code>
<Message>
Value null at 'message.subject' failed to satisfy constraint: Member
must not be null
</Message>
</Error>
<RequestId>
42d59b56-7407-4c4a-be0f-4c88daeea257
</RequestId>
</ErrorResponse>

331

Amazon SES Endpoints
Regions and Amazon SES
When you use Amazon Simple Email Service (Amazon SES), you connect to a URL that provides an
endpoint for the Amazon SES API or SMTP interface. Amazon SES has endpoints in multiple AWS
regions. To reduce network latency, it's a good idea to choose an endpoint closest to your application.
This topic contains information you need to know when you use Amazon SES endpoints in multiple
AWS regions. It discusses the following subjects:
Amazon SES Endpoints (p. 332)
Selecting a Region to Use with Amazon SES (p. 333)
Sandbox and Sending Limit Increases (p. 334)
Verification (p. 334)
Easy DKIM Setup (p. 334)
Suppression List (p. 335)
Feedback Notifications (p. 335)
SMTP Credentials (p. 335)
Sending Authorization (p. 336)
Custom MAIL FROM Domains (p. 335)
Email Receiving (p. 336)
For general information about AWS regions, see AWS Regions and Endpoints in the AWS General
Reference.
Amazon SES Endpoints

The following sections list the AWS regions in which Amazon SES is available, and the corresponding
endpoints for sending and receiving emails.
Email Sending Endpoints

The following table lists the endpoints you use for email sending.
332

Email Receiving Endpoints
Region name
API (HTTPS)
endpoint
SMTP endpoint
US East (N.
Virginia)
email.usemail-smtp.us-east-1.amazonaws.com
east-1.amazonaws.com
US West
(Oregon)
email.usemail-smtp.us-west-2.amazonaws.com
west-2.amazonaws.com
EU (Ireland)
email.euemail-smtp.eu-west-1.amazonaws.com
west-1.amazonaws.com
Email Receiving Endpoints

The following table lists the endpoints you use for email receiving.
Region name
API (HTTPS) endpoint
inbound-smtp.us-east-1.amazonaws.com
US West (Oregon)
inbound-smtp.us-west-2.amazonaws.com
EU (Ireland)
inbound-smtp.eu-west-1.amazonaws.com
Selecting a Region to Use with Amazon SES

The following sections describe how to select a region depending on which method you use to call
Amazon SES.
Amazon SES API

When you use the Amazon SES API, you specify an endpoint in the Query request. That endpoint
determines the AWS region you are using. For more information, see Query Requests and Amazon
SES (p. 326).
Amazon SES SMTP Interface

The SMTP interface is for email sending only. When you use the SMTP interface, the SMTP endpoint
you specify in your code or configuration settings determines the AWS region you are using. For more
Amazon SES Console

When you use the Amazon SES console, you can change the endpoint by clicking the region name in
the upper right corner of the navigation bar, as shown in the following screenshot.

333

Sandbox and Sending Limit Increases
Sandbox and Sending Limit Increases

Sandbox status and sending limits apply on a per-region basis. You must request sending limit
increases for each region individually. When you open an SES Sending Limits Increase case in
Support Center, the form has a menu you use to select the AWS region for which you are requesting
a sending limit increase. For more information on increasing your sending limits, see Opening an SES
Sending Limits Increase Case (p. 194).
Verification
Before you send email using Amazon SES, you must verify that you own your email address or
domain with Amazon SES. Verification status for each region is separate, as described in the following
sections.
Email Address Verification

You must verify each sender's email address separately for each region you want to use. For example,
if you verify an email address in the US West (Oregon) region, you will be able to send from it when
you connect to an Amazon SES endpoint in the US West (Oregon) region, but you will not be able to
send from it using an endpoint in the US East (N. Virginia) region until you verify that email address in
the US East (N. Virginia) region. For more information about verifying email addresses, see Verifying
Email Addresses in Amazon SES (p. 39).
Domain Verification
Like email address verification, domain verification applies to each region separately. You must
perform the domain verification procedure for each region in which you want to send from a given
domain. For example, if you want to send email from example.com from both the US West (Oregon)
region endpoint and the US East (N. Virginia) region endpoint, you must add two TXT records to your
DNS settings one record for each region. You generate these records by using the Amazon SES
console with the appropriate region selected, or the Amazon SES API endpoint that corresponds to
the region you want. For more information about verifying domains, see Verifying Domains in Amazon
SES (p. 41).
Easy DKIM Setup

You must perform the Easy DKIM setup procedure for each region in which you want to use Easy
DKIM. That is, for each region, you must use the Amazon SES console or the Amazon SES API to
334

Suppression List
generate TXT records, add the TXT records to your DNS settings, and then use the Amazon SES API
or the Amazon SES console to enable DKIM signing for your chosen sending identity (email address
or domain) within that region. For more information about setting up Easy DKIM, see Easy DKIM in
Amazon SES (p. 94).
Suppression List
Although each region has a separate suppression list, if you remove an address from the suppression
list of one region, the address is removed from the suppression list of all regions. You remove
addresses from the suppression list by using the Amazon SES console. For more information about the
suppression list, see Removing an Email Address from the Amazon SES Suppression List (p. 236).
Feedback Notifications
There are two important points to note about setting up feedback notifications in multiple regions:
Verified identity settings, such as whether you receive feedback by email or through Amazon Simple
Notification Service (Amazon SNS), apply only to the region in which you set them. For example, if
you verify [email protected] in the US West (Oregon) and US East (N. Virginia) regions and you
want to receive bounced emails via Amazon SNS notifications, you must use the Amazon SES API
or the Amazon SES console to set up Amazon SNS feedback notifications for [email protected] in
both regions.
Amazon SNS topics you use for feedback forwarding must be within the same region in which you
are using Amazon SES.
SMTP Credentials
You can use the same set of SMTP credentials in all regions. For more information about SMTP
credentials, see Obtaining Your Amazon SES SMTP Credentials (p. 57).
Custom MAIL FROM Domains

You can use the same custom MAIL FROM domain for verified identities in different AWS regions. If
that is what you want to do, you must still publish only one MX record to the MAIL FROM domain's
DNS server. Bounces returned by ISPs will go to the Amazon SES feedback endpoint in the region
specified in the MX record first, and then Amazon SES will redirect the bounces to the verified identity
in the region that sent the email.
Use the MX record settings that Amazon SES provides during the custom MAIL FROM setup for an
identity in one of the regions. The custom MAIL FROM setup process is described in Setting a MAIL
FROM Domain (p. 47). For reference, you can find the feedback endpoints for all of the regions in the
following table.
Region name
Feedback endpoints for custom MAIL FROM

sending configurations
feedback-smtp.us-east-1.amazonses.com
US West (Oregon)
feedback-smtp.us-west-2.amazonses.com
EU (Ireland)
feedback-smtp.eu-west-1.amazonses.com
335

The delegate sender must send the emails from the AWS region in which the identity owner's identity
is verified. The sending authorization policy that gives permission to the delegate sender must be
attached to the identity in that region. For more information about sending authorization, see Using
Sending Authorization with Amazon SES (p. 196).
Email Receiving
When you receive email with Amazon SES, all of the resources that you use must be in the same
region as the Amazon SES endpoint.
Note
For a list of endpoints for Amazon SES email receiving, see Email Receiving
Endpoints (p. 333).
For example, if you use the Amazon SES endpoint in US West (Oregon), then any Amazon S3 bucket,
Amazon SNS topic, AWS KMS key, and Lambda function that you use must also be in US West
(Oregon). Similarly, to receive mail with Amazon SES within a region, you must have an active receipt
rule set within that region.

336

Limits Related to Email Sending
Limits in Amazon SES

This topic lists limits within Amazon Simple Email Service (Amazon SES).
Limits Related to Email Sending

The following tables list limits related to email sending.
Sending Limits
Note
Sending limits are based on recipients rather than on messages.
Limit
Description
Sending limits in the sandbox

environment
Sending quota: 200 emails per 24-hour period.

Maximum send rate: 1 email per second.
Note
The rate at which Amazon SES accepts your
messages might be less than the maximum
send rate.
To increase your sending limits, open an SES Sending
Limit case in Support Center. For more information, see
Moving Out of the Amazon SES Sandbox (p. 54).
Message Limits
Limit
Description
Maximum message size (including

attachments)
10 MB per message (after base64 encoding).
Accepted header fields
Amazon SES accepts any email headers that follow the

format described in RFC 822.
337

Sender and Recipient Limits
Limit
Description
Accepted attachment types
Amazon SES accepts all file attachment types except

for attachments with file extensions listed in Appendix:
Unsupported Attachment Types (p. 344).
Sender and Recipient Limits

Limit
Description
Sender address
Both in and out of the sandbox, you are required to verify

the "From", "Source", "Sender", and "Return-Path" email
addresses or domains, although not "Reply-To".
Recipient address
In the sandbox environment, all "To" addresses except

for Amazon SES mailbox simulator addresses must be
verified. If you don't want to verify your "To" addresses,
open an SES Sending Limit case in Support Center. For
more information, see Moving Out of the Amazon SES
Sandbox (p. 54).
Maximum number of recipients per

message
50 recipients per message.

A recipient is any "To", "CC", or "BCC" address.
Maximum number of identities you can

verify
1000 identities (domains or email addresses in any

combination) per AWS account per region.
Limits Related to Email Sending Event Publishing

Limit
Description
Maximum number of configuration sets
50
Maximum number of event

destinations per configuration set
10
Maximum number of dimensions per

CloudWatch event destination
10
Amazon EC2-Related Limits

Limit
Description
Email sending over port 25
Amazon EC2 throttles email traffic over port 25 by default.

To avoid timeouts when sending email through the Amazon
SES SMTP endpoint from Amazon EC2, use a different
port (587 or 2587) or fill out a Request to Remove Email
Sending Limitations.

338

Limits Related to Email Receiving
Limits Related to Email Receiving

The following table lists limits related to email receiving.
Limit
Description
Maximum number of rules per receipt

rule set
100
Maximum number of actions per

receipt rule
10
Maximum number of recipients per

receipt rule
100
Maximum number of receipt rule sets

per AWS account
20
Maximum number of IP address filters

per AWS account
100
Maximum email size (including

headers) that can be stored in an
Amazon S3 bucket
30 MB
Maximum email size (including

headers) that can be published using
an Amazon SNS notification
150 KB
General Limits
The following table lists limits that apply to both email sending and email receiving.
Amazon SES API Limits

Limit
Description
Rate at which you can call Amazon

SES API actions
All actions (except for SendEmail and SendRawEmail) are

throttled at one request per second. For more information
about the Amazon SES API, see the Amazon Simple Email

339
Amazon SES Resources

The following table lists resources that you may find useful as you work with Amazon Simple Email
Service (Amazon SES).
Resource
Description
Amazon Simple Email Service API

Reference
The Amazon SES API Reference. Contains complete

descriptions of the API actions, parameters, and data types,
and a list of errors that the service returns.
Amazon Simple Email Service Email

Sending Best Practices whitepaper
A white paper about Amazon SES best practices.
Amazon SES Pricing
Pricing information for Amazon SES.
SES Sending Limits Increase case
The Support Center form to request an increase in your

sending limits and move out of the sandbox.
Request to Remove Email Sending

Limitations
The form to request to remove the default Amazon EC2

sending limits.
Amazon SES Forum
The forum in which Amazon SES users can post questions

and discuss various Amazon SES topics.
Amazon SES Blog
The blog that contains blog posts and announcements by

the Amazon SES team.
AWS Developer Tools
Links to developer tools and resources that provide

documentation, code samples, release notes, and other
information to help you build innovative applications with
AWS.
AWS Support Center
The hub for creating and managing your AWS Support

cases. Also includes links to other helpful resources, such
as forums, technical FAQs, service health status, and AWS
Trusted Advisor.
Contact Us
A central contact point for inquiries concerning AWS billing,

account, events, abuse, and other issues.
AWS Glossary
The AWS Glossary. Contains definitions of common terms

used in Amazon SES and other AWS services.
340
Resource
Description
Conditions of Use
Amazon Web Services Acceptable Use Policy. Describes

email abuse and other prohibited uses of the web services
offered by Amazon Web Services, Inc.

341

Appendix: Header Fields
Amazon SES Developer Guide

Appendix
This appendix contains supplementary information about sending emails through Amazon Simple
Email Service (Amazon SES).
For the header field requirements for emails that you send through Amazon SES, see Appendix:
Header Fields (p. 342).
For a list of attachment types that Amazon SES does not accept, see Appendix: Unsupported
Attachment Types (p. 344).

Amazon SES accepts any email headers that follow the format described in RFC 822.
The following fields cannot appear more than once in a header:
Accept-Language
acceptLanguage (Note: This field is nonstandard. If possible, use Accept-Language instead.)
Archived-At
Auto-Submitted
Bounces-to
Comments
Content-Alternative
Content-Base
Content-Class
Content-Description
Content-Disposition
Content-Duration
342

Content-ID
Content-Language
Content-Length
Content-Location
Content-MD5
Content-Transfer-Encoding
Content-Type
Date (Note: Amazon SES overrides any Date header you provide with the time that Amazon SES
accepts the message. The time zone of the Date header is UTC.)
Delivered-To
Disposition-Notification-Options
Disposition-Notification-To
DKIM-Signature
DomainKey-Signature
Errors-To
From
Importance
In-Reply-To
Keywords
List-Archive
List-Help
List-Id
List-Owner
List-Post
List-Subscribe
List-Unsubscribe
Message-Context
Message-ID (Note: Amazon SES overrides any Message-ID header you provide.)
MIME-Version
Organization
Original-From
Original-Message-ID
Original-Recipient
Original-Subject
Precedence
Priority
References
Reply-To
Return-Path (Note: After Amazon SES uses any Return-Path header you provide, it removes that
header before sending the email.)
Return-Receipt-To
Sender
Solicitation
Sensitivity
Subject
Thread-Index
Thread-Topic
343

Appendix: Unsupported Attachment Types
User-Agent
VBR-Info
Appendix: Unsupported Attachment Types

You can send messages with attachments through Amazon SES by using the Multipurpose Internet
Mail Extensions (MIME) standard. Amazon SES accepts all file attachment types except for
attachments with the file extensions in the following list.
Note
Some ISPs have further limitations (e.g., regarding archived attachments), so we recommend
testing your email sending through major ISPs before you send your production email.
Unsupported Attachment Types

.ade
.adp
.app
.asp
.bas
.bat
.cer
.chm
.cmd
.com
.cpl
.crt
.csh
.der
.exe
.fxp
.gadget
.hlp
.hta
.inf
.ins
.isp
.its
.js
.jse
.ksh
.lib
.lnk
.mad
.maf
.mag
.mam
.maq
.mar
.mas
.mat
.mau
.mav
.maw
.mda
.mdb
.mde
.mdt
.mdw
.mdz
.msc
.msh
.msh1
.msh2
.mshxml
.msh1xml
.msh2xml
.msi
.msp
.mst
.ops
.pcd
.pif
.plg
.prf

344
.prg
.reg
.scf
.scr
.sct
.shb
.shs
.sys
.ps1
.ps1xml
.ps2
.ps2xml
.psc1
.psc2
.tmp
.url
.vb
.vbe
.vbs
.vps
.vsmacros
.vss
.vst
.vsw
.vxd
.ws
.wsc
.wsf
.wsh
.xnk
Amazon SES Developer Guide

Document History
The following table describes the major changes to the documentation to the Amazon Simple Email
Service (Amazon SES) Developer Guide.
API version: 2010-12-01
Latest documentation update: January 18, 2017
Change
Description
Date Changed
New feature
Updated for dedicated IPs.
November 21,
2016
New feature
Updated for email sending event publishing.
November 2,
2016
Service
update
Updated to reflect that users no longer need to explicitly enable

Easy DKIM signing after generating their DKIM records.
September 15,
2016
Documentation Added a getting started tutorial for receiving email.

update
July 12, 2016
New feature
Updated for enhanced notifications.
June 14, 2016
New feature
Updated for custom MAIL FROM domains.
March 14,
2016
New feature
Updated for inbound email.
September 28,
2015
New feature
Updated for sending authorization.
July 8, 2015
New feature
Updated for AWS CloudTrail logging.
May 7, 2015
Service
update
Updated to reflect the consolidation of the Amazon SES limit

increase forms and removed "production access" terminology.
April 8, 2015
Service
update
Updated with new requirements for domain verification TXT

records.
February 25,
2015

345
Change
Description
Date Changed
Documentation Added Enforcement FAQ.

update
December 15,
2014
New feature
Updated for delivery notifications.
June 23, 2014
New feature
Updated for subdomain support.
March 19,
2014
New feature
Updated for Amazon SES expansion to the US West (Oregon)

region.
January 29,
2014
New feature
Updated for Amazon SES expansion to the EU (Ireland) region.
January 15,
2014
New feature
Updated to reflect the changes in validation of Header Fields and

MIME Types.
November 6,
2013
Documentation Removed content on Sender ID.

update
August 22,
2013
New feature
Updated to reflect the Amazon SES console redesign.
June 19, 2013
New feature
Replaced the blacklist with the suppression list.
May 8, 2013
New feature
Updated for the blacklist removal feature.
March 4, 2013
Documentation Added MIME types.

update
February 4,
2013
Documentation Included a Getting Started section to replace the stand-alone

update
Getting Started guide, restructured the Table of Contents, and
updated the Sendmail integration instructions.
January 21,
2013
Documentation Added troubleshooting sections on increasing throughput and

update
SMTP issues.
December 12,
2012
Documentation Restructured the information on sending limits.

update
November 9,
2012
New feature
Updated for the Amazon SES mailbox simulator.
October 3,
2012
New feature
Updated for using a DKIM signature to sign email from a verified

identity.
July 17, 2012
New feature
Updated for receiving bounce and complaint feedback notifications

through Amazon Simple Notification Service (Amazon SNS).
June 26, 2012
New feature
Updated for domain verification.
May 15, 2012
New feature
Updated to reflect additional header and attachment types.
April 25, 2012
New feature
Updated for the STARTTLS extension to SMTP.
March 7, 2012
New feature
Updated for Variable Envelope Return Path (VERP).
February 22,
2012
New feature
Updated for SMTP support.
December 13,
2011

346
Change
Description
Date Changed
New feature
Updated for AWS Management Console support.
November 17,
2011
New feature
Updated for attachment support.
July 18, 2011
Initial release
This is the first release of the Amazon Simple Email Service

Developer Guide.
January 25,
2011

347

Simple Email Service - Developer Guide

Uploaded by

Copyright:

Available Formats

Simple Email Service - Developer Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Simple Email Service - Developer Guide

Uploaded by

Copyright:

Available Formats

Amazon Simple Email Service

Amazon Simple Email Service Developer Guide

Amazon Simple Email Service Developer Guide

Amazon Simple Email Service: Developer Guide

Amazon Simple Email Service Developer Guide

Amazon Simple Email Service Developer Guide

Delegate Sender Tasks ..............................................................................................

Amazon Simple Email Service Developer Guide

Restricting Email Addresses ........................................................................................ 308

API Version 2010-12-01

Amazon Simple Email Service Developer Guide

What Is Amazon SES?

Why use Amazon SES?

Amazon SES and other AWS services

Amazon Simple Email Service Developer Guide

Sending Email (p. 3)

Describes how you can send email using Amazon SES.

Receiving Email (p. 259)

Describes how you can receive email using Amazon SES.

Controlling Access (p. 307)

Shows you how to use Amazon SES with AWS Identity

Logging API Calls (p. 313)

Provides a list of Amazon SES APIs that can be logged

Using Credentials (p. 323)

Explains the types of credentials that you might use with

Using the API (p. 326)

Describes how to use the Amazon SES Query API.

Regions (p. 332)

Limits (p. 337)

Provides a list of limits within Amazon SES.

Resources (p. 340)

Appendix (p. 342)

Provides supplementary information about header fields,

API Version 2010-12-01

Amazon Simple Email Service Developer Guide

Sending Email with Amazon SES

How do I send emails using Amazon SES?

Amazon Simple Email Service Developer Guide

Setting up Email (p. 37)

Using the SMTP Interface (p. 56)

Shows you how to get your Amazon SES SMTP

Using the API (p. 87)

Shows you how to send formatted and raw emails by using

Amazon Simple Email Service Developer Guide

Authenticating Your Email (p. 92)

Shows you how to use DKIM with Amazon SES to show

Monitoring Your Sending

Shows you how to view your usage statistics (such as

Managing Your Sending

Explains the two Amazon SES sending limits (sending

Improving Deliverability (p. 227)

Provides tips about how to improve the percentage of

Using Sending Authorization (p. 196)

Shows you how to authorize other users to send emails

Helps you decide whether to use shared IP addresses

Testing Email Sending (p. 224)

Explains how to use the Amazon SES mailbox simulator

Troubleshooting (p. 229)

Explains common causes of delivery problems and

Amazon SES Email-Sending Concepts