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
- 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.
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.
/segments/:id/add_customers
API Host: https://track.customer.io/api/v1
Add people to a manual segment
Parameters
- id
- The unique identifier of the segment
- ids
- A list of customer ids to add to the segment
curl -i https://track.customer.io/api/v1/segments/:id/add_customers \
-X POST \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
-H 'Content-Type:application/json' \
-d '{"ids":["customer_id1","customer_id2"]}'
cio.add_to_segment(segment_id=1,customer_ids=['customer_id1','customer_id2'])
cio.AddCustomersToSegment(1, []string["customer_id1","customer_id2"])
Manual segments are segments that you control by sending requests to our Behavioral Tracking API or by uploading lists of customers in the Customer.io application. You can add people to a segment by sending an add_customers request, and remove them by sending a remove_customers request.
There is a limit of 1000 customer ids per request
If you send customer ids that don’t exist yet in an add_customers request, we will automatically create customer profiles for the new customer ids.
NOTE: This API call is for use with manual segments only. It will NOT add anyone to data-driven segments. Please visit our documentation on segments to learn more about these segment types.
HTTP 200OK
A 200 response code signifies the request was accepted. All other response codes mean something went wrong.
/segments/:id/remove_customers
API Host: https://track.customer.io/api/v1
Remove people from a manual segment
Parameters
- id
- The unique identifier of the segment
- ids
- A list of customer ids to remove from the segment
curl -i https://track.customer.io/api/v1/segments/:id/remove_customers \
-X POST \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
-H 'Content-Type:application/json' \
-d '{"ids":["customer_id1","customer_id2"]}'
cio.remove_from_segment(segment_id=1,customer_ids=['customer_id1','customer_id2'])
cio.RemoveCustomersFromSegment(1, []string["customer_id1","customer_id2"])
There is a limit of 1000 customer ids per request
NOTE: This API call is for use with manual segments only. It will NOT remove anyone from data-driven segments. Please visit our documentation on segments to learn more about these segment types.
HTTP 200OK
A 200 response code signifies the request was accepted. 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
- ids
- List of profile ids to use as campaign recipients.
- id_ignore_missing
- If false (the default) a missing id is an error.
- emails
- List of email addresses which are mapped to customer.io profiles and used as campaign recipients.
- email_ignore_missing
- If false (the default) a missing email address is an error.
- email_add_duplicates
- If false (the default) an email address associated with more than one profile id is an error.
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 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://beta-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}}]}}'
# Find the first 10 unsubscribed customers
curl -i https://beta-api.customer.io/v1/api/customers?limit=10 \
-X POST \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
-H 'Content-Type:application/json' \
-d '{"filter":{"attribute":{"field":"unsubscribed","operator":"eq","value":"true"}}}'
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,
"deduplicate_id": "1000004:1513303411",
"name": "Example Segment Triggered Campaign",
"type": "segment",
"created": 1478031021,
"updated": 1513303411,
"active": true,
"msg_templates": [
{
"id": 408145,
"type": "email",
}
],
"first_started": 1478036379,
"created_by": test@example.com,
"tags": ["Example Campaign", "Human Resources"],
},
{
"id": 1000009,
"deduplicate_id": "1000009:1488310642",
"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"
}
],
"first_started": 1478282456,
"created_by": test@example.com,
"tags": ["Example Campaign", "Human Resources"],
}
]
}
/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,
"deduplicate_id": "1000004:1513303411",
"name": "Example Segment Triggered Campaign",
"type": "segment",
"created": 1478031021,
"updated": 1513303411,
"active": true,
"msg_templates": [
{
"id": 408145,
"type": "email",
}
],
"first_started": 1478036379,
"created_by": test@example.com,
"tags": ["Example Campaign", "Human Resources"],
}
}
/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'.
- steps
- Integer specifying how many steps to return. Defaults to the maximum number of timeperiods available, or 12 when using the 'months' period.
- 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
# Get by months (maximum being 120 months)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics?period=months \
-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==",
"deduplicate_id": "ZAEBGWK1VfCkObbwmsWEDoq0cQ==:1523477582",
"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==",
"deduplicate_id": "ZAEGAQLQ0_wRgPsS6F0cuig_iQ==:1523921976",
"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,
"deduplicate_id": "128275:1484870424",
"msg_template_ids": [
428849
],
"name": "Example Newsletter",
"subject": "Example Newsletter",
"sent_at": null,
"created": 1481653929,
"updated": 1484870424
},
{
"id": 136086,
"deduplicate_id": "136086:1488839714",
"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,
"deduplicate_id": "128275:1484870424",
"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'.
- steps
- Integer specifying how many steps to return. Defaults to the maximum number of timeperiods available, or 12 when using the 'months' period.
# 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==",
"deduplicate_id": "ZAEBGWK1VfCkObbwmsWEDoq0cQ==:1523477582",
"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==",
"deduplicate_id": "ZAEGAQLQ0_wRgPsS6F0cuig_iQ==:1523921976",
"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
Create manual segment
Parameters
- name
- Name of the manual segment
- description
- Description of the segment
curl -H "Content-Type: application/json" --request POST -d '{"segment":{"name":"Manual Segment 1","description":"Description for segment"}}' \
https://beta-api.customer.io/v1/api/segments \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
Creates a manual segment. Must supply a valid segment name.
{
"segment":{
"id":12,
"deduplicate_id":"12:1548355004",
"name":"Manual Segment 1",
"description":"Description for segment",
"state":"finished",
"progress":null,
"type":"manual"
}
}
/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,
"deduplicate_id": "200005:1484729714",
"name": "Unsubscribed",
"description": "custom unsubscribed users",
"state": "finished",
"progress": null
},
{
"id": 200006,
"deduplicate_id": "200006:1484729845",
"name": "Employees",
"description": "Segment of Employees",
"state": "finished",
"progress": null
},
{
"id": 200057,
"deduplicate_id": "200057:1484735231",
"name": "No Email",
"description": "Users without email attribute",
"state": "finished",
"progress": null
},
{
"id": 200064,
"deduplicate_id": "200064:1484737624",
"name": "Converts",
"description": "Segment for converted customers",
"state": "finished",
"progress": null
},
{
"id": 200065,
"deduplicate_id": "200065:1484749782",
"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,
"deduplicate_id": "200005:1484729714",
"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 segment. 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"
}
}
/segments/:id
API Host: https://beta-api.customer.io/v1/api
Delete an existing manual segment by id
Parameters
- id
- The segment id
curl -curl -X DELETE https://beta-api.customer.io/v1/api/segments/1 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
/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.
- sort
- Set the chronological order of the response. Allowable values are 'asc' for chronological order, the default value, and 'desc' for reverse-chronological order.
# 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,
"deduplicate_id": "408145:1491007617",
"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,
"deduplicate_id": "408146:1491043529",
"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.customer.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,
"deduplicate_id": "408145:1491007617",
"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'.
- steps
- Integer specifying how many steps to return. Defaults to the maximum number of timeperiods available, or 12 when using the 'months' period.
# Get by days (maximum being 192 days)
curl -i https://beta-api.customer.io/v1/api/msg_templates/:id/metrics?period=days \
-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?period=weeks \
-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==",
"deduplicate_id": "ZAEBGWK1VfCkObbwmsWEDoq0cQ==:1523477582",
"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==",
"deduplicate_id": "ZAEGAQLQ0_wRgPsS6F0cuig_iQ==:1523921976",
"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==",
"deduplicate_id": "ZAEBGWK1VfCkObbwmsWEDoq0cQ==:1523477582",
"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,
"deduplicate_id": "110:1530296738",
"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,
"deduplicate_id": "110:1530296738",
"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"
}
/exports/customers
API Host: https://beta-api.customer.io/v1/api
Create customer export
Parameters
- attributes
- The set of user attributes that should be included in the export
- filters
- The filter conditions that will determine which customers to include in the export
curl -i https://beta-api.customer.io/v1/api/exports/customers \
-X POST \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
-d '{"filters":{"and":[{"segment":{"id":7}},{"segment":{"id":5}}]}}'
Creates a customer export and returns the export record data
{
"export": {
"id": 110,
"deduplicate_id": "110:1530296738",
"type": "customers",
"failed": false,
"description": "Filtered customer export (created via the api)",
"downloads": 2,
"created_at": 1530296738,
"updated_at": 1530296738
}
}
/exports/deliveries
API Host: https://beta-api.customer.io/v1/api
Create delivery export
Parameters
- newsletter_id
- The unique identifier of the newsletter the export is for
- campaign_id
- The unique identifier of the campaign the export is for
- template_ids
- The unique identifiers of the templates the export is for
- start
- The unix timestamp that denotes the beginning of the period the export is for
- end
- The unix timestamp that denotes the end of the period the export is for
- attributes
- The attributes that should be included in the export
- and_filters
- The and conditions that denote which deliveries should be included in the export
- or_filters
- The or conditions that denote which deliveries should be included in the export
curl -i https://beta-api.customer.io/v1/api/exports/deliveries \
-X POST \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
-d {"newsletter_id": "10", "start": 1517529600, "end": 1517702400}
Creates a delivery export and returns the export record data
{
"export": {
"id": 111,
"deduplicate_id": "110:1530296738",
"type": "deliveries",
"failed": false,
"description": "Full deliveries export (created via the api)",
"downloads": 0,
"created_at": 1530296742,
"updated_at": 1530296742
}
}
/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.
The activities API retrieves the same data as seen in the UI which only goes back approximately 30 days.
{
"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.
- sort
- Set the chronological order of the response. Allowable values are 'asc' for chronological order, the default value, and 'desc' for reverse-chronological order.
# 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,
"deduplicate_id": "4534:1478035647",
"name": "Cher Ami",
"email": "test@example.com",
"address": "Cher Ami <test@example.com>",
"template_type": "email",
"auto_generated": "false",
},
{
"id": 4535,
"deduplicate_id": "4535:1478039359",
"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,
"deduplicate_id": "4534:1478035647",
"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
]
}
/reporting_webhooks/
API Host: https://beta-api.customer.io/v1/api
Create a new reporting webhook settings
Parameters
- endpoint
- The webhook URL
- events
- The webhook settings as json
- full_resolution
- Determines if only the first time or every time the event occurs.
curl -i https://beta-api.customer.io/v1/api/exports/customers \
-h "Content-Type: application/json" \
--request POST \
-d '{"endpoint":"http://example.com/webhook","events":{"customer_subscribed":false,"customer_unsubscribed":true,"email_attempted":true,"email_bounced":false,"email_clicked":true,"email_converted":false,"email_delivered":true,"email_drafted":false,"email_dropped":true,"email_failed":false,"email_opened":true,"email_sent":false,"email_spammed":true,"email_unsubscribed":false},"full_resolution":true}' \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
{
"reporting_webhooks":[
{
"endpoint":"http://example.com/webhook",
"events":{
"customer_subscribed":false,
"customer_unsubscribed":true,
"email_attempted":true,
"email_bounced":false,
"email_clicked":true,
"email_converted":false,
"email_delivered":true,
"email_drafted":false,
"email_dropped":true,
"email_failed":false,
"email_opened":true,
"email_sent":false,
"email_spammed":true,
"email_unsubscribed":true
},
"full_resolution":true,
"id":1
}
]
}
/reporting_webhooks/
API Host: https://beta-api.customer.io/v1/api
Get reporting webhook settings
curl -i https://beta-api.customer.io/v1/api/reporting_webhooks/ \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
Retrieves the settings of a reporting webhook.
{
"reporting_webhooks":[
{
"endpoint":"http://example.com/webhook",
"events":{
"customer_subscribed":false,
"customer_unsubscribed":true,
"email_attempted":true,
"email_bounced":false,
"email_clicked":true,
"email_converted":false,
"email_delivered":true,
"email_drafted":false,
"email_dropped":true,
"email_failed":false,
"email_opened":true,
"email_sent":false,
"email_spammed":true,
"email_unsubscribed":true
},
"full_resolution":true,
"id":1
}
]
}
/reporting_webhooks/:id
API Host: https://beta-api.customer.io/v1/api
Create a new reporting webhook settings
Parameters
- id
- The webhook id
- endpoint
- The webhook URL
- events
- The webhook settings as json
- full_resolution
- Determines if only the first time or every time the event occurs.
curl -i https://beta-api.customer.io/v1/api/exports/customers \
-h "Content-Type: application/json" \
--request PUT \
-d '{"endpoint":"http://example.com/webhook2","events":{"customer_subscribed":false,"customer_unsubscribed":true,"email_attempted":true,"email_bounced":false,"email_clicked":true,"email_converted":false,"email_delivered":true,"email_drafted":false,"email_dropped":true,"email_failed":false,"email_opened":true,"email_sent":false,"email_spammed":true,"email_unsubscribed":false},"full_resolution":false}' \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
{
"reporting_webhooks":[
{
"endpoint":"http://example.com/webhook2",
"events":{
"customer_subscribed":false,
"customer_unsubscribed":true,
"email_attempted":true,
"email_bounced":false,
"email_clicked":true,
"email_converted":false,
"email_delivered":true,
"email_drafted":false,
"email_dropped":true,
"email_failed":false,
"email_opened":true,
"email_sent":false,
"email_spammed":true,
"email_unsubscribed":true
},
"full_resolution":false,
"id":1
}
]
}
/reporting_webhooks/:id
API Host: https://beta-api.customer.io/v1/api
Delete an existing webhook settings
Parameters
- id
- The webhook id
curl -curl -X DELETE https://beta-api.customer.io/v1/api/reporting_webhooks/1 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE