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

Short description

Amazon SES and Amazon Cognito can be integrated to send email messages with a custom email address that you own. Follow these high-level steps to integrate Amazon SES with an Amazon Cognito user pool:

• Consider the limitations of the Amazon SES sandbox.
• Move an account out of the Amazon SES sandbox.
• Verify an Amazon SES identity.
• Configure an Amazon Cognito user pool with an Amazon SES verified identity.

Resolution

Implement the following steps to integrate Amazon SES with an Amazon Cognito user pool for sending email messages on your behalf.

Limitations of the Amazon SES sandbox

All new Amazon SES accounts are placed in the Amazon SES sandbox to prevent fraud and abuse. There are restrictions to consider when using an Amazon SES sandbox. To review the specific sandbox restrictions, see Moving out of the Amazon SES sandbox. You must move your Amazon SES account out of the sandbox to fully use the Amazon SES service.

Move an account out of the Amazon SES sandbox

To move an account out of the Amazon SES sandbox, follow these steps:

1.    Review the AWS Regions mapping table in Amazon SES email configuration. The mapping table shows the Regions where Amazon SES identities can be integrated with Amazon Cognito user pools. You must 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. After your production access request is approved, you can send email messages to any recipient.

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

Verify an Amazon SES identity

To verify an Amazon SES domain identity, follow these steps:

1.    Create a domain identity.

2.    Verify one or more domains in Amazon SES.

To verify an Amazon SES email identity, follow these steps:

1.    Create an email identity.

2.    Verify one or more email addresses in Amazon SES.

Note: Cross-account integrations for Amazon Cognito and Amazon SES aren't supported. You can't configure an Amazon Cognito user pool in one account and integrate it with an Amazon SES email address in a different account.

Configure an Amazon Cognito user pool with an Amazon SES verified identity

To integrate the Amazon Cognito user pool with the verified Amazon SES identity configuration, follow the steps that are relevant to your use case.

When the Amazon SES domain identity is verified

1.    Sign in to the new Amazon Cognito console and then choose User Pools.

2.    Select the appropriate user pool from the list.

3.    Choose the Messaging tab, Email configuration, and then Edit.

4.    Under FROM email address, choose the Amazon SES verified domain identity. (For example, example.com.)

5.    Under FROM sender name, enter your email address. (For example, admin@example.com.)

Because the domain is already verified, 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: Because the UpdateUserPool API resets the user pool's existing configuration, invoke the DescribeUserPool API first. Then, send all the existing user pool parameters to the UpdateUserPool API.

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 ARN of your Amazon SES domain identity.
• user@example.com must be replaced with your email identity.
• example_region represents the Region where your Amazon Cognito user pool exists. Example: ap-southeast-1.

When the Amazon SES email identity is verified

1.    Sign in to the new Amazon Cognito console and then choose User Pools.

2.    Select the appropriate user pool from the list.

3.    Choose the Messaging tab, Email configuration, and then choose Edit.

4.    Under FROM email address, choose the Amazon SES email domain identity. (For example, admin@example.com.)

Error troubleshooting

This section includes information about troubleshooting errors that users encounter when sending email messages after integrating Amazon Cognito and Amazon SES.

Error for unverified email address

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

Amazon Cognito receives the unverified email address error when attempting to send an email message. You can get this error when you try sending an email message from an account in an Amazon SES sandbox to an unverified email address. To resolve the error, move your Amazon SES account out of the sandbox or verify the recipient's email address in Amazon SES.

Users aren't receiving email messages from Amazon Cognito

Users aren't receiving email messages from an Amazon Cognito user pool. To resolve this issue, confirm whether you're using the Amazon Cognito default email functionality or the Amazon SES email configuration for sending email messages. Verify your updates through the AWS Management Console or by invoking the DescribeUserPool API.

Example describe-user-pool command:

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

Output:

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

-or-

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

If the EmailSendingAccount configuration is set to DEVELOPER, then your Amazon Cognito user pool is using Amazon SES to send email messages. Verify that your Amazon SES account is in the sandbox. If it is, then move Amazon SES out of the sandbox for sending email messages to unverified identities. If the Amazon SES account is in production or out of the sandbox mode, then check the Amazon SES logs for email delivery.

If you receive the COGNITO_DEFAULT message in your output, then your Amazon Cognito user pool is using default functionality to send email messages. With this default functionality, Amazon Cognito has a quota limit on the number of email messages sent by each user pool.

LimitExceededException exception is thrown

"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."

Users receive the daily email limit error when Amazon Cognito uses default email functionality with a daily quota limit to send email messages. As suggested in the error message, set a higher email message delivery volume by changing the Amazon SES email configuration.

---