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:

Property Type Description context.traits Object An associative array about the email’s intended recipient. context.traits.email String The intended recipient’s email address. Example

analytics.track('Email Bounced', {
    'email_id': '18vzF7u3z',
    'email_subject': 'First shirt on us!',
    'campaign_id': '123',
    'campaign_name': 'New Customer Discount'
})

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

analytics.track('Email Delivered', {
    'email_id': '18vzF7u3z',
    'email_subject': 'First shirt on us!',
    'campaign_id': '123',
    'campaign_name': 'New Customer Discount'
})

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_idStringThe intended recipient’s email address.
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

analytics.track('Email Link Clicked', {
    'email_id': '18vzF7u3z',
    'email_subject': 'First shirt on us!',
    'campaign_id': '123',
    'campaign_name': 'New Customer Discount',
    'link_id': '101',
    'link_url': 'https://www.buymyshirts.com?promo=NEWCUSTOMER'
})

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

analytics.track('Email Marked as Spam', {
    'email_id': '18vzF7u3z',
    'email_subject': 'First shirt on us!',
    'campaign_id': '123',
    'campaign_name': 'New Customer Discount'
})

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.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

analytics.track('Email Opened', {
    'email_id': '18vzF7u3z',
    'email_subject': 'First shirt on us!',
    'campaign_id': '123',
    'campaign_name': 'New Customer Discount'
})

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.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

analytics.track('Unsubscribed', {
    'email_id': '18vzF7u3z',
    'email_subject': 'First shirt on us!',
    'campaign_id': '123',
    'campaign_name': 'New Customer Discount',
    'list_id': '1425',
    'list_name': 'New customers'
})


Not using Plainflow yet? Get your free account here. 👈