Email events

Updated

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 Customer.io, we recommend that you follow the specifications on this page. See Email Events if you want to download the specification or try out email events.

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

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.

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"
  }
}

    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"
  }
}
      • 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"
  }
}

      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"
  }
}
        • 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