Spec: Email Events

This guide explains what data can be sent to Segment from Email tools. The semantic events detailed below represent the ideal for Email events; not every Email tool supports all of these events or all of their properties.

Overview

Every Email tool is built around the idea of delivering emails to recipients. A user sends one or many emails through an email tool, and the email is either delivered to a recipient or bounces if the email is undeliverable.

When an email is delivered, a recipient can take one or many actions on it: They might open the email, click on a link in the email’s body, mark the email as spam, or unsubscribe

Events

The email category has the following semantic events:

Email Bounced

This event should be sent when an email tool receives notice from an email server that an email is undeliverable.

Properties

This event supports the following semantic properties:

PropertyTypeDescription
email_idStringAn ID used to identify the email.
email_subjectStringThe email’s subject line.
campaign_idStringAn id used to identify a campaign
campaign_nameStringA name used to identify a campaign

Context

This event supports the following semantic context properties:

PropertyTypeDescription
context.traitsObjectAn associative array about the email’s intended recipient.
context.traits.emailStringThe intended recipient’s email address.
Example

Email Delivered

This event should be fired when the receiving mail server confirms receipt of an email.

Properties

This event supports the following semantic properties:

PropertyTypeDescription
email_idStringAn ID used to identify the email.
email_subjectStringThe email’s subject line.
campaign_idStringAn id used to identify a campaign
campaign_nameStringA name used to identify a campaign

Context

This event supports the following semantic context properties:

PropertyTypeDescription
context.traitsObjectAn associative array about the email’s intended recipient.
context.traits.emailStringThe intended recipient’s email address.
Example

This event should be fired when the recipient clicks on a link in the email’s body.

Properties

This event supports the following semantic properties:

PropertyTypeDescription
email_idStringAn ID used to identify the email.
email_subjectStringThe email’s subject line.
campaign_idStringAn id used to identify a campaign
campaign_nameStringA name used to identify a campaign
link_idStringAn id used to identify a link
link_urlStringThe URL the link points to.

Context

This event supports the following semantic context properties:

PropertyTypeDescription
context.ipObjectThe opening computer’s public IP address.
context.traitsObjectAn associative array describing the email’s intended recipient.
context.traits.emailStringThe intended recipient’s email address.
context.user_agentStringThe opening browser’s user agent.

Example

Email Marked as Spam

This event should be fired when a recipient marks an email as spam.

Properties

This event supports the following semantic properties:

PropertyTypeDescription
email_idStringAn ID used to identify the email.
email_subjectStringThe email’s subject line.
campaign_idStringAn id used to identify a campaign
campaign_nameStringA name used to identify a campaign

Context

This event supports the following semantic context properties:

PropertyTypeDescription
context.ipObjectThe opening computer’s public IP address.
context.traitsObjectAn associative array describing the email’s intended recipient.
context.traits.emailStringThe intended recipient’s email address.
context.user_agentStringThe opening browser’s user agent.

Example

Email Opened

This event should be fired when the recipient opens the email.

Properties

This event supports the following semantic properties:

PropertyTypeDescription
email_idStringAn ID used to identify the email.
email_subjectStringThe email’s subject line.
campaign_idStringAn id used to identify a campaign
campaign_nameStringA name used to identify a campaign

Context

This event supports the following semantic context properties:

PropertyTypeDescription
context.ipStringThe opening computer’s public IP address.
context.traitsObjectAn associative array describing the email’s intended recipient.
context.traits.emailStringThe intended recipient’s email address.
context.user_agentStringThe opening browser’s user agent.

Example

Unsubscribed

This event should be fired when the recipient unsubscribes from the email. The unsubscription can either happen for a particular list, or globally from all marketing emails, depending on the tool. Typically you cannot unsubscribe from a transactional email such as a password reset.

Properties

This event supports the following semantic properties:

PropertyTypeDescription
email_idStringAn ID used to identify the email.
email_subjectStringThe email’s subject line.
campaign_idStringAn id used to identify a campaign
campaign_nameStringA name used to identify a campaign
list_idStringAn optional id used to identify a list
list_nameStringAn optional name used to identify a list

Context

This event supports the following semantic context properties:

PropertyTypeDescription
context.ipStringThe opening computer’s public IP address.
context.traitsObjectAn associative array describing the email’s intended recipient.
context.traits.emailStringThe intended recipient’s email address.
context.user_agentStringThe opening browser’s user agent.

Example


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!