Getting started overview

Getting started with Amazon Simple Email Service (SES) involves a sequence of steps to ensure secure and verified email sending. The process typically begins with setting up an AWS account and configuring Identity and Access Management (IAM) credentials. Following this, you must verify ownership of the email addresses or domains you intend to send from, which is a critical step for maintaining sender reputation and preventing abuse. Once verification is complete, you can use one of the AWS SDKs, the AWS Command Line Interface (CLI), or direct API calls to integrate SES into your application for sending emails.

The following table provides a quick reference to the essential steps for initiating your Amazon SES integration:

Step What to do Where
1. Create AWS Account Sign up for a new AWS account or log in to an existing one. AWS homepage
2. Create IAM User & Keys Generate an IAM user with programmatic access and obtain Access Key ID and Secret Access Key. AWS IAM User Guide
3. Verify Identity Verify an email address or a domain as a sender identity within SES. Amazon SES Developer Guide on identity verification
4. Configure SDK/CLI Install and configure an AWS SDK (e.g., Python Boto3) or the AWS CLI with your credentials. Amazon SES first email guide
5. Send First Email Execute a programmatic call to send an email using the SES API. Amazon SES send email documentation

Create an account and get keys

To begin using Amazon SES, you need an active AWS account. If you do not have one, navigate to the AWS homepage and follow the sign-up process. This typically involves providing an email address, password, and billing information. AWS offers a free tier that includes usage for many services, including a generous free tier for Amazon SES, which covers 62,000 outbound messages per month when sending from an EC2 instance or AWS Lambda.

Once your AWS account is set up, the next critical step is to create an IAM user and obtain access keys. Best practice dictates that you should avoid using your root AWS account credentials for programmatic access. Instead, create a dedicated IAM user with the minimum necessary permissions. For SES, this would typically involve permissions like ses:SendEmail and ses:SendRawEmail to allow sending. You can create an IAM user by following the AWS IAM User Guide for creating IAM users.

During the IAM user creation process, select "Programmatic access" to generate an Access Key ID and a Secret Access Key. These keys are your credentials for authenticating API requests to AWS services, including SES. It is crucial to download and securely store these keys immediately, as the Secret Access Key is only displayed once. If lost, you will need to generate new credentials.

Your first request

Before sending your first email, you must verify the email address or domain you intend to send from. This step is a security measure to prevent unauthorized use and to maintain sender reputation. You can verify an identity in the AWS SES console or programmatically. For an email address, SES sends a verification email that you must click to confirm ownership. For a domain, you typically add specific DNS records (TXT or CNAME) provided by SES to your domain's DNS configuration, as detailed in the Amazon SES Developer Guide on verifying identities. Once verified, the identity's status will change to "verified" in the SES console.

Amazon SES operates in a sandbox environment for new accounts, which means you can only send emails to verified email addresses or from verified identities. To send emails to unverified recipients, you must request production access by following the AWS SES production access request documentation. This request typically involves explaining your use case and ensuring compliance with AWS's sending policies.

To send your first email, you can use an AWS SDK. Here's an example using Python with the Boto3 SDK:


import boto3
from botocore.exceptions import ClientError

# Replace [email protected] with your "From" address.
# This address must be verified with Amazon SES.
SENDER = "Verified Sender <[email protected]>"

# Replace [email protected] with a "To" address.
# If your account is still in the sandbox, this address must be verified.
RECIPIENT = "[email protected]"

# Specify a configuration set. If you do not have one, comment out this line.
# CONFIGURATION_SET = "ConfigSet"

# The AWS Region that you want to use to send the email.
AWS_REGION = "us-east-1"

# The subject line for the email.
SUBJECT = "Amazon SES Test Email (Python boto3)"

# The email body for recipients with HTML email clients.
BODY_HTML = """<html>
<head></head>
<body>
  <h1>Amazon SES Test (boto3 Python)</h1>
  <p>This email was sent with Amazon SES using the
    <a href='https://aws.amazon.com/ses/'>AWS SDK for Python (boto3)</a>.
  </p>
</body>
</html>
"""

# The character encoding for the email.
CHARSET = "UTF-8"

# Create a new SES client and specify a region.
client = boto3.client('ses',region_name=AWS_REGION)

# Try to send the email.
try:
    #Provide the contents of the email.
    response = client.send_email(
        Destination={
            'ToAddresses': [
                RECIPIENT,
            ],
        },
        Message={
            'Body': {
                'Html': {
                    'Charset': CHARSET,
                    'Data': BODY_HTML,
                },
            },
            'Subject': {
                'Charset': CHARSET,
                'Data': SUBJECT,
            },
        },
        Source=SENDER,
        # If you are using a configuration set, uncomment the following line:
        # ConfigurationSetName=CONFIGURATION_SET,
    )
except ClientError as e:
    print(e.response['Error']['Message'])
else:
    print("Email sent! Message ID:")
    print(response['MessageId'])

This Python script uses the boto3 library to interact with SES. Ensure you have boto3 installed (pip install boto3) and your AWS credentials configured, either through environment variables, a shared credentials file, or an IAM role, as described in the Boto3 quickstart guide. The SENDER and RECIPIENT variables must be set correctly, with SENDER being a verified identity in your SES account.

Common next steps

After successfully sending your first email, several common next steps can enhance your Amazon SES integration:

  • Move out of the sandbox: If you plan to send emails to unverified recipients, you must request production access for your SES account. This involves submitting a request form through the AWS console, detailing your use case and estimated sending volumes. Refer to the Amazon SES documentation on requesting production access for guidelines.
  • Set up DKIM and SPF: Implement DomainKeys Identified Mail (DKIM) and Sender Policy Framework (SPF) for your verified domains. These email authentication methods help improve email deliverability and protect your sending reputation by verifying that the email originates from your domain. The Amazon SES Developer Guide provides details on DKIM setup.
  • Monitor sending reputation: Regularly monitor your sending reputation and metrics within the SES console. AWS provides dashboards to track bounces, complaints, and delivery rates. Maintaining a good reputation is crucial for optimal deliverability.
  • Configure event publishing: Set up event publishing to capture data about your email sending activities, such as deliveries, opens, clicks, and bounces. You can publish these events to Amazon CloudWatch, Amazon Kinesis Firehose, or Amazon SNS for analysis and real-time notifications. This is covered in the Amazon SES event publishing documentation.
  • Explore advanced sending options: Investigate features like configuration sets for grouping emails with specific rules (e.g., custom headers, event destinations), email templates for personalized messages, and the SES SMTP interface for applications that require SMTP.
  • Integrate with other AWS services: Leverage other AWS services to enhance your email solution. For example, use AWS Lambda for event-driven processing of incoming emails, Amazon S3 for storing email content, or Amazon DynamoDB for managing subscriber lists. Receiving email with Amazon SES is a common integration point.
  • Review pricing: Understand the Amazon SES pricing model as your usage scales beyond the free tier. Pricing is based on the number of emails sent, data processed, and any optional features utilized.

Troubleshooting the first call

When making your first Amazon SES API call, you might encounter issues. Here are common problems and their solutions:

  • "Not Authorized" or "Access Denied" errors:
    • Issue: Your IAM user lacks the necessary permissions to call SES API actions.
    • Solution: Review your IAM user's policies and ensure they include permissions like ses:SendEmail and ses:SendRawEmail. Check the Amazon SES documentation on controlling access for required permissions.
  • "Email address not verified" error:
    • Issue: The email address or domain specified as the sender (Source) has not been verified in SES.
    • Solution: Verify the sender identity through the SES console or API. If your account is in the sandbox, ensure both sender and recipient email addresses are verified. Refer to the identity verification guide.
  • "Maximum sending rate exceeded" or "Daily sending quota exceeded" error:
    • Issue: You are attempting to send more emails than your current SES sending limits allow. New accounts in the sandbox have strict limits.
    • Solution: Wait until your quota resets, or request a sending limit increase and production access from AWS support if you are still in the sandbox.
  • Incorrect AWS Region:
    • Issue: Your API call is directed to an SES endpoint in a different AWS Region than where your verified identities are configured.
    • Solution: Ensure the AWS_REGION in your code (e.g., us-east-1) matches the region where you verified your email addresses or domains. You can find a list of AWS Regions and Endpoints in the general reference documentation.
  • SDK or CLI configuration issues:
    • Issue: Your AWS SDK or CLI is not correctly configured with your Access Key ID and Secret Access Key.
    • Solution: Double-check your environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), AWS credentials file (~/.aws/credentials), or IAM role configuration. The AWS SDK for JavaScript Developer Guide on credentials offers a good overview of credential management.
  • Email delivery issues (e.g., emails not arriving):
    • Issue: Emails are sent from SES but not reaching the recipient's inbox.
    • Solution: Check your SES sending statistics for bounces or complaints. Ensure your domain's SPF and DKIM records are correctly configured. Verify recipient email addresses are valid. If issues persist, consider enabling event publishing to diagnose delivery failures.