Menu
Amazon Simple Email Service
Developer Guide

Contents of Amazon SES Event Data Published to Kinesis Firehose

Amazon SES publishes email sending event records to Amazon Kinesis Firehose in JSON format. When publishing events to Kinesis Firehose, Amazon SES follows each JSON record with a newline character.

The top-level JSON object contains an eventType string, a mail object, and either a bounce, complaint, delivery, send, reject, open or click object, depending on the type of event.

See the following sections for descriptions of the different types of objects:

Top-Level JSON Object

The top-level JSON object in an email sending event record contains the following fields.

Field Name Description

eventType

A string that holds the type of email sending event represented by the JSON object. Possible values are Bounce, Complaint, Delivery, Send, Reject, Open and Click.

mail

A JSON object that contains information about the original mail to which the event pertains.

bounce

This field is present only if the eventType is Bounce. It contains a JSON object that holds information about the bounce.

complaint

This field is present only if the eventType is Complaint. It contains a JSON object that holds information about the complaint.

delivery

This field is present only if the eventType is Delivery. It contains a JSON object that holds information about the delivery.

send

This field is present only if the eventType is Send.

reject

This field is present only if the eventType is Reject. It contains a JSON object that holds information about the rejection.

open

This field is present only if the eventType is Open. It contains a JSON object that holds information about the open event.

click

This field is present only if the eventType is Click. It contains a JSON object that holds information about the click event.

Mail Object

Each email sending event record contains information about the original email in the mail object. The JSON object that contains information about a mail object has the following fields.

Field Name Description

timestamp

The time at which the message was sent, displayed in ISO8601 format (YYYY-MM-DDThh:mm:ss.sZ).

messageId

A unique ID that Amazon SES assigned to the message. Amazon SES returned this value to you when you sent the message.

Note

This message ID was assigned by Amazon SES. You can find the message ID of the original email in the headers and commonHeaders fields of the mail object.

source

The email address from which the original message was sent (the envelope MAIL FROM address).

sourceArn

The Amazon Resource Name (ARN) of the identity that was used to send the email. In the case of sending authorization, the sourceArn is the ARN of the identity that the identity owner authorized the delegate sender to use to send the email. For more information about sending authorization, see Using Sending Authorization.

sendingAccountId

The AWS account ID of the account that was used to send the email. In the case of sending authorization, the sendingAccountId is the delegate sender's account ID.

destination

A list of email addresses that were recipients of the original mail.

headersTruncated

A string that specifies whether the headers are truncated in the notification, which occurs if the headers are larger than 10 KB. Possible values are true and false.

headers

A list of the email's original headers. Each header in the list has a name field and a value field.

Note

Any message ID within the headers field is from the original message that you passed to Amazon SES. The message ID that Amazon SES subsequently assigned to the message is in the messageId field of the mail object.

commonHeaders

A list of the email's original, commonly used headers. Each header in the list has a name field and a value field.

Note

Any message ID within the commonHeaders field is from the original message that you passed to Amazon SES. The message ID that Amazon SES subsequently assigned to the message is in the messageId field of the mail object.

Bounce Object

The JSON object that contains information about a Bounce event will always have the following fields.

Field Name Description

bounceType

The type of bounce, as determined by Amazon SES.

bounceSubType

The subtype of the bounce, as determined by Amazon SES.

bouncedRecipients

A list that contains information about the recipients of the original mail that bounced.

timestamp

The date and time at which the bounce was sent, displayed in ISO8601 format (YYYY-MM-DDThh:mm:ss.sZ). This is the time at which the ISP sent the bounce notification, which is different from the time at which it was received by Amazon SES.

feedbackId

A unique ID for the bounce.

reportingMTA

The value of the Reporting-MTA field from the DSN. This is the value of the Message Transfer Authority (MTA) that attempted to perform the delivery, relay, or gateway operation described in the DSN.

Note

This field only appears if a delivery status notification (DSN) was attached to the bounce.

Bounced Recipients

A bounce event may pertain to a single recipient or to multiple recipients. The bouncedRecipients field holds a list of objects—one object per recipient to whom the bounce event pertains—and will always contain the following field.

Field Name Description

emailAddress

The email address of the recipient. If a DSN is available, this is the value of the Final-Recipient field from the DSN.

Optionally, if a DSN is attached to the bounce, the following fields may also be present.

Field Name Description

action

The value of the Action field from the DSN. This indicates the action performed by the reporting MTA as a result of its attempt to deliver the message to this recipient.

status

The value of the Status field from the DSN. This is the per-recipient transport-independent status code that indicates the delivery status of the message.

diagnosticCode

The status code issued by the reporting MTA. This is the value of the Diagnostic-Code field from the DSN. This field may be absent in the DSN (and therefore also absent in the JSON).

Bounce Types

Each bounce event will be of one of the types shown in the following table.

The event publishing system only publishes hard bounces and soft bounces that will no longer be retried by Amazon SES. When you receive bounces marked Permanent, you should remove the corresponding email addresses from your mailing list; you will not be able to send to them in the future. Transient bounces are sent to you when a message has soft bounced several times, and Amazon SES has stopped trying to re-deliver it. You may be able to successfully resend to an address that initially resulted in a Transient bounce in the future.

bounceType bounceSubType Description

Undetermined

Undetermined

Amazon SES was unable to determine a specific bounce reason.

Permanent

General

Amazon SES received a general hard bounce. If you receive this type of bounce, you should remove the recipient's email address from your mailing list.

Permanent

NoEmail

Amazon SES received a permanent hard bounce because the target email address does not exist. If you receive this type of bounce, you should remove the recipient's email address from your mailing list.

Permanent

Suppressed

Amazon SES has suppressed sending to this address because it has a recent history of bouncing as an invalid address. For information about how to remove an address from the suppression list, see Removing an Email Address from the Amazon SES Suppression List.

Transient

General

Amazon SES received a general bounce. You may be able to successfully send to this recipient in the future.

Transient

MailboxFull

Amazon SES received a mailbox full bounce. You may be able to successfully send to this recipient in the future.

Transient

MessageTooLarge

Amazon SES received a message too large bounce. You may be able to successfully send to this recipient if you reduce the size of the message.

Transient

ContentRejected

Amazon SES received a content rejected bounce. You may be able to successfully send to this recipient if you change the content of the message.

Transient

AttachmentRejected

Amazon SES received an attachment rejected bounce. You may be able to successfully send to this recipient if you remove or change the attachment.

Complaint Object

The JSON object that contains information about a Complaint event has the following fields.

Field Name Description

complainedRecipients

A list that contains information about recipients that may have submitted the complaint.

timestamp

The date and time at which the bounce was sent, displayed in ISO8601 format (YYYY-MM-DDThh:mm:ss.sZ). Note that this is the time at which the complaint notification was sent by the ISP, and not the time at which it was received by Amazon SES.

feedbackId

A unique ID for the complaint.

Further, if a feedback report is attached to the complaint, the following fields may be present.

Field Name Description

userAgent

The value of the User-Agent field from the feedback report. This indicates the name and version of the system that generated the report.

complaintFeedbackType

The value of the Feedback-Type field from the feedback report received from the ISP. This contains the type of feedback.

arrivalDate

The value of the Arrival-Date or Received-Date field from the feedback report in ISO8601 format (YYYY-MM-DDThh:mm:ss.sZ). This field may be absent in the report (and therefore also absent in the JSON).

Complained Recipients

The complainedRecipients field contains a list of recipients that may have submitted the complaint.

Important

Since most ISPs redact the email address of the recipient who submitted the complaint from their complaint notification, this list contains information about recipients who might have sent the complaint, based on the recipients of the original message and the ISP from which we received the complaint. Amazon SES performs a lookup against the original message to determine this recipient list.

JSON objects in this list contain the following field.

Field Name Description

emailAddress

The email address of the recipient.

Complaint Types

You may see the following complaint types in the complaintFeedbackType field as assigned by the reporting ISP, according to the Internet Assigned Numbers Authority website:

Field Name Description

abuse

Indicates unsolicited email or some other kind of email abuse.

auth-failure

Email authentication failure report.

fraud

Indicates some kind of fraud or phishing activity.

not-spam

Indicates that the entity providing the report does not consider the message to be spam. This may be used to correct a message that was incorrectly tagged or categorized as spam.

other

Indicates any other feedback that does not fit into other registered types.

virus

Reports that a virus is found in the originating message.

Delivery Object

The JSON object that contains information about a Delivery event will always have the following fields.

Field Name Description

timestamp

The time Amazon SES delivered the email to the recipient's mail server, displayed in ISO8601 format (YYYY-MM-DDThh:mm:ss.sZ).

processingTimeMillis

The time in milliseconds between when Amazon SES accepted the request from the sender to when Amazon SES passed the message to the recipient's mail server.

recipients

A list of the intended recipients of the email to which the delivery event applies.

smtpResponse

The SMTP response message of the remote ISP that accepted the email from Amazon SES. This message will vary by email, by receiving mail server, and by receiving ISP.

reportingMTA

The host name of the Amazon SES mail server that sent the mail.

Send Object

The JSON object that contains information about a send event is always empty.

Reject Object

The JSON object that contains information about a Reject event will always have the following fields.

Field Name Description

reason

The reason the email was rejected. The only possible value is Bad content, which means that Amazon SES detected that the email contained a virus.

Open Object

The JSON object that contains information about a Open event will always contain the following fields.

Field Name Description

ipAddress

The recipient's IP address.

timestamp

The time at which the open event occurred, displayed in ISO8601 format (YYYY-MM-DDThh:mm:ss.sZ).

userAgent

The user agent of the device or email client that the recipient used to open the email.

Click Object

The JSON object that contains information about a Click event will always contain the following fields.

Field Name Description

ipAddress

The recipient's IP address.

timestamp

The time at which the click event occurred, displayed in ISO8601 format (YYYY-MM-DDThh:mm:ss.sZ).

userAgent

The user agent of the device or email client from which the recipient clicked a link in the email.

link

The URL of the link that the recipient clicked.

linkTags

A list of tags that were added to the link using the ses:tags attribute. For more information about adding tags to links in your emails, see Q5. Can I tag links with unique identifiers? in the Amazon SES Email Sending Metrics FAQs.