Pipelines API - Email Events

Email Semantic Events

This document describes semantic events for email interactions in the Customer.io Pipelines API.

Semantic events are special payloads for our track endpoint based on the event name. When you send an email event with a specific name (like Email Delivered or Email Opened), Customer.io and downstream integrations recognize it and handle it appropriately.

With semantic events, you can set up your events and they'll work with any of our destinations that support email events.

Server addresses: US and EU

Customer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.

Region	Server Address
US	https://cdp.customer.io
EU	https://cdp-eu.customer.io

If you're in our EU region, you'll need to specify the EU URL when you initialize our server-side libraries.

Authentication

The Data Pipelines API uses basic authentication with your API key as the username and a blank password.

Server

The base URL for all Data Pipelines calls in our United States (US) region.

Client Libraries

Shell Curl

Track Email Events

Send email interaction events when people interact with your emails.

These are semantic events that follow a standard structure for email tracking across different email service providers and analytics platforms.

Available email events:

Email Bounced - Email failed to deliver
Email Delivered - Email successfully delivered
Email Link Clicked - Recipient clicked a link in the email
Email Marked as Spam - Recipient marked email as spam
Email Opened - Recipient opened the email
Email Unsubscribed - Recipient unsubscribed from emails

Headers

X-Strict-Mode
enum
const:
1

When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200.
values
- 1

Body

required

application/json

userId
Type: string
required

The unique identifier for the user.

type
enum
const:
track
required

The event type. Must be track for event calls.

values
track
event
enum
const:
Email Bounced
required

The event name. Must be Email Bounced for this semantic event.

values
Email Bounced
properties
Type: object
required

Event properties that describe the email bounce.

timestamp
Type: stringFormat: date-time

The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.

context
Type: object

Contextual information about the event. These fields are in addition to any captured automatically by your source library.

integrations
Type: object · Integrations

Control which integrations receive this event. By default, all enabled integrations receive events.

Responses

application/json
application/json
401

Unauthorized request. Make sure that you provided the right credentials.

post/track

curl https://cdp.customer.io/v1/track \
  --request POST \
  --header 'X-Strict-Mode: 1' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "userId": "user_12345",
  "type": "track",
  "event": "Email Bounced",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "properties": {
    "email_id": "msg_abc123",
    "email_subject": "Your weekly newsletter",
    "campaign_id": "camp_456",
    "campaign_name": "Weekly Newsletter Campaign",
    "additionalProperty": null
  },
  "context": {
    "traits": {
      "email": "user@example.com"
    },
    "additionalProperty": "anything"
  },
  "integrations": {
    "All": false,
    "Mixpanel": true,
    "Segment": true
  }
}'

Show Schema

{}

A successful request returns an empty object response.

Pipelines API - Email Events

Email Semantic Events

Server addresses: US and EU

Authentication

Authentication

Track Email Events

Models