# Email events

## How it works[](#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](/integrations/api/cdp/email/) 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[](#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

## Email Bounced[](#email-bounced)

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

```json
{
  "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"
  }
}
```

*   context object
    
    Contextual information about the event. These fields are in addition to any [captured automatically by your source library](/integrations/data-in/source-spec/common-fields/).
    
    *   traits object
        
        Traits you want to capture as context for the event.
        
        *   email string
            
            The recipient’s email address.
            

## Email Delivered[](#email-delivered)

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

```json
{
  "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"
  }
}
```

*   context object
    
    Contextual information about the event. These fields are in addition to any [captured automatically by your source library](/integrations/data-in/source-spec/common-fields/).
    
    *   traits object
        
        Traits you want to capture as context for the event.
        
        *   email string
            
            The recipient’s email address.
            

## Email Opened[](#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.

```json
{
  "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[](#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.

```json
{
  "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"
  }
}
```

*   properties object
    
    *   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[](#email-marked-as-spam)

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

```json
{
  "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[](#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.

```json
{
  "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"
  }
}
```

*   properties object
    
    *   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.