MyDataHelps utilizes an email provider to send email notifications and track email events. Within the Analytics Events export, there are several files related to email events: bounce, click, delivery, open, and send. These differ from the other analytics events files in that these reflect the raw email events from the email provider.
Table of Contents
Common Data Fields
All of the Email Events exports contain the following common data fields.
| Field | Description |
|---|---|
ParticipantID |
The stable, automatically generated, internal system identifier for this participant. |
ParticipantIdentifier |
The identifier of the participant the notification or survey was delivered to. Can be used to cross reference with Participants. |
Timestamp |
The timestamp of the email event. |
EmailEventKey |
The unique identifier of a single email event. |
MailDestination |
The email address(es) that the email was sent to. |
MailTimestamp |
The timestamp of when the email was sent. |
MailSource |
The email address that the email was sent from. |
MailMessageID |
The unique ID assigned to the email message, which correlates all events associated with the single email send (i.e., bounces, clicks, deliveries, opens). |
NotificationIdentifier |
The organization-specific identifier of the notification that was sent. This is the identifier shown in the Notifications library. |
FromDomain |
The domain this email was sent from. This can be helpful with debugging emails going to spam. |
LocaleCode |
Email language, if not the default. |
The sections below outline the additional data fields contained within each of the file types.
Email Bounce
A bounce describes an event where an email is rejected by the recipient’s mail server. In addition to the common data fields above, this file will also contain the following fields.
| Field | Description |
|---|---|
BounceType |
The type of bounce that occurred (e.g., transient or permanent). If transient, and there is not a successful delivery of the associated email message, you may need to try resending the email. If permanent, verify that the recipient email address is valid. |
BounceSubType |
The subtype of the bounce that occurred. Click here for definitions of each type. |
Email Click
A click describes an event where a link within the email is clicked by the email recipient. In addition to the common data fields above, this file will also contain the following fields.
When a link is inserted into an email notification, the email provider will modify the link so that participants are first sent to the email provider server, then immediately redirected to the destination address. This is how we are able to obtain click tracking metrics.
If you wish to disable click tracking for a link, add the ses:no-track attribute to the link (within the html code view for the notification).
| Field | Description |
|---|---|
ClickTimestamp |
The timestamp of when the link was clicked. |
ClickUserAgent |
The user agent of the client that the recipient used to click a link in the email. |
ClickIPAddress |
The IP address of the server on which the email was clicked. |
ClickLink |
The URL of the link that was clicked. |
ClickLinkTags |
The tag(s) added to the link that was clicked, if applicable. These tags allow you to further analyze the specific link clicked. If interested in adding tags, they should be added as key-value pairs using the ses:tags attribute. Click here for more details on how to incorporate tags. |
Click tracking is dependent on the configuration of the recipient’s email server, and may be impacted by the recipient’s privacy, sharing, or cache settings.
Email Complaint
An email complaint describes an event where a recipient has submitted a complaint about the email they received. A list of complaint types can be found here.
| Field | Description |
|---|---|
ComplaintType |
The type of complaint submitted. |
ComplaintUserAgent |
The user agent of the client that submitted the complaint. |
Email Delivery
A delivery describes an event where the email has been successfully delivered to the recipient’s mail server. In addition to the common data fields above, this file will also contain the following fields.
| Field | Description |
|---|---|
DeliveryRecipient |
The email address that the email was sent to. |
DeliveryTimestamp |
The timestamp of when the email was delivered. |
Delivery indicates that the email was delivered to the recipient’s mail server, but not necessarily the participant’s inbox (e.g., a message could also be delivered to a participant’s spam folder).
Email Open
An open describes an event where the email has been opened by the recipient. In addition to the common data fields above, this file will also contain the following fields.
Open tracking works by placing a 1x1 transparent pixel (image) at the bottom of the email, where each pixel has a unique URL. There may be instances where you see a “Click” event for a participant, but not an associated “Open” event. For example, this can occur if the participant has their email client set up to not load images, or if the participant has "do not track" browser settings enabled.
| Field | Description |
|---|---|
OpenTimestamp |
The timestamp of when the email was opened. |
OpenUserAgent |
The user agent of the device or email client that the recipient used to open the email. |
OpenIPAddress |
The recipient's IP address. |
Open tracking is dependent on the configuration of the recipient’s email server, and may be impacted by the recipient’s privacy, sharing, or cache settings.
Email Send
A send describes an event where the email has been sent from the server (and will attempt to be delivered to the recipient). The Email Send file contains only the common data fields listed in the first section.
Sample CSV Export
ParticipantIdentifier,Timestamp,FromDomain,MailDestination,MailMessageID,MailSource,MailTimestamp,NotificationIdentifier,ParticipantID
641d313d-7144-4534-ac28-719e0904253e,2022-05-03T12:45:42Z,mydatahelps.org,test123@careevolution.com,0100018089f3ed3f-9977584c-951d-4f6f-acb2-01aaf7e835b4-000000,MyDataHelps <noreply@mydatahelps.org>,2022-05-03T12:45:06Z,Invitation-Email,61fd00e8-eea9-ec11-aaab-f47bb6835a10
Sample JSON Export
{
"ParticipantID":"61fd00e8-eea9-ec11-aaab-f47bb6835a10",
"ParticipantIdentifier":"641d313d-7144-4534-ac28-719e0904253e",
"Timestamp":"2022-05-03T12:45:42Z",
"Properties":
{
"MailDestination": "test123@careevolution.com",
"MailTimestamp": "2022-05-03T12:45:06Z",
"MailSource": "MyDataHelps <noreply@mydatahelps.org>",
"MailMessageID": "0100018089f3ed3f-9977584c-951d-4f6f-acb2-01aaf7e835b4-000000",
"NotificationIdentifier": "Invitation-Email",
"FromDomain": "mydatahelps.org"
}
}