Amazon Pinpoint
Developer Guide

Email Events

When you send email messages, Amazon Pinpoint streams data that provides additional information about the following types of events:

  • Sends

  • Deliveries

  • Bounces

  • Complaints

  • Opens

  • Clicks

  • Rejections

  • Unsubscribes

The event types in the preceding list are explained in detail in Email Event Attributes.

Sample Events

Email Send

The JSON object for an email send event contains the data shown in the following example.

{ "event_type": "_email.send", "event_timestamp": 1564618621380, "arrival_timestamp": 1564618622025, "event_version": "3.1", "application": { "app_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "sdk": {} }, "client": { "client_id": "9a311b17-6f8e-4093-be61-4d0bbexample" }, "device": { "platform": {} }, "session": {}, "attributes": { "feedback": "received" }, "awsAccountId": "123456789012", "facets": { "email_channel": { "mail_event": { "mail": { "message_id": "0200000073rnbmd1-mbvdg3uo-q8ia-m3ku-ibd3-ms77kexample-000000", "message_send_timestamp": 1564618621380, "from_address": "sender@example.com", "destination": ["recipient@example.com"], "headers_truncated": false, "headers": [{ "name": "From", "value": "sender@example.com" }, { "name": "To", "value": "recipient@example.com" }, { "name": "Subject", "value": "Amazon Pinpoint Test" }, { "name": "MIME-Version", "value": "1.0" }, { "name": "Content-Type", "value": "multipart/alternative; boundary=\"----=_Part_314159_271828\"" }], "common_headers": { "from": "sender@example.com", "to": ["recipient@example.com"], "subject": "Amazon Pinpoint Test" } }, "send": {} } } } }

Email Delivered

The JSON object for an email send event contains the data shown in the following example.

{ "event_type": "_email.delivered", "event_timestamp": 1564618621380, "arrival_timestamp": 1564618622690, "event_version": "3.1", "application": { "app_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "sdk": {} }, "client": { "client_id": "e9a3000d-daa2-40dc-ac47-1cd34example" }, "device": { "platform": {} }, "session": {}, "attributes": { "feedback": "delivered" }, "awsAccountId": "123456789012", "facets": { "email_channel": { "mail_event": { "mail": { "message_id": "0200000073rnbmd1-mbvdg3uo-q8ia-m3ku-ibd3-ms77kexample-000000", "message_send_timestamp": 1564618621380, "from_address": "sender@example.com", "destination": ["recipient@example.com"], "headers_truncated": false, "headers": [{ "name": "From", "value": "sender@example.com" }, { "name": "From", "value": "recipient@example.com" }, { "name": "Subject", "value": "Amazon Pinpoint Test" }, { "name": "MIME-Version", "value": "1.0" }, { "name": "Content-Type", "value": "multipart/alternative; boundary=\"----=_Part_314159_271828\"" }], "common_headers": { "from": "sender@example.com", "to": ["recipient@example.com"], "subject": "Amazon Pinpoint Test" } }, "delivery": { "smtp_response": "250 ok: Message 82080542 accepted", "reporting_mta": "a8-53.smtp-out.amazonses.com", "recipients": ["recipient@example.com"], "processing_time_millis": 1310 } } } } }

Email Click

The JSON object for an email click event contains the data shown in the following example.

{ "event_type": "_email.click", "event_timestamp": 1564618621380, "arrival_timestamp": 1564618713751, "event_version": "3.1", "application": { "app_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "sdk": {} }, "client": { "client_id": "49c1413e-a69c-46dc-b1c4-6470eexample" }, "device": { "platform": {} }, "session": {}, "attributes": { "feedback": "https://aws.amazon.com/pinpoint/" }, "awsAccountId": "123456789012", "facets": { "email_channel": { "mail_event": { "mail": { "message_id": "0200000073rnbmd1-mbvdg3uo-q8ia-m3ku-ibd3-ms77kexample-000000", "message_send_timestamp": 1564618621380, "from_address": "sender@example.com", "destination": ["recipient@example.com"], "headers_truncated": false, "headers": [{ "name": "From", "value": "sender@example.com" }, { "name": "From", "value": "recipient@example.com" }, { "name": "Subject", "value": "Amazon Pinpoint Test" }, { "name": "MIME-Version", "value": "1.0" }, { "name": "Content-Type", "value": "multipart/alternative; boundary=\"----=_Part_314159_271828\"" }, { "name": "Message-ID", "value": "null" }], "common_headers": { "from": "sender@example.com", "to": ["recipient@example.com"], "subject": "Amazon Pinpoint Test" } }, "click": { "ip_address": "72.21.198.67", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.1.2 Safari/605.1.15", "link": "https://aws.amazon.com/pinpoint/" } } } } }

Email Open

The JSON object for an email open event contains the data shown in the following example.

{ "event_type": "_email.open", "event_timestamp": 1564618621380, "arrival_timestamp": 1564618712316, "event_version": "3.1", "application": { "app_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "sdk": {} }, "client": { "client_id": "8dc1f651-b3ec-46fc-9b67-2a050example" }, "device": { "platform": {} }, "session": {}, "attributes": { "feedback": "opened" }, "awsAccountId": "123456789012", "facets": { "email_channel": { "mail_event": { "mail": { "message_id": "0200000073rnbmd1-mbvdg3uo-q8ia-m3ku-ibd3-ms77kexample-000000", "message_send_timestamp": 1564618621380, "from_address": "sender@example.com", "destination": ["recipient@example.com"], "headers_truncated": false, "headers": [{ "name": "From", "value": "sender@example.com" }, { "name": "From", "value": "recipient@example.com" }, { "name": "Subject", "value": "Amazon Pinpoint Test" }, { "name": "MIME-Version", "value": "1.0" }, { "name": "Content-Type", "value": "multipart/alternative; boundary=\"----=_Part_314159_271828\"" }, { "name": "Message-ID", "value": "null" }], "common_headers": { "from": "sender@example.com", "to": ["recipient@example.com"], "subject": "Amazon Pinpoint Test" } }, "open": { "ip_address": "72.21.198.67", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/605.1.15 (KHTML, like Gecko)" } } } } }

Email Event Attributes

This section defines the attributes that are included in the event stream data that Amazon Pinpoint generates when you send email.

Attribute Description
event_type

The type of event. Possible values:

  • _email.send – Amazon Pinpoint accepted the message and attempted to deliver it to the recipient.

  • _email.delivered – The message was delivered to the recipient.

  • _email.rejected – Amazon Pinpoint determined that the message contained malware and didn't attempt to send it.

  • _email.hardbounce – A permanent issue prevented Amazon Pinpoint from delivering the message. Amazon Pinpoint won't attempt to deliver the message again.

  • _email.softbounce – A temporary issue prevented Amazon Pinpoint from delivering the message. Amazon Pinpoint will attempt to deliver the message again for a certain period of time. After this time, if the message still can't be delivered, it's counted as a hard bounce.

  • _email.complaint – The recipient received the message, and then identified the message to their email provider as spam (for example, by using the "Report Spam" feature of their email client).

  • _email.open – The recipient received the message and opened it.

  • _email.click – The recipient received the message and clicked a link in it.

  • _email.unsubscribe – The recipient received the message and clicked an unsubscribe link in it.

event_timestamp

The time when the event was reported, shown as Unix time in milliseconds.

arrival_timestamp

The time when the event was received by Amazon Pinpoint, shown as Unix time in milliseconds.

event_version

The version of the event JSON schema.

Tip

Check this version in your event-processing application so that you know when to update the application in response to a schema update.

application

Information about the Amazon Pinpoint project that's associated with the event. See the Application table for more information.

client

The app client installed on the device that reports the event. See the Client table for more information.

device

The device that reports the event. See the Device table for more information.

In events that are generated when you send a transactional message, this object is empty.

session For email events, this object is empty.
attributes

Attributes that are associated with the event. For events that are reported by one of your apps, this object can include custom attributes that are defined by the app. For events that are created when you send a campaign, this object contains attributes that are associated with the campaign. For events that are generated when you send transactional messages, this object contains information that's related to the message itself.

See the Attributes table for more information.

client_context For email events, this object contains an object called custom, which contains an attribute called legacy_identifier. The value of legacy_identifier is equal to the ID of the project that the email was sent from.
facets

Additional information about the message, such as the email headers. See the Facets table for more information.

awsAccountId

The ID of the AWS account that was used to send the message.

Application

Includes information about the Amazon Pinpoint project that the event is associated with.

Attribute Description
app_id

The unique ID of the Amazon Pinpoint project that reported the event.

sdk

The SDK that was used to report the event. If you send a transactional email message calling the Amazon Pinpoint API directly, or by using the Amazon Pinpoint console, this object is empty.

Attributes

Includes information about the campaign that produced the event.

Attribute Description
feedback

For _email.click events, the value of this attribute is the URL of the link that the recipient clicked to generate the event. For other events, the value represents the event type (such as received, opened, or clicked).

treatment_id

If the message was sent using an A/B test campaign, this value represents the treatment number of the message. For standard campaigns and transactional email messages, this value is 0.

campaign_activity_id The unique ID that Amazon Pinpoint generates when the event occurs.
campaign_id

The unique ID of the campaign that the message was sent from.

Client

Includes information about the endpoint that was targeted by the campaign.

Attribute Description
client_id The email address of the endpoint that reported the event.

Facets

Attribute Description
email_channel

Contains an object called mail_event, which contains two objects: mail, and an object that corresponds with the event type.

Mail

Includes information about the content of the email, as well as metadata related to the message itself.

Attribute Description
message_id

The unique ID of the email message. Amazon Pinpoint automatically generates this ID when it accepts the email.

message_send_timestamp

The date and time when the message was sent, shown in the format specified in RFC 822.

from_address

The email address that the message was sent from.

destination

An array that contains the email addresses that the message was sent to.

headers_truncated

A boolean that indicates whether the email headers were truncated.

headers

An object that contains several name-value pairs that correspond to the headers in the email. This object typically contains information about the following headers:

  • From – The senders's email address.

  • To – The recipient's email address.

  • Subject – The subject line of the email.

  • MIME-Version – Indicates that the message is MIME-formatted. If this header is present, the value is always 1.0.

  • Content-Type – The MIME media type of the message content.

common_headers

Contains information about several common email headers, such as the date when the email was sent, and the to, from, and subject lines.