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 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 Customer.io) 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

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 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 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 Link Clicked

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