Email events

How it works

Email service providers and other platforms produce events that help you track the lifecycles of your emails—whether emails are delivered, opened, etc. If you send email events into Data Pipelines, we recommend that you follow the specifications on this page.

We use this specification to support default actions—any we have now and ones we might add in the future. If you send email lifecycle events that conform to this specification, you’ll be ready to trigger downstream actions in destinations that rely on these events.

Events in an email lifecycle

Emails (outside of Journeys) produce the following events. Not every message will produce the same events, so it may be helpful to understand the possible lifecycle of an email.

  • Email Bounced
  • Email Delivered
  • Email Link Clicked
  • Email Marked as Spam
  • Email Opened
  • Unsubscribed
flowchart LR a{Was email delivered?}-.->|no|b(Email Bounced) a-->|yes|c(Email Delivered) c-->x{DidDoes the user
open the email?}-->|yes|d(Email Opened) d-->e{Did the
user respond?}-->|yes|z subgraph z[Responses: not mutually exclusive] direction LR f(Email Link Clicked) g(Email Marked as Spam) h(Unsubscribed) end

Email Bounced

This event indicates that your email server/service provider couldn’t deliver a message to the recipient.

{
  "user_id": "020ba8yf4r",
  "action": "track",
  "event": "Email Bounced",
  "context": {
    "traits": {
      "email": "cool.person@example.com"
    }
  },
  "properties": {
    "email_id": "18vzF7u3z",
    "email_subject": "20% off: A token of our appreciation!",
    "campaign_id": "abc123",
    "campaign_name": "New Customer Discount"
  }
}
      • email string
        The recipient’s email address.
    • campaign_id string
      The ID of the campaign the email belongs to.
    • campaign_name string
      The campaign’s friendly name.
    • email_id string
      Required The ID of the email/delivery.
    • email_subject string
      The email’s subject line.

Email Delivered

This event indicates that your email server/service provider delivered a message to the recipient.

{
  "user_id": "020ba8yf4r",
  "action": "track",
  "event": "Email Delivered",
  "context": {
    "traits": {
      "email": "cool.person@example.com"
    }
  },
  "properties": {
    "email_id": "18vzF7u3z",
    "email_subject": "20% off: A token of our appreciation!",
    "campaign_id": "abc123",
    "campaign_name": "New Customer Discount"
  }
}
      • email string
        The recipient’s email address.
    • campaign_id string
      The ID of the campaign the email belongs to.
    • campaign_name string
      The campaign’s friendly name.
    • email_id string
      Required The ID of the email/delivery.
    • email_subject string
      The email’s subject line.

Email Opened

This event indicates that the user opened the email. Email opens may rely on tracking pixels or other techniques that aren’t 100% reliable. Even if you send this event yourself, you may not be able to capture every open. You’re likely to get concrete metrics from the following three events.

{
  "user_id": "020ba8yf4r",
  "action": "track",
  "event": "Email Opened",
  "context": {
    "ip": "67.207.109.102",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.118 Safari/537.36",
    "traits": {
      "email": "cool.person@example.com"
    }
  },
  "properties": {
    "email_id": "18vzF7u3z",
    "email_subject": "20% off: A token of our appreciation!",
    "campaign_id": "abc123",
    "campaign_name": "New Customer Discount"
  }
}
      • email string
        The recipient’s email address.
      • ip string
        The IP address of the user who interacted with the email.
      • user_agent string
        The user agent of the user who interacted with the email.
    • campaign_id string
      The ID of the campaign the email belongs to.
    • campaign_name string
      The campaign’s friendly name.
    • email_id string
      Required The ID of the email/delivery.
    • email_subject string
      The email’s subject line.

Send this event when someone clicks a link in your message. In most cases, you’ll need to add some kind of query parameter or other link-tracking mechanism to track clicks this way.

{
  "user_id": "020ba8yf4r",
  "action": "track",
  "event": "Email Link Clicked",
  "context": {
    "ip": "67.207.109.102",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.118 Safari/537.36",
    "traits": {
      "email": "cool.person@example.com"
    }
  },
  "properties": {
    "email_id": "18vzF7u3z",
    "email_subject": "20% off: A token of our appreciation!",
    "campaign_id": "abc123",
    "campaign_name": "New Customer Discount"
  }
}
      • email string
        The recipient’s email address.
      • ip string
        The IP address of the user who interacted with the email.
      • user_agent string
        The user agent of the user who interacted with the email.
    • campaign_id string
      The ID of the campaign the email belongs to.
    • campaign_name string
      The campaign’s friendly name.
    • email_id string
      Required The ID of the email/delivery.
    • email_subject string
      The email’s subject line.
    • link_id string
      The ID of the link that the user clicked.
    • link_url string
      The URL of the link that the user clicked.

Email Marked as Spam

Send this event when a user marks your message as spam.

{
  "user_id": "020ba8yf4r",
  "action": "track",
  "event": "Email Marked as Spam",
  "context": {
    "ip": "67.207.109.102",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.118 Safari/537.36",
    "traits": {
      "email": "cool.person@example.com"
    }
  },
  "properties": {
    "email_id": "18vzF7u3z",
    "email_subject": "20% off: A token of our appreciation!",
    "campaign_id": "abc123",
    "campaign_name": "New Customer Discount"
  }
}
      • email string
        The recipient’s email address.
      • ip string
        The IP address of the user who interacted with the email.
      • user_agent string
        The user agent of the user who interacted with the email.
    • campaign_id string
      The ID of the campaign the email belongs to.
    • campaign_name string
      The campaign’s friendly name.
    • email_id string
      Required The ID of the email/delivery.
    • email_subject string
      The email’s subject line.

Unsubscribed

Send this event when a user unsubscribes from your emails. You can also send a list values to indicate that a user unsubscribed from a specific mailing list.

{
  "user_id": "020ba8yf4r",
  "action": "track",
  "event": "Unsubscribed",
  "context": {
    "ip": "67.207.109.102",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.118 Safari/537.36",
    "traits": {
      "email": "cool.person@example.com"
    }
  },
  "properties": {
    "email_id": "18vzF7u3z",
    "email_subject": "20% off: A token of our appreciation!",
    "campaign_id": "abc123",
    "campaign_name": "New Customer Discount"
  }
}
      • email string
        The recipient’s email address.
      • ip string
        The IP address of the user who interacted with the email.
      • user_agent string
        The user agent of the user who interacted with the email.
    • list_id string
      The ID of the mailing list the user unsubscribed from.
    • list_name string
      The name of the mailing list the user unsubscribed from.
Copied to clipboard!
  Contents
Is this page helpful?