Amazon SES Now Includes Original Message Headers in Notifications

The Amazon SES team is pleased to announce the addition of original email headers to the bounce, complaint, and delivery notifications SES provides through Amazon SNS.

We strive to make your email-sending process easier, and today we’re taking another step in that direction. Increasing your visibility into the feedback you receive from SES has always been a key focus for us. Starting today, the headers you pass to SES in your email-sending requests can be made available in your SNS notifications. Read on for answers to some common questions.

How do I enable this feature?

Use the Amazon SES console or API to configure the notification settings for an identity (email address or domain) and notification type (bounce, complaint, or delivery).

For example, to use the SES console to include the original headers for an identity’s bounce notifications, you’d go to the notification settings for an identity and select Include original headers next to the bounce notification configuration:

After this feature is enabled, the notifications will contain the headers in both raw name/value format and in JSON format for commonly provided headers.

How can I leverage this feature in my email sending?

When SES successfully enqueues your email, it returns a unique message identifier (message ID). Previously, to associate an SNS notification to an original message send request, you needed to store a mapping between your own message identifier and the SES message ID. You no longer need to do that. You can include your identifier as a custom header, or even in the Message-ID header, and SES will return that to you, removing the need for you to maintain your own mapping.

You can also now leverage custom message headers to easily separate subsets of your email stream. For example, say you suspect that a specific type of email you send through SES may be causing a higher than usual complaint rate. You can mark those emails with a custom header value, and later perform a programmatic analysis on the received SNS notifications to see how the marked emails are behaving compared to your overall sending.

How about decoding header values? Does SES help me there?

SES unfolds and decodes the header values for you. If SES isn’t able to decode a header, it will return the raw provided value.

Are there any limits to the headers in the notifications?

There is no limit on the number of headers SES returns to you, but 10 KB is the maximum header size for each notification. If your header section surpasses 10 KB, SES will return the first 10 KB of headers and set headersTruncated to true.

Does this change have any impact on how SES processes messages?

No. SES still adds or overwrites specific headers like Date and Message-ID. Check out our header appendix for more information.

Is there any potential for this change to impact my notification parser?

If you do not enable this feature by using the SES console or API, your notifications will remain the same. If you enable the feature, standard JSON parsers will continue to parse the notifications correctly. If you do custom parsing, please check your parser implementation to ensure that it still works with SES notifications. As an example, line parsers are not always compatible with the addition of new information, and would therefore need to be updated to accommodate the new header fields.

For examples of bounce, complaint, and delivery SNS notifications, check out our developer guide.

We hope you find this feature useful! If you have any questions or comments, let us know in the SES Forum or here in the comment section of the blog.