REST API Documentation

Getting Started

Welcome to the Customer.io API.

You can send behavioral events to Customer.io from many different languages.

If you’re using a language not listed here, we’d be happy to help you integrate with our API or create a library that we can add to this area.

Behavioral Tracking vs. API

There are two primary API hosts available for you to integrate with:

Behavioral Tracking

https://track.customer.io/api/v1/

Our Behavioral Tracking API is used to identify and track customer data with Customer.io.

API

https://api.customer.io/v1/api/

Our API allows you to read data from your Customer.io account for use in custom workflows in your backend system or for reporting purposes.

JS Snippet or Backend language?

The Javascript snippet tracks basic behavior for you just by copy/pasting it onto your site. In many cases, using the Javascript snippet will be easier to integrate with your app, but there are several reasons why sending events from your backend is useful:

You’re not planning on triggering emails based on how customers interact with your website (e.g. users who haven’t visited the site in X days)
You’re using the Javascript snippet, but have a few events you’d like to send from your backend system. They will work well together!
You’d rather not have another Javascript snippet slowing down your frontend. Our snippet is asynchronous (doesn’t affect initial page load) and very small, but we understand.

In the end, the decision on whether or not to send events from your backend or the Javascript snippet should be based on what works best for you. You’ll be able to integrate fully with Customer.io with either approach.

Supported Languages

Authentication

curl -i https://track.customer.io/auth \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

var _cio = _cio || [];

(function() {
  var a,b,c;a=function(f){return function(){_cio.push([f].
  concat(Array.prototype.slice.call(arguments,0)))}};b=["load","identify",
  "sidentify","track","page"];for(c=0;c<b.length;c++){_cio[b[c]]=a(b[c])};
  var t = document.createElement('script'),
      s = document.getElementsByTagName('script')[0];
  t.async = true;
  t.id    = 'cio-tracker';
  t.setAttribute('data-site-id', 'YOUR SITE ID HERE');
  t.src = 'https://assets.customer.io/assets/track.js';
  s.parentNode.insertBefore(t, s);
})();

var cio = new CIO("YOUR SITE ID", "YOUR API SECRET KEY");

$customerio = Customerio::Client.new("YOUR SITE ID", "YOUR API SECRET KEY")

from customerio import CustomerIO
cio = CustomerIO("YOUR SITE ID", "YOUR API SECRET KEY")

import (
  // ...
  "github.com/customerio/go-customerio"
)

cio := customerio.NewCustomerIO("YOUR SITE ID", "YOUR API SECRET KEY")

All requests to the Customer.io API must be authenticated via HTTP Basic Auth.

To authenticate, you provide your site id as the username, and your secret API key as the password. You can find these values in the integration area of your Customer.io account.

Nothing will work unless you include this API key

Limits

Identify Limits

Data Type	Limit	Description
Customer ID	150 bytes	Max length of customer ID value for Identify call
Customer Attribute Name	150 bytes	Max length of attribute names for Identify call
Customer Attribute Value	1000 bytes	Max length of attribute values for Identify call
Unique Identify attributes	30	Max number of attributes that can be included per Identify call

Event Limits

Data Type	Limit	Description
Event Name	100 bytes	Max length of event name for Track call
Event Data	10000 bytes	Max length of event data for Track call

API Triggered Broadcast Limits

Data Type	Limit	Description
Trigger Data	10000 bytes	Max length of Liquid merge data for Trigger call

Rate Limits

When sending data to Customer.io, Behavioral Tracking API calls should be limited to 30 requests per second. This limit applies to both active data integrations, as well as historical backfill scripts.

If this rate limit is exceeded we will reach out to help you correct your integration. However we reserve the right to block your API calls if your integration is exceeding this limit in a way that degrades performance for our customers.

Errors

Customer.io uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a search failed, etc.), and codes in the 5xx range indicate an error with Customer.io’s servers.

Code	Name	Description
200	OK	Everything worked as expected
400	Bad Request	Often missing a required parameter
401	Unauthorized	No valid API key provided
404	Not Found	The requested item does not exist
500, 502, 503, 504	Server errors	Something went wrong on our end

Behavioral Tracking

Introduction

API Host: https://track.customer.io/api/v1

Below we document the Behavioral Tracking API endpoints and corresponding examples using some of our official libraries.

The Behavioral Tracking API meta info can be accessed at https://track.customer.io/ and displays a summary of every endpoint when navigated to directly.

We’ve documented the most commonly used endpoints in detail below to assist in getting started with your integration. The API documentation is focused around the REST HTTP API, but we will provide equivelent language implementation examples from our official libraries where possible.

/customers/:id

API Host: https://track.customer.io/api/v1

Create or update a customer

Parameters

id: The unique identifier for the customer
email: The email address of the user
created_at: The UNIX timestamp from when the user was created in your system
attributes: Custom attributes to define the customer

curl -i https://track.customer.io/api/v1/customers/:id \
  -X PUT \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -d email=customer@example.com \
  -d created_at=1361205308 \
  -d first_name=Bob \
  -d plan=basic

curl -i https://track.customer.io/api/v1/customers/:id \
  -X PUT \
  -H "Content-Type: application/json" \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -d '{"email":"customer@example.com","created_at":1361205308,"first_name":"Bob","plan":"basic"}'

_cio.identify({
  id: 5,
  email: 'customer@example.com',
  created_at: 1361205308,
  first_name: "Bob",
  plan: "basic"
});

cio.identify(5, {
  email: 'customer@example.com',
  created_at: 1361205308,
  first_name: "Bob",
  plan: "basic"
});

$customerio.identify(
  id: 5,
  email: "customer@example.com",
  created_at: 1361205308,
  first_name: "Bob",
  plan: "basic"
)

cio.identify(id=5, email='customer@example.com', created_at=1361205308, first_name='Bob', plan='basic')

cio.Identify("5", map[string]interface{}{
  "email": "customer@example.com",
  "created_at": time.Now().Unix(),
  "first_name": "Bob",
  "plan": "basic",
})

Creating or updating customers via the Behavioral Tracking API accomplishes the same goal as the identify method in the Javascript snippet. It allows you to pass attributes of your customers to us which you can then use to personalized your triggered emails or affect the logic of who receives them.

There is a limit of 30 unique attributes set per identify call

Updating or removing attributes

You can also update a customer’s attributes after creating them, using the same PUT API call. Don’t worry about sending only the attributes which have changed, our API takes care of that for you.

To remove an attribute on an existing customer, set its value to an empty string.

HTTP 200OK

A 200 response code signifies the customer was created or updated. All other response codes mean something went wrong.

/customers/:id

API Host: https://track.customer.io/api/v1

Delete a customer

Parameters

id: The unique identifier for the customer

curl -i https://track.customer.io/api/v1/customers/:id \
  -X DELETE \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

cio.destroy(5);

$customerio.delete(5)

cio.delete(customer_id=5)

cio.Delete("5")

Deleting a customer will remove them, and all their information from Customer.io.

Note: if you’re still sending data to Customer.io via other means (such as the Javascript snippet), the customer could be recreated.

This action is not available with the Javascript snippet alone

HTTP 200OK

When we send back a 200 response, the record will eventually be deleted if it exists. All other response codes mean something went wrong.

/customers/:id/devices

API Host: https://track.customer.io/api/v1

Create or update a customer device

Parameters

id: The unique identifier for the customer
device_id: The unique token for the user device
platform: The platform for the user device. Allowed values are 'ios' and 'android'.
last_used: UNIX timestamp representing the last used time for the device. If this is not included we default to the time of the device identify.
attributes: Custom attributes to send with the device identify

curl -i https://track.customer.io/api/v1/customers/:id/devices \
  -X PUT \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -d device["id"]=my_ios_device_id \
  -d device["platform"]=ios \
  -d device["last_used"]=1514764800

curl -i https://track.customer.io/api/v1/customers/:id/devices \
  -X PUT \
  -H "Content-Type: application/json" \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -d '{"device":{"id": "my_android_device_id", "platform": "android", "last_used": 1514764800}}'

// Add iOS device
cio.addDevice(1, "my_ios_device_id", "ios");
// Add android device
cio.addDevice(1, "my_android_device_id", "android");

// Add device with custom "last_used" value
cio.addDevice(1, "my_ios_device_id", "ios", {"last_used": 1514764800});

# Add iOS device
$customerio.add_device(5, "my_ios_device_id", "ios")
# Add Android device
$customerio.add_device(5, "my_android_device_id", "android")

# Add device with custom "last_used" value
$customerio.add_device(5, "my_ios_device_id", "ios", {:last_used=>1514764800})

# Add iOS device
cio.add_device(customer_id=1, device_id='my_ios_device_id', platform='ios')
# Add Android device
cio.add_device(customer_id=1, device_id='my_android_device_id', platform='android')

# Add device with custom "last_used" value
cio.add_device(customer_id=1, device_id='my_ios_device_id', platform='ios', last_used=1514764800)

// Add iOS device
cio.AddDevice("5", "my_ios_device_id", "ios", nil)
// Add Android device
cio.AddDevice("5", "my_android_device_id", "android", nil)

// Add device with custom "last_used" value
cio.AddDevice("5", "my_ios_device_id", "ios", map[string]interface{}{
  "last_used": 1514764800,
})

To identify mobile devices for use in Push messaging you need to form a PUT call to the devices endpoint for a given customer.

HTTP 200OK

A 200 response code signifies the device was created or updated. All other response codes mean something went wrong.

/customers/:id/devices

API Host: https://track.customer.io/api/v1

Delete a customer device

Parameters

id: The unique identifier for the customer
device_id: The unique token for the user device

curl -i https://track.customer.io/api/v1/customers/:id/devices/:device_id \
  -X DELETE \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

cio.deleteDevice(1, "my_device_id");

$customerio.delete_device(5, "my_device_id")

cio.delete_device(customer_id=1, device_id='my_device_id')

cio.DeleteDevice("5", "my_device_id")

Deleting a mobile device will remove the device from a customer’s profile in Customer.io.

Note: if you’re still sending data about the device to Customer.io via your integration the device will be recreated.

HTTP 200OK

When we send back a 200 response, the device will eventually be deleted if it exists. All other response codes mean something went wrong.

/customers/:id/suppress

API Host: https://track.customer.io/api/v1

Suppress a customer

Parameters

id: The unique identifier for the customer

curl -i https://track.customer.io/api/v1/customers/:id/suppress \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

To suppress a profile id in Customer.io from your server side code, you can POST to the suppress resource for a given profile ID. If we receive further API event/identify calls for the same profile ID, we’ll notice the id is suppressed and ignore the received API calls.

In addition to suppressing the profile ID we will also delete the user profile from Customer.io the same way we would when calling the identify endpoint with the DELETE method.

WARNING: This API call will NOT add anyone’s email address to the global suppression list for your account. Instead, it will delete the user’s profile AND cause us to ignore future API calls that attempt to create a new profile with the same profile id. If you need to suppress deliveries for a particular email address, please reach out to our support team or your email admin.

HTTP 200OK

A 200 response code signifies the customer will be deleted and future API calls suppressed. All other response codes mean something went wrong.

/customers/:id/unsuppress

API Host: https://track.customer.io/api/v1

Unsuppress a customer

Parameters

id: The unique identifier for the customer

curl -i https://track.customer.io/api/v1/customers/:id/unsuppress \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

If you need to resume tracking a previously suppressed profile ID in Customer.io you can POST to the unsuppress resource for a previously suppressed profile ID.

Following a call to unsuppress, identifies and events for a person will behave exactly as they would for a customer that we haven’t seen before. Identifying a person following an unsuppress will create an entirely new profile for them, with none of the history (messages, journeys, etc.) that might have existed for that ID prior to a suppress call.

WARNING: This API call will NOT remove anyone’s email address from the global suppression list for your account. Instead, it will reverse the effects of a SUPPRESS call (above) and cause us to allow future API calls that will create a new profile that uses a previously suppressed profile id. If you need to unsuppress deliveries for a particular email address, please reach out to our support team or your email admin.

HTTP 200OK

A 200 response code signifies the customer has been unsuppressed. All other response codes mean something went wrong.

/customers/:id/events

API Host: https://track.customer.io/api/v1

Track a customer event

Parameters

id: The unique identifier for the customer
name: The name of the event to track
type: Used to change event type. For Page View events set to "page".
data: Custom data to include with the event

curl -i https://track.customer.io/api/v1/customers/:id/events \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -d name=purchase \
  -d data[price]=23.45 \
  -d data[product]=socks

curl -i https://track.customer.io/api/v1/customers/:id/events \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"name":"purchase","data":{"price": "23.45", "product": "socks"}}'

// identify customer before tracking event
_cio.identify({id: 5});

_cio.track("purchase", { price: "23.45", product: "socks" });

// track regular event
cio.track(5, {
  name: 'purchase',
  data: {
    price: "23.45",
    product: "socks"
  }
});

// track page view event
cio.trackPageView(5, "http://google.com/search");

# track regular event
$customerio.track(5, "purchase", price: "23.45", product: "socks")

# track page view event
$customerio.track(5, "http://google.com/search", type: "page", referrer: "http://google.com")

# track regular event
cio.track(customer_id=5, name="purchase", price="23.45", product="socks")

# track page view event
cio.track(customer_id=5, name="http://google.com/search", type="page", referrer="http://google.com")

// track regular event
cio.Track("5", "purchase", map[string]interface{}{
  "price": "23.45",
  "product": "socks",
})

// track page view event
cio.Track("5", "http://google.com/search", map[string]interface{}{
  "type": "page",
  "referrer": "http://google.com"
})

To send an event to Customer.io outside of the browser, say from your server side code, you can POST to the events resource for a given customer.

Reserved Custom Data Parameters

There are a few important values which, if sent with the events that trigger campaigns, will override those campaign settings. These are:

Attachments
from_address
recipient
reply_to

When using the Javascript snippet to track events you must call the Behavioral Tracking API call after previously identifying the user or else the event will not associate to the user’s profile.

HTTP 200OK

A 200 response code signifies the event was successfully tracked. All other response codes mean something went wrong.

/events

API Host: https://track.customer.io/api/v1

Track an anonymous event

Parameters

name: The name of the event to track
data: Custom data to include with the event

curl -i https://track.customer.io/api/v1/events \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -d name=purchase \
  -d data[recipient]=customer@example.com \
  -d data[price]=23.45 \
  -d data[product]=socks

curl -i https://track.customer.io/api/v1/events \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"name":"purchase","data":{"recipient":"customer@example.com", "price": "23.45", "product": "socks"}}'

cio.trackAnonymous({
  name: 'purchase',
  data: {
    price: "23.45",
    product: "socks"
  }
});

$customerio.anonymous_track("purchase", recipient: "customer@example.com", price: "23.45", product: "socks")

Anonymous events can also be sent to Customer.io by way of a POST to the events resource directly without a customer ID.

Reserved Custom Data Parameters

There are a few important values which, if sent with the events that trigger campaigns, will override those campaign settings. These are:

recipient
from_address
reply_to

The recipient event attribute is required if the anonymous event is used to trigger an email campaign.

Use case

You can use anonymous events to send invitation emails to people not yet in your Customer.io database.

HTTP 200OK

A 200 response code signifies the event was successfully tracked. All other response codes mean something went wrong.

API

Introduction

API Host: https://api.customer.io/v1/api

Below we’ve documented our API which allows you to read data from your Customer.io account and trigger campaigns.

We’ve documented the most commonly used endpoints in detail below to assist in getting started with your integration. The API documentation is focused around the REST HTTP API, but we will provide equivelent language implementation examples from our official libraries where possible.

/campaigns/:id/triggers

API Host: https://api.customer.io/v1/api

Trigger broadcast campaign

Parameters

id: The unique identifier for the campaign
data: Custom Liquid merge data to include with the trigger
recipients: Additional recipient conditions to filter recipients

curl -i https://api.customer.io/v1/api/campaigns/:id/triggers \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"data":{"headline":"Roadrunner spotted in Albuquerque!","date":1511315635, "text": "We received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!"},"recipients":{"segment":{"id":7}}}'

cio.triggerBroadcast(5, {
  headline: "Roadrunner spotted in Albuquerque!",
  date: 1511315635,
  text: "We received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!"
}, { segment: { id: 7 }});

To send an API triggered broadcast in Customer.io from your server side code, you can POST to the trigger resource for a given campaign.

HTTP 200OK

A 200 response indicates the campaign has successfully been triggered and will begin sending. All other response codes mean something went wrong.

Important Usage Guidelines

API Host: https://beta-api.customer.io/v1/api

Here be dragons. Beta API features should be used with caution, and should be expected to change with little notice.

The API endpoints documented below are on the bleeding edge of what we’re building in our API. The API documentation is focused around calling via REST HTTP requests.

We encourage you to contact us at win@customer.io if you encounter issues, need clarifications or have requests for improvements. In addition, we’d love to hear about what you are building to help guide ongoing development.

This API is rate limited to 10 requests a second per workspace. Any requests beyond that are rejected with a http 429 status code.

/customers

API Host: https://beta-api.customer.io/v1/api

List customers

Parameters

email: Email address to search for matching customer profiles

curl -i https://beta-api.customer.io/v1/api/customers?email=test@example.com \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Calling the customers endpoint allows you to search Customer.io for a customer profile by email address.

{
  "results": [
    {
      "email": "test@example.com",
      "id": "14527"
    },
    {
      "email": "test@example.com",
      "id": "5323"
    }
  ]
}

/customers

API Host: https://beta-api.customer.io/v1/api

Search customers

Parameters

filter: Conditions to filter customers
start: The contination token to retrieve the next set of messages. Note that the continuation token may end with an '=' character, so be sure to query escape the token.
limit: The number of messages to retrieve

# Find the first 2 customers in segment 7 and segment 5.
curl -i https://api.customer.io/v1/api/customers?limit=2 \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"filter":{"and":[{"segment":{"id":7}},{"segment":{"id":5}}]}}'

Posting the customers endpoint allows you to search Customer.io for a customer profiles matching a set of filters. The filter language is defined at https://customer.io/docs/documentation/api-triggered-data-format.html#general-syntax

{
  "ids": [
    "0",
    "1"
  ],
  "next": "MDox"
}

/customers/:id/attributes

API Host: https://beta-api.customer.io/v1/api

List customer attributes

Parameters

id: The unique identifier for the customer

curl -i https://beta-api.customer.io/v1/api/customers/:id/attributes \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving customer attributes via the API returns all the attributes for a customer tracked in Customer.io by the passed Customer ID.

{
  "customer": {
    "id": "1",
    "attributes": {
      "_last_emailed": "1528932553",
      "created_at": "1489014595",
      "email": "test@example.com",
      "id": "1",
      "unsubscribed": "false"
    },
    "timestamps": {
      "_last_emailed": 1528932553,
      "created_at": 1489014595,
      "email": 1508932553,
      "id": 1489014595,
      "unsubscribed": 1489014595
    },
    "unsubscribed": false,
    "devices": [
      {
        "id": "my_android_device_id",
        "last_used": 1514764800,
        "platform": "android"
      },
      {
        "id": "my_ios_device_id",
        "last_used": 1514764800,
        "platform": "ios"
      }
    ]
  }
}

/customers/:id/segments

API Host: https://beta-api.customer.io/v1/api

List customer segments

Parameters

id: The unique identifier for the customer

curl -i https://beta-api.customer.io/v1/api/customers/:id/segments \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving customer segments via the API returns all the segments a customer is a member of within Customer.io.

{
  "segments": [
    {
      "id": 200006,
      "name": "Employees",
      "description": "Segment of Employees"
    },
    {
      "id": 200064,
      "name": "Converts",
      "description": "Segment for converted customers"
    },
    {
      "id": 200065,
      "name": "Did not receive January newsletter",
      "description": "Users that didn't receive the January newsletter"
    }
  ]
}

/customers/:id/messages

API Host: https://beta-api.customer.io/v1/api

Get metadata about messages sent to a customer

Parameters

id: The unique identifier for the customer
start: The contination token to retrieve the next set of messages. Note that the continuation token may end with an '=' character, so be sure to query escape the token.
limit: The number of messages to retrieve

# Get metadata about the first two messages.
curl -i https://beta-api.customer.io/v1/api/customers/:id/messages?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two messages.
curl -i https://beta-api.customer.io/v1/api/customers/:id/messages?limit=2&start=ZAEGAQLQ0_wRgPsS6F0cuig_iQ== \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving metadata about messages sent to a customer via the API returns the metadata in most recent order.

{
  "messages":[
      {
        "id": "ZAEBGWK1VfCkObbwmsWEDoq0cQ==",
        "msg_template_id": 223935,
        "customer_id": "12345",
        "recipient": "test@example.com",
        "subject": "Example Email",
        "metrics": {
          "delivered": 1523477582,
          "sent": 1523477582
        },
        "created": 1523477581,
        "failure_message": null,
        "newsletter_id": null,
        "campaign_id": 95913,
        "type": "email",
        "forgotten": false
      },
      {
        "id":"ZAEGAQLQ0_wRgPsS6F0cuig_iQ==",
        "msg_template_id": 484198,
        "customer_id":"12345",
        "recipient":"",
        "subject":"",
        "metrics":{
            "sent":1523921976
        },
        "created":1523921976,
        "failure_message":null,
        "newsletter_id":null,
        "campaign_id":1000207,
        "type":"webhook",
        "forgotten": false
      }
  ]
}

/customers/:id/activities

API Host: https://beta-api.customer.io/v1/api

Get data about activities performed by or for a customer

Parameters

id: The unique identifier for the customer
start: The contination token to retrieve the next set of activities. Note that the continuation token may end with an '=' character, so be sure to query escape the token.
type: The type of activity to return. This can be one of 'page', 'event', 'attribute_change', 'failed_attribute_change', 'stripe_event', 'drafted_email', 'failed_email', 'dropped_email', 'sent_email', 'spammed_email', 'bounced_email', 'delivered_email', 'triggered_email', 'opened_email', 'clicked_email', 'converted_email', 'unsubscribed_email', 'attempted_email', 'undeliverable_email', 'device_change', 'attempted_action', 'drafted_action', 'sent_action', 'delivered_action', 'bounced_action', 'failed_action', 'converted_action', 'undeliverable_action', 'opened_action', 'secondary:dropped_email', 'secondary:spammed_email', 'secondary:bounced_email', 'secondary:delivered_email', 'secondary:opened_email', 'secondary:clicked_email', 'secondary:failed_email'.
name: For 'event' the name of the event to search, and 'attribute_update' the name or attribute to search.
limit: The number of activities to retrieve

# Get metadata about the first two activities.
curl -i https://beta-api.customer.io/v1/api/customers/:id/activities?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two activities.
curl -i https://beta-api.customer.io/v1/api/customers/:id/activities?limit=2&start=ZAEGAQLQ0_wRgPsS6F0cuig_iQ== \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving data about activities performed by or for customer via the API returns the data in most recent order.

{
  "activities": [
    {
      "customer_id": "1",
      "data": {
        "delivered": null,
        "delivery_id": "ZAIAAVTJVG0QcCok0-0ZKj6yiQ==",
        "opened": null
      },
      "delivery_id": "ZAIAAVTJVG0QcCok0-0ZKj6yiQ==",
      "delivery_type": "email",
      "id": "01AK4N8V8G8KVA4HN8Y50CCZ59",
      "timestamp": 1397566226,
      "type": "sent_email"
    },
    {
      "customer_id": "1",
      "data": {
        "delivered": null,
        "delivery_id": "ZAIAAVTJVG0QR6BPPTMiMYxjGQ==",
        "opened": null
      },
      "delivery_id": "ZAIAAVTJVG0QR6BPPTMiMYxjGQ==",
      "delivery_type": "email",
      "id": "01AK4N8V8GCNZZNBNS2TR4A7EP",
      "timestamp": 1397566225,
      "type": "sent_email"
    },
    {
      "customer_id": "1",
      "data": {
        "email": {
          "from": "",
          "to": "test@example.com"
        }
      },
      "id": "01AK4N8V8G924GY4VR9AC9VJGJ",
      "timestamp": 1463666634,
      "type": "attribute_change"
    }
  ],
  "next": ""
}

/campaigns

API Host: https://beta-api.customer.io/v1/api

List campaigns

curl -i https://beta-api.customer.io/v1/api/campaigns \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving campaigns via the API returns information regarding your Customer.io campaigns.

{
  "campaigns": [
    {
      "id": 1000004,
      "name": "Example Segment Triggered Campaign",
      "type": "segment",
      "created": 1478031021,
      "updated": 1513303411,
      "active": true,
      "msg_templates": [
        {
          "id": 408145,
          "type": "email",
        }
      ]
    },
    {
      "id": 1000009,
      "name": "Example Event Triggered Campaign",
      "type": "event",
      "event_type": "purchased",
      "created": 1478282388,
      "updated": 1488310642,
      "active": true,
      "msg_templates": [
        {
          "id": 414883,
          "type": "email"
        },
        {
          "id": 437742,
          "type": "webhook"
        },
        {
          "id": 437744,
          "type": "push"
        },
        {
          "id": 437745
          "type": "email"
        }
      ]
    }
  ]
}

/campaigns/:id

API Host: https://beta-api.customer.io/v1/api

Get campaigns data

Parameters

id: The unique identifier of the template to be retrieved.

curl -i https://beta-api.customer.io/v1/api/campaigns/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of a campaign that was previously created. Must supply a valid campaign ID.

{
  "campaign": {
      "id": 1000004,
      "name": "Example Segment Triggered Campaign",
      "type": "segment",
      "created": 1478031021,
      "updated": 1513303411,
      "active": true,
      "msg_templates": [
        {
          "id": 408145,
          "type": "email",
        }
      ]
    }
}

/campaigns/:id/metrics

API Host: https://beta-api.customer.io/v1/api

Get campaign metrics

Parameters

id: The unique identifier for the campaign
period: Specify metric period. Possible values are 'hours', 'days', 'weeks', 'months', with a default being 'days'.
type: Specify metric type. Possible values are 'email', 'webhook', 'twilio', 'urban_airship', 'slack', 'push' with the default being empty meaning aggregated metrics for all possible types.

# Get by days (maximum being 192 days)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

# Get by weeks (maximum being 17 weeks)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics?period=weeks \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving campaign metrics via the API returns metrics for a given Customer.io campaign. The maximum amount of data is always retrieved, the metrics being in time order from least recent to most recent.

{
  "metric": {
    "series": {
      "2xx": [],
      "3xx": [],
      "4xx": [],
      "5xx": [],
      "attempted": [],
      "bounced": [],
      "clicked": [],
      "converted": [],
      "created": [],
      "delivered": [],
      "drafted": [],
      "dropped": [],
      "failed": [],
      "opened": [],
      "sent": [],
      "spammed": [],
      "undeliverable": [],
      "unsubscribed": []
    },
    "totals": {
      "2xx": 0,
      "3xx": 0,
      "4xx": 0,
      "5xx": 0,
      "attempted": 0,
      "bounced": 0,
      "clicked": 4,
      "converted": 0,
      "created": 40,
      "delivered": 40,
      "drafted": 0,
      "dropped": 0,
      "failed": 0,
      "opened": 26,
      "sent": 40,
      "spammed": 0,
      "undeliverable": 0,
      "unsubscribed": 0
    }
  }
}

/campaigns/:id/triggers

API Host: https://beta-api.customer.io/v1/api

Get triggered campaigns

Parameters

id: The unique identifier for the campaign

curl -i https://beta-api.customer.io/v1/api/campaigns/:id/triggers \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving campaign triggers via the API returns data for a given Customer.io triggered campaign.

{
  "triggers": [
    {
      "id": 3,
      "campaign_id": 1000130,
      "created_at": 1530129974,
      "processed_at": 1530129974
    },
    {
      "id": 2,
      "campaign_id": 1000130,
      "created_at": 1530129971,
      "processed_at": 1530129971
    },
    {
      "id": 1,
      "campaign_id": 1000130,
      "created_at": 1530129968,
      "processed_at": 1530129968
    }
  ]
}

/campaigns/:id/messages

API Host: https://beta-api.customer.io/v1/api

Get metadata about messages sent by a campaign

Parameters

id: The unique identifier for the campaign
start: The contination token to retrieve the next set of message metadata. Note that the continuation token may end with an '=' character, so be sure to query escape the token.
limit: The maximum number of messages to retrieve
type: Filter the messages metadata based on a message type. Allowable values are 'email', 'webhook', 'twilio', 'urban_airship', 'slack', 'push'.
state: Filter the message metadata based on a state. Allowable values are 'failed', 'sent', 'drafted', 'attempted'.
metric: Filter the message metadata based on a metric. Allowable values are 'created', 'drafted', 'attempted', 'sent', 'delivered', 'opened', 'clicked', 'converted', 'bounced', 'spammed', 'unsubscribed', 'dropped', 'failed', 'undeliverable'.

# Get metadata about the first two messages.
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/messages?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two messages.
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/messages?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving metadata about messages sent by a campaign via the API returns the metadata in reverse cronological order.

{
  "messages":[
      {
        "id": "ZAEBGWK1VfCkObbwmsWEDoq0cQ==",
        "msg_template_id": 223935,
        "customer_id": "12345",
        "recipient": "test@example.com",
        "subject": "Example Email",
        "metrics": {
          "delivered": 1523477582,
          "sent": 1523477582
        },
        "created": 1523477581,
        "failure_message": null,
        "newsletter_id": null,
        "campaign_id": 95913,
        "type": "email",
        "forgotten": false
      },
      {
        "id":"ZAEGAQLQ0_wRgPsS6F0cuig_iQ==",
        "msg_template_id": 484198,
        "customer_id":"12345",
        "recipient":"",
        "subject":"",
        "metrics":{
            "sent":1523921976
        },
        "created":1523921976,
        "failure_message":null,
        "newsletter_id":null,
        "campaign_id":1000207,
        "type":"webhook",
        "forgotten": false
      }
  ],
  "next": "MDox"
}

/newsletters

API Host: https://beta-api.customer.io/v1/api

List newsletters

curl -i https://beta-api.customer.io/v1/api/newsletters \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving newsletters via the API returns information regarding your Customer.io newsletters.

{
  "newsletters": [
    {
      "id": 128275,
      "msg_template_ids": [
        428849
      ],
      "name": "Example Newsletter",
      "subject": "Example Newsletter",
      "sent_at": null,
      "created": 1481653929,
      "updated": 1484870424
    },
    {
      "id": 136086,
      "msg_template_ids": [
        447740
      ],
      "name": "January Newsletter",
      "subject": "January Newsletter",
      "sent_at": 1488839714,
      "created": 1485540080,
      "updated": 1488839714
    }
  ]
}

/newsletters/:id

API Host: https://beta-api.customer.io/v1/api

Get newsletter data

Parameters

id: The unique identifier for the newsletter

curl -i https://beta-api.customer.io/v1/api/newsletters/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of a newsletter that was previously created. Must supply a valid newsletter ID.

{
  "newsletter": {
    "id": 128275,
    "msg_template_ids": [
      428849
    ],
    "name": "Example Newsletter",
    "subject": "Example Newsletter",
    "sent_at": null,
    "created": 1481653929,
    "updated": 1484870424
  }
}

/newsletters/:id/metrics

API Host: https://beta-api.customer.io/v1/api

Get newsletter metrics

Parameters

id: The unique identifier for the newsletter
period: Specify metric period. Possible values are 'hours', 'days', 'weeks', 'months', with a default being 'days'.

# Get by days (maximum being 192 days)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/metrics \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

# Get by weeks (maximum being 17 weeks)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/metrics?period=weeks \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving newsletter metrics via the API returns metrics for a given Customer.io newsletter campaign. The maximum amount of data is always retrieved, the metrics being in time order from least recent to most recent.

{
  "metric": {
    "series": {
      "2xx": [],
      "3xx": [],
      "4xx": [],
      "5xx": [],
      "attempted": [],
      "bounced": [],
      "clicked": [],
      "converted": [],
      "created": [],
      "delivered": [],
      "drafted": [],
      "dropped": [],
      "failed": [],
      "opened": [],
      "sent": [],
      "spammed": [],
      "undeliverable": [],
      "unsubscribed": []
    },
    "totals": {
      "2xx": 0,
      "3xx": 0,
      "4xx": 0,
      "5xx": 0,
      "attempted": 0,
      "bounced": 0,
      "clicked": 4,
      "converted": 0,
      "created": 40,
      "delivered": 40,
      "drafted": 0,
      "dropped": 0,
      "failed": 0,
      "opened": 26,
      "sent": 40,
      "spammed": 0,
      "undeliverable": 0,
      "unsubscribed": 0
    }
  }
}

/newsletters/:id/messages

API Host: https://beta-api.customer.io/v1/api

Get metadata about messages sent by a newsletter

Parameters

id: The unique identifier for the newsletter
start: The contination token to retrieve the next set of message metadata. Note that the continuation token may end with an '=' character, so be sure to query escape the token.
limit: The maximum number of messages to retrieve
state: Filter the message metadata based on a state. Allowable values are 'failed', 'sent', 'drafted', 'attempted'.
metric: Filter the message metadata based on a metric. Allowable values are 'created', 'drafted', 'attempted', 'sent', 'delivered', 'opened', 'clicked', 'converted', 'bounced', 'spammed', 'unsubscribed', 'dropped', 'failed', 'undeliverable'.

# Get metadata about the first two messages.
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/messages?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two messages.
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/messages?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving metadata about messages sent by a newsletter via the API returns the metadata in reverse cronological order.

{
  "messages":[
      {
        "id": "ZAEBGWK1VfCkObbwmsWEDoq0cQ==",
        "msg_template_id": 223935,
        "customer_id": "12345",
        "recipient": "test@example.com",
        "subject": "Example Email",
        "metrics": {
          "delivered": 1523477582,
          "sent": 1523477582
        },
        "created": 1523477581,
        "failure_message": null,
        "newsletter_id": 95913,
        "campaign_id": null,
        "type": "email",
        "forgotten": false
      },
      {
        "id":"ZAEGAQLQ0_wRgPsS6F0cuig_iQ==",
        "msg_template_id": 484198,
        "customer_id":"12345",
        "recipient":"",
        "subject":"Example email",
        "metrics":{
            "sent":1523921976
        },
        "created":1523921976,
        "failure_message":null,
        "newsletter_id":95913,
        "campaign_id":null,
        "type":"email",
        "forgotten": false
      }
  ],
  "next": "MDox"
}

/segments

API Host: https://beta-api.customer.io/v1/api

List segments

curl -i https://beta-api.customer.io/v1/api/segments \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving segments via the API returns information regarding your Customer.io segments.

{
  "segments": [
    {
      "id": 200005,
      "name": "Unsubscribed",
      "description": "custom unsubscribed users",
      "state": "finished",
      "progress": null
    },
    {
      "id": 200006,
      "name": "Employees",
      "description": "Segment of Employees",
      "state": "finished",
      "progress": null
    },
    {
      "id": 200057,
      "name": "No Email",
      "description": "Users without email attribute",
      "state": "finished",
      "progress": null
    },
    {
      "id": 200064,
      "name": "Converts",
      "description": "Segment for converted customers",
      "state": "finished",
      "progress": null
    },
    {
      "id": 200065,
      "name": "Did not receive January newsletter",
      "description": "Users that didn't receive the January newsletter",
      "state": "finished",
      "progress": null
    }
  ]
}

/segments/:id

API Host: https://beta-api.customer.io/v1/api

Get segment data

Parameters

id: The unique identifier for the segment

curl -i https://beta-api.customer.io/v1/api/segments/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of a segment that was previously created. Must supply a valid segment ID.

{
  "segment": {
    "id": 200005,
    "name": "Unsubscribed",
    "description": "custom unsubscribed users",
    "state": "finished",
    "progress": null
  },
}

/segments/:id/used_by

API Host: https://beta-api.customer.io/v1/api

Get dependencies of a segment

Parameters

id: The unique identifier for the segment

curl -i https://beta-api.customer.io/v1/api/segments/:id/used_by \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the campaigns and newsletters used by a given segment. Must supply a valid segment ID.

{
  "used_by": {
    "campaigns": [
      1000001,
      1000002
    ],
    "sent_newsletters": [],
    "draft_newsletters": []
  }
}

/segments/:id/customer_count

API Host: https://beta-api.customer.io/v1/api

Get number of customers in a segment

Parameters

id: The unique identifier for the segment

curl -i https://beta-api.customer.io/v1/api/segments/:id/customer_count \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves membership count for a given segment. Must supply a valid segment ID.

{
  "count": 123
}

/segments/:id/membership

API Host: https://beta-api.customer.io/v1/api

Get the membership of a segment

Parameters

id: The unique identifier for the segment
start: The contination token to retrieve the next set of ids
limit: The maximum number of ids to retrieve

# Get the first two ids,
curl -i https://beta-api.customer.io/v1/api/segments/:id/membership?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get the next two ids.
curl -i https://beta-api.customer.io/v1/api/segments/:id/membership?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the ids of the customers in a given sgement. Must supply a valid segment ID. Note that the continuation token may end with an ‘=’ character, so be sure to query escape the token.

{
  "ids": [
      "1",
      "2"
    ],
  "next": "MDox"
  }
}

/msg_templates

API Host: https://beta-api.customer.io/v1/api

Get message template data

Parameters

start: The continuation token to retrieve the next set of template data. Note that the continuation token may end with an '=' character, so be sure to query escape the token.
limit: The number of message template data to retrieve per request, maximum of 100 and a default of 10.

# Get data about the first two templates.
curl -i https://beta-api.customer.io/v1/api/msg_templates?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get data about the next two templates.
curl -i https://beta-api.customer.io/v1/api/msg_templates?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of message templates that were previously created.

{
  "msg_templates": [
    {
      "id": 408145,
      "campaign_id": 1000004,
      "newsletter_id": null,
      "name": "",
      "layout": "",
      "body": "This email has an unsubscribe link",
      "created": 1478038158,
      "updated": 1491007617,
      "type": "email",
      "from": "Cher Ami <test@example.com>",
      "from_id": 1,
      "reply_to": "",
      "reply_to_id": null,
      "preprocessor": "",
      "recipient": "",
      "subject": "Set-up your profile",
      "bcc": "",
      "fake_bcc": true,
      "preheader_text": ""
    },
    {
      "id": 408146,
      "campaign_id": null,
      "newsletter_id": 1000009,
      "name": "",
      "layout": "",
      "body": "This email should have an unsubscribe link",
      "created": 1478039267,
      "updated": 1491043529,
      "type": "email",
      "from": "Cher Ami <test@example.com>",
      "from_id": 1,
      "reply_to": "",
      "reply_to_id": null,
      "preprocessor": "",
      "recipient": "",
      "subject": "Example Email",
      "bcc": "",
      "fake_bcc": true,
      "preheader_text": ""
    }
   ],
   "next": "MDox"
  }

/msg_templates/:id

API Host: https://beta-api.customer.io/v1/api

Get message template data

Parameters

id: The unique identifier of the template to be retrieved.

curl -i https://beta-api.template.io/v1/api/msg_templates/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of a message template that was previously created. Must supply a valid template ID.

{
  "msg_template": {
    "id": 408145,
    "campaign_id": 1000004,
    "newsletter_id": null,
    "name": "",
    "layout": "",
    "body": "This email has an unsubscribe link",
    "created": 1478038158,
    "updated": 1491007617,
    "type": "email",
    "from": "Cher Ami <test@example.com>",
    "from_id": 1,
    "reply_to": "",
    "reply_to_id": null,
    "preprocessor": "",
    "recipient": "",
    "subject": "Set-up your profile",
    "bcc": "",
    "fake_bcc": true,
    "preheader_text": ""
  }
}

/msg_templates/:id/metrics

API Host: https://beta-api.customer.io/v1/api

Get message template metrics

Parameters

id: The unique identifier of the message template to retrieve metrics of.
period: Specify metric period. Possible values are 'hours', 'days', 'weeks', 'months', with a default being 'days'.

# Get by days (maximum being 192 days)
curl -i https://beta-api.customer.io/v1/api/msg_templates/:id/metrics \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

# Get by weeks (maximum being 17 weeks)
curl -i https://beta-api.customer.io/v1/api/msg_templates/:id/metrics \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving metrics for a message template via the API returns metrics for a given Customer.io message template. The maximum amount of data is always retrieved, the metrics being in time order from least recent to most recent.

{
  "metric": {
    "series": {
      "2xx": [],
      "3xx": [],
      "4xx": [],
      "5xx": [],
      "attempted": [],
      "bounced": [],
      "clicked": [],
      "converted": [],
      "created": [],
      "delivered": [],
      "drafted": [],
      "dropped": [],
      "failed": [],
      "opened": [],
      "sent": [],
      "spammed": [],
      "undeliverable": [],
      "unsubscribed": []
    },
    "totals": {
      "2xx": 0,
      "3xx": 0,
      "4xx": 0,
      "5xx": 0,
      "attempted": 0,
      "bounced": 0,
      "clicked": 4,
      "converted": 0,
      "created": 40,
      "delivered": 40,
      "drafted": 0,
      "dropped": 0,
      "failed": 0,
      "opened": 26,
      "sent": 40,
      "spammed": 0,
      "undeliverable": 0,
      "unsubscribed": 0
    }
  }
}

/messages

API Host: https://beta-api.customer.io/v1/api

List metadata about messages

Parameters

start: The contination token to retrieve the next set of message metadata. Note that the continuation token may end with an '=' character, so be sure to query escape the token.
limit: The maximum number of message metadata to retrieve
state: Filter the message metadata based on a state. Allowable values are 'failed', 'sent', 'drafted', 'attempted'.
type: Filter the messages metadata based on a message type. Allowable values are 'email', 'webhook', 'twilio', 'urban_airship', 'slack', 'push'.
metric: Filter the message metadata based on a metric. Allowable values are 'created', 'drafted', 'attempted', 'sent', 'delivered', 'opened', 'clicked', 'converted', 'bounced', 'spammed', 'unsubscribed', 'dropped', 'failed', 'undeliverable'.
campaign_id: Filter the message metadata based on a campaign id.
newsletter_id: Filter the message metadata based on a newsletter id.
template_id: Filter the message metadata based on a template id.

# Get metadata about the first two messages.
curl -i https://beta-api.customer.io/v1/api/messages?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two messages.
curl -i https://beta-api.customer.io/v1/api/messages?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving metadata about messages sent by a newsletter via the API returns the metadata in reverse cronological order.

{
  "messages":[
      {
        "id": "ZAEBGWK1VfCkObbwmsWEDoq0cQ==",
        "msg_template_id": 223935,
        "customer_id": "12345",
        "recipient": "test@example.com",
        "subject": "Example Email",
        "metrics": {
          "delivered": 1523477582,
          "sent": 1523477582
        },
        "created": 1523477581,
        "failure_message": null,
        "newsletter_id": 95913,
        "campaign_id": null,
        "type": "email",
        "forgotten": false
      },
      {
        "id":"ZAEGAQLQ0_wRgPsS6F0cuig_iQ==",
        "msg_template_id": 484198,
        "customer_id":"12345",
        "recipient":"",
        "subject":"Example email",
        "metrics":{
            "sent":1523921976
        },
        "created":1523921976,
        "failure_message":null,
        "newsletter_id":95913,
        "campaign_id":null,
        "type":"email",
        "forgotten": false
      }
  ],
  "next": "MDox"
}

/messages/:id

API Host: https://beta-api.customer.io/v1/api

Get metadata about messages

Parameters

id: The unique identifier for the message

curl -i https://beta-api.customer.io/v1/api/messages/:id \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the metadata about a message that was previously created. Must supply a valid message ID.

{
  "message":{
    "id": "ZAEBGWK1VfCkObbwmsWEDoq0cQ==",
    "msg_template_id": 223935,
    "customer_id": "12345",
    "recipient": "test@example.com",
    "subject": "Example Email",
    "metrics": {
      "delivered": 1523477582,
      "sent": 1523477582
    },
    "created": 1523477581,
    "failure_message": null,
    "newsletter_id": null,
    "campaign_id": 95913,
    "type": "email",
    "forgotten": false
  },
}

/exports

API Host: https://beta-api.customer.io/v1/api

List exports

curl -i https://beta-api.customer.io/v1/api/exports \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving exports via the API returns information regarding your Customer.io exports.

{
  "exports": [
    {
      "id": 110,
      "type": "customers",
      "failed": false,
      "description": "Customers with segment filters: in \"Purchased Flowers\"",
      "downloads": 2,
      "created_at": 1530296738,
      "updated_at": 1530296738
  }
}

/exports/:id

API Host: https://beta-api.customer.io/v1/api

Get export data

Parameters

id: The unique identifier for the export

curl -i https://beta-api.customer.io/v1/api/exports/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of an export that was previously created. Must supply a valid export ID.

{
  "export": {
    "id": 110,
    "type": "customers",
    "failed": false,
    "description": "Customers with segment filters: in \"Purchased Flowers\"",
    "downloads": 2,
    "created_at": 1530296738,
    "updated_at": 1530296738
  }
}

/exports/:id/download

API Host: https://beta-api.customer.io/v1/api

Download an export

Parameters

id: The unique identifier for the export

curl -i https://beta-api.customer.io/v1/api/exports/:id/download \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Downloading an export returns an signed link to download the content. The link expires after 15 minutes.

{
  "url": "path-to-get-the-content"
}

/activities

API Host: https://beta-api.customer.io/v1/api

Get data about activities

Parameters

start: The contination token to retrieve the next set of activities. Note that the continuation token may end with an '=' character, so be sure to query escape the token.
type: The type of activity to return. This can be one of 'page', 'event', 'attribute_change', 'failed_attribute_change', 'stripe_event', 'drafted_email', 'failed_email', 'dropped_email', 'sent_email', 'spammed_email', 'bounced_email', 'delivered_email', 'triggered_email', 'opened_email', 'clicked_email', 'converted_email', 'unsubscribed_email', 'attempted_email', 'undeliverable_email', 'device_change', 'attempted_action', 'drafted_action', 'sent_action', 'delivered_action', 'bounced_action', 'failed_action', 'converted_action', 'undeliverable_action', 'opened_action', 'secondary:dropped_email', 'secondary:spammed_email', 'secondary:bounced_email', 'secondary:delivered_email', 'secondary:opened_email', 'secondary:clicked_email', 'secondary:failed_email'.
name: For 'event' the name of the event to search, and 'attribute_change' the name or attribute to search.
deleted: If true, also return activities for deleted customers.
customer_id: Only find activities for a given customer id.
limit: The number of activities to retrieve

# Get metadata about the first two activities.
curl -i https://beta-api.customer.io/v1/api/activities?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two activities.
curl -i https://beta-api.customer.io/v1/api/activities?limit=2&start=ZAEGAQLQ0_wRgPsS6F0cuig_iQ== \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving data about activities the API returns the data in most recent order.

{
  "activities": [
    {
      "customer_id": "1",
      "data": {
        "delivered": null,
        "delivery_id": "ZAIAAVTJVG0QcCok0-0ZKj6yiQ==",
        "opened": null
      },
      "delivery_id": "ZAIAAVTJVG0QcCok0-0ZKj6yiQ==",
      "delivery_type": "email",
      "id": "01AK4N8V8G8KVA4HN8Y50CCZ59",
      "timestamp": 1397566226,
      "type": "sent_email"
    },
    {
      "customer_id": "1",
      "data": {
        "delivered": null,
        "delivery_id": "ZAIAAVTJVG0QR6BPPTMiMYxjGQ==",
        "opened": null
      },
      "delivery_id": "ZAIAAVTJVG0QR6BPPTMiMYxjGQ==",
      "delivery_type": "email",
      "id": "01AK4N8V8GCNZZNBNS2TR4A7EP",
      "timestamp": 1397566225,
      "type": "sent_email"
    },
    {
      "customer_id": "1",
      "data": {
        "email": {
          "from": "",
          "to": "test@example.com"
        }
      },
      "id": "01AK4N8V8G924GY4VR9AC9VJGJ",
      "timestamp": 1463666634,
      "type": "attribute_change"
    }
  ],
  "next": ""
}

/sender_identities

API Host: https://beta-api.customer.io/v1/api

Get sender identities data

Parameters

start: The continuation token to retrieve the next set of sender identity data. Note that the continuation token may end with an '=' character, so be sure to query escape the token.
limit: The number of sender identity data to retrieve per request, maximum of 100 and a default of 10.

# Get data about the first two identities.
curl -i https://beta-api.customer.io/v1/api/sender_identities?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get data about the next two identities.
curl -i https://beta-api.customer.io/v1/api/sender_identities?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of sender identities that were previously created.

{
  "sender_identities": [
    {
      "id": 4534,
      "name": "Cher Ami",
      "email": "test@example.com",
      "address": "Cher Ami <test@example.com>",
      "template_type": "email",
      "auto_generated":  "false",
    },
    {
      "id": 4535,
      "name": "Joe Everyman",
      "email": "test@example.com",
      "address": "Joe Everyman <test@example.com>",
      "template_type": "email",
      "auto_generated":  "false",
    },
   ],
   "next": "MDox"
  }

/sender_identities/:id

API Host: https://beta-api.customer.io/v1/api

Get sender identity data

Parameters

id: The unique identifier of the sender identity to be retrieved.

curl -i https://beta-api.customer.io/v1/api/sender_identities/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of a sender identity that was previously created.

{
  "sender_identity": 
    {
      "id": 4534,
      "name": "Cher Ami",
      "email": "test@example.com",
      "address": "Cher Ami <test@example.com>",
      "template_type": "email",
      "auto_generated":  "false",
    }
  }

/sender_identities/:id/used_by

API Host: https://beta-api.customer.io/v1/api

Get sender identity usage data.

Parameters

id: The unique identifier of the sender identity usage data is to be retrieved for.

curl -i https://beta-api.customer.io/v1/api/sender_identities/:id/used_by \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the usage details of a sender identity that was previously created.

{
  "campaigns": [ 
    543,
    793,
    8754
  ],
  "sent_newsletters": [
    82,
    986,
    294,
    36342
  ],
  "draft_newsletters": [
    4152,
    9876,
    46
  ]
}