Menu
Amazon Simple Email Service
Developer Guide

Automatically Pausing Email Sending for Your Amazon SES Account

The procedures in this section explain the steps to set up Amazon SES, Amazon SNS, Amazon CloudWatch, and AWS Lambda to automatically pause email sending for your Amazon SES account.

Part 1: Create an IAM Role

The first step in configuring automatic pausing of email sending is to create an IAM role that can execute the UpdateAccountSendingEnabled API operation.

To create the IAM role

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane on the left, choose Roles.

  3. Choose Create role.

  4. Under Select type of trusted entity, choose AWS service.

  5. Under Choose the service that will use this role, choose Lambda. Choose Next: Permissions.

  6. On the Attach permissions policies page, choose the following policies:

    • AWS LambdaBasicExecutionRole

    • AmazonSESFullAccess

    Tip

    Use the search box at the top of the list of policies to quickly locate these policies.

    Choose Next: Review.

  7. On the Review page, for Name, type a name for the role. Choose Create role.

Part 2: Package the Lambda Function

Because Lambda uses a version of the AWS SDK for JavaScript in Node.js that does not currently include the UpdateAccountSendingEnabled operation, you must package the latest version of the SDK in a .zip file that also contains your Lambda function. This section contains procedures for writing and packaging the Lambda script.

To package the Lambda function

  1. On your computer, create a new folder in which you will store the Lambda function and the SDK for JavaScript in Node.js.

  2. At the command line, navigate to the folder you created in the previous step.

  3. At the command line, type the following command to create an npm configuration file: npm init --yes

  4. At the command line, type the following command to download and install the SDK for JavaScript in Node.js: npm install aws-sdk

  5. In a text editor, create a new file. Paste the following code into the file:

    Copy
    'use strict'; var aws = require('aws-sdk'); // Create a new SES object. var ses = new aws.SES(); // Specify the parameters for this operation. var params = { Enabled: false }; exports.handler = (event, context, callback) => { // Pause sending for your entire SES account ses.updateAccountSendingEnabled(params, function(err, data) { if(err) { console.log(err.message); } else { console.log(data); } }); }

    Save the file as index.js in the directory you created in step 1.

  6. Add the contents of the folder you created in step 1 to a .zip file. The .zip file should contain the following items:

    • node_modules – A directory that contains the SDK for JavaScript in Node.js and its dependencies.

    • index.js – The file you created in step 5.

    • package.json – The configuration file that was generated when you ran the npm init command.

    Important

    When you create the .zip file, you must compress the contents of the directory, and not the directory itself. To learn more about creating the .zip file, see Create an Application Source Bundle in the AWS Elastic Beanstalk Developer Guide.

Part 3: Upload and Test the Lambda Function

The next step in configuring automatic pausing of email sending is to upload the package you created in the previous section to Lambda and test it.

To create the Lambda function

  1. Open the AWS Lambda console at https://console.aws.amazon.com/lambda/.

  2. Choose Create function.

  3. Choose Author from scratch.

  4. On the Basic information page, complete the following steps:

    • For Name, type a name for the Lambda execution role.

    • For Role, select Choose an existing role.

    • For Existing role, choose the IAM role you created in Part 1: Create an IAM Role.

    • Choose Create function.

  5. In the Function code section, for Code entry type, choose Upload a .ZIP file.

  6. Under Function package, choose Upload. Choose the .zip file you created in Part 2: Package the Lambda Function.

  7. Choose Save and test.

  8. If the Configure test event window appears, type a name in the Event name field, and then choose Create.

  9. Choose Test. Ensure that the notification bar at the top of the page says Execution result: succeeded. If the function failed to execute, do the following:

    • Verify that the IAM role you created in Part 1: Create an IAM Role contains the correct policies.

    • Verify that the code in the Lambda function you created in Part 2: Package the Lambda Function does not contain any syntax errors. To check for errors, you can execute the code on your local computer or use an online JavaScript syntax checker.

    • Verify that when you created the .zip file in Part 2: Package the Lambda Function, you zipped only the contents of the directory that contains your code, and not the entire directory.

Part 4: Re-Enable Email Sending for Your Account

A side effect of testing the Lambda function in Part 3: Upload and Test the Lambda Function is that email sending for your Amazon SES account is paused. In most cases, you do not want to pause sending for your account until the CloudWatch alarm is triggered.

The procedures in this section re-enable email sending for your Amazon SES account. To complete these procedures, you must install and configure the AWS Command Line Interface. For more information, see the AWS Command Line Interface User Guide.

To re-enable email sending

  1. At the command line, type the following command to re-enable email sending for your account: aws ses update-account-sending-enabled --enabled

  2. At the command line, type the following command to ensure that email sending is enabled: aws ses get-account-sending-enabled

    If you see the following output, then you have successfully re-enabled email sending for your account:

    {
        "Enabled": true 
    }

Part 5: Create an Amazon SNS Topic

For CloudWatch to execute your Lambda function when an alarm is triggered, you must first create an Amazon SNS topic and subscribe the Lambda function to it.

To create the Amazon SNS topic

  1. Open the Amazon SNS console at https://console.aws.amazon.com/sns/v2/home.

  2. In the navigation pane on the left, choose Topics.

  3. Choose Create new topic.

  4. On the Create new topic window, for Topic name, type a name for the topic. Optionally, you can type a more descriptive name in the Display name field.

    Choose Create topic.

  5. In the list of topics, check the box next to the topic you created in the previous step. On the Actions menu, choose Subscribe to topic.

  6. On the Create subscription window, make the following selections:

  7. Choose Create subscription.

Part 6: Create a CloudWatch Alarm

This section contains procedures for creating an alarm in CloudWatch that is triggered when a metric reaches a certain threshold. When the alarm is triggered, it delivers a notification to the Amazon SNS topic you created in Part 5: Create an Amazon SNS Topic, which then executes the Lambda function you created in Part 3: Upload and Test the Lambda Function.

To create a CloudWatch alarm

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

  2. In the navigation pane on the left, choose Alarms.

  3. Choose Create Alarm.

  4. On the Create Alarm window, under SES Metrics, choose Account Metrics.

  5. Under Metric Name, choose one of the following options:

    • Reputation.BounceRate – Choose this metric if you want to pause email sending for your account when the overall hard bounce rate for your account crosses a threshold that you define.

    • Reputation.ComplaintRate – Choose this metric if you want to pause email sending for your account when the overall complaint rate for your account crosses a threshold that you define.

    Choose Next.

  6. Complete the following steps:

    • Under Alarm Threshold, for Name, type a name for the alarm.

    • Under Whenever: Reputation.BounceRate or Whenever: Reputation.ComplaintRate, specify the threshold that will cause the alarm to trigger.

      Note

      Your account is automatically placed on probation if your bounce rate exceeds 10%, or if your complaint rate exceeds .5%. When you specify the bounce or complaint rate that will cause the CloudWatch alarm to trigger, we recommend that you use values that are below these rates to prevent your account from being placed on probation.

    • Under Actions, for Whenever this alarm, choose State is ALARM. For Send notification to, choose the Amazon SNS topic you created in Part 5: Create an Amazon SNS Topic.

    Choose Create Alarm.

(Optional) Part 7: Test the solution

You can now test the alarm to ensure that it executes the Lambda function when it enters the ALARM state. You can use the SetAlarmState API operation to temporarily change the state of the alarm.

The procedures in this section are optional, but we recommend that you complete them to ensure that the entire solution is configured correctly.

  1. At the command line, type the following command to check the email sending status for your account: aws ses get-account-sending-enabled

    If sending is enabled for your account, you will see the following output:

    {
        "Enabled": true 
    }
  2. At the command line, type the following command to temporarily change the alarm state to ALARM: aws cloudwatch set-alarm-state --alarm-name MyAlarm --state-value ALARM --state-reason "Testing execution of Lambda function"

    Replace MyAlarm in the preceding command with the name of the alarm you created in Part 6: Create a CloudWatch Alarm.

    Note

    When you execute this command, the status of the alarm switches from OK to ALARM and back to OK within a few seconds. You can view these status changes on the alarm's History tab in the CloudWatch console, or by using the DescribeAlarmHistory operation.

  3. At the command line, type the following command to check the email sending status for your account: aws ses get-account-sending-enabled

    If the Lambda function executed successfully, you will see the following output:

    {
        "Enabled": false
    }
  4. Complete the steps in Part 4: Re-Enable Email Sending for Your Account to re-enable email sending for your account.