AWS Blog

Programmable Feedback Notification for the Simple Email Service

by Jeff Barr | on | in Amazon SES, Amazon Simple Notification Service | | Comments

The Amazon Simple Email Service (SES) gives you the power to programmatically send bulk or transactional emails from your application. Whether you send a few messages per month or millions every day, SES is able to accommodate you with a cost-effective, pay-as-you-go pricing model.

SES helps you to manage deliverability, the likelihood that an email you send will actually end up in the desired mailbox. In order for you to maximize deliverability, it is important that you keep your list of email addresses clean. For example, you need to handle complaints from ISPs and you need to properly handle temporary and permanent bounces.

Until now, SES delivered bounces and complaints to your mailbox. In order to respond, you had to identify and fetch the proper messages, parse them, and then figure out what to do.

Today, we are giving you a mechanism to simplify that process. You can now arrange for SES to notify you of bounces and complaints by sending JSON-formatted messages to the SNS (Simple Notification Service) topics of your choice.

You can set this up by calling the SetIdentityNotificationTopic API or you can simply specify the topics in the AWS Management Console, like this:

You can set this up for each of the domains or email addresses that you use to send email, on a per-sender basis. Once set up, bounces and complaints will be routed to the topic. If the topic is deleted or becomes inaccessible, SES will revert to email-based notification.

Each notification contains three top-level fields:

  1. A notification type (either Bounce or Complaint).
  2. A Mail object with information about the mail message that triggered the notification.
  3. A Bounce object or a Complaint object, based on the value of the first field.

The Mail object looks like this:

{
    “timestamp” : “2012-05-25T14:59:38.623-07:00” ,
    “messageId” : “000001378603177f-7a5433e7-8edb-42ae-af10-f0181f34d6ee-000000” ,
    “source” : “sender@example.com” ,
    “destination” : [
      “recipient1@example.com” ,
      “recipient2@example.com” ,
      “recipient3@example.com” ,
      “recipient4@example.com”
    ]
}

The Bounce object looks like this:

{
    “bounceType” : “Permanent” ,
    “bounceSubType” : “General” ,
    “bouncedRecipients” : [
      {
          “status” : “5.0.0” ,
          “action” : “failed” ,
          “diagnosticCode” : “smtp; 550 user unknown” ,
          “emailAddress” : “recipient1@example.com”
      } ,
      {
          “status” : “4.0.0” ,
          “action” : “delayed” ,
          “emailAddress” : “recipient2@example.com”
      }
    ] ,
    “reportingMTA” : “example.com” ,
    “timestamp” : “2012-05-25T14:59:38.605-07:00” ,
    “feedbackId” : “000001378603176d-5a4b5ad9-6f30-4198-a8c3-b1eb0c270a1d-000000”
}

The bounceType can be Undetermined, Permanent (you should stop sending email to the indicated recipients), or Transient (you can try again, after examining the bounceSubType to learn more about what caused the bounce).

And the Complaint object looks like this:

{
    “userAgent” : “Comcast Feedback Loop (V0.01)” ,
    “complainedRecipients” : [
      {
          “emailAddress” : “recipient1@example.com”
      }
    ] ,
    “complaintFeedbackType” : “abuse” ,
    “arrivalDate” : “Thu, 03 Dec 2009 04:24:21 -0500” ,
    “timestamp” : “2012-05-25T14:59:38.623-07:00” ,
    “feedbackId” : “000001378603177f-18c07c78-fa81-4a58-9dd1-fedc3cb8f49a-000000”
}

The complaintFeedbackType can be abuse, auth-failure, fraud, not-spam, virus, or other. The appropriate response to a complaint will depend on this field and on the recipient(s).

And there you have it! Consult the Amazon SES Documentation to learn more about this new feature.

— Jeff;