How do I integrate Amazon SES with an Amazon Cognito user pool?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Prerequisites

Amazon Cognito and Amazon SES don't support cross-account integrations. You can't configure an Amazon Cognito user pool in one account, and then integrate the user pool with an Amazon SES email address in a different account.

Configure your Amazon SES account

To prevent fraud and abuse, Amazon SES places all new Amazon SES accounts in the Amazon SES sandbox. When you use an Amazon SES sandbox, review the restrictions. Then, complete the following steps to remove your account from the Amazon SES sandbox:

1. Review the AWS Regions mapping table in Amazon SES email configuration. The mapping table shows the Regions where you can integrate Amazon SES identities with Amazon Cognito user pools. Make sure that you use compatible Regions before you move the Amazon SES account out of the sandbox.
2. Request production access for your Amazon SES account. AWS Support team provides an initial response to your request within 24 hours.

Note: You must switch to the new Amazon Cognito console experience to integrate Amazon Cognito with Amazon SES in the same Region.

You must also verify your domain identities and email addresses in Amazon SES.

Integrate your user pool with a verified identity

Complete the following steps:

1. Sign in to the Amazon Cognito console, and then choose User Pools.
2. Select the user pool.
3. In the Authentication methods menu, select Email configuration. Then, choose Edit.
4. For FROM email address, choose the Amazon SES verified domain identity. For example, example.com.
5. For FROM sender name, enter your email address. For example, admin@example.com.

You can add a custom email address for the domain identity. The UpdateUserPool API configures the Amazon Cognito user pool with an Amazon SES identity.

Example update-user-pool command:

$ aws cognito-idp update-user-pool --user-pool-id example_pool_id --email-configuration SourceArn=arn:aws:ses:example_region:example_account_number:identity/example_domain,EmailSendingAccount=DEVELOPER,From=user@example.com --region example_region  

**Important:**The UpdateUserPool API resets the user pool's existing configuration. To reset the confguration, you must invoke the DescribeUserPool API, and then send all the existing user pool parameters to the UpdateUserPool API.

The following are descriptions for the update-user-pool command:

• example_pool_id corresponds to the Amazon Cognito user pool ID. Example: ap-southeast-1_xxxxxxxx.
• arn:aws:ses:example_region:example_account_number:identity/example_domain is the Amazon Resource Name (ARN) of your Amazon SES domain identity.
• Replace user@example.com with your email identity.
• example_region represents the Region where your Amazon Cognito user pool is. Example: ap-southeast-1.

Troubleshoot errors

Based on your issue, complete the following tasks.

Resolve unverified email address errors

If you try to send an email from an Amazon SES sandbox account to an unverified email address, then you might receive the following error message:

"Email address is not verified. The following identities failed the check in region AP-SOUTHEAST-1: user@example.com."

To resolve this error, move your Amazon SES account out of the sandbox or verify the recipient's email address in Amazon SES.

Missing email messages

If users aren't receiving emails from your Amazon Cognito user pool, then complete the following tasks:

• Use the Amazon Cognito default email configuration or the Amazon SES email configuration to send email messages.
• Verify your updates through the AWS Management Console. Or, run the DescribeUserPool API call.

Example describe-user-pool command:

aws cognito-idp describe-user-pool --user-pool-id example_pool_id --region example_region --query 'UserPool.EmailConfiguration'  

Example output 1:

{  "SourceArn": "arn:aws:ses:us-east-1:123456789012:identity/admin@example.com", 
  "EmailSendingAccount": "DEVELOPER", 
  "From": "admin@example.com" 
}  

Example output 2:

{  "SourceArn": "arn:aws:ses:us-east-1:123456789012:identity/admin@example.com", 
  "EmailSendingAccount": "COGNITO_DEFAULT" 
}  

If EmailSendingAccount is DEVELOPER, then your user pool uses Amazon SES to send email messages. You can also review the Amazon SES logs for more information on delivery issues.

If EmailSendingAccount is COGNITO_DEFAULT, then your user pool uses Amazon Cognito's default email functionality to send email messages. This functionality has a quota on emails sent per user pool that can cause daily email quota errors.

Resolve daily email quota errors

If you exceed the quota for Amazon Cognito's default email configuration, then you might get the following error message:

"Exceeded daily email limit for the operation or account. Number of allowed operation has exceeded. If a higher limit is required, please configure your user pool to use your own Amazon SES configuration for sending email messages."

To resolve this error message, configure your user pool to use your own Amazon SES configuration for sending emails. This configuration increases your Amazon SES sending quotas.

Related information

Why doesn't Amazon Cognito send the verification code email or SMS text message with the ForgotPassword API call?