Provide filters and attributes describing the customers you want to export. This endpoint returns export metadata; use the /exports/{export_id}/endpoint to download your export.

Provide filters for the newsletter, campaign, or action you want to return delivery information from. This endpoint starts an export, but you cannot download your export from this endpoint. Use the /exports/{export_id} endpoint to download your export.

Use the start and end to find messages within a time range. If your request doesn’t include start and end parameters, we’ll return the most recent 6 months of messages. If your start and end range is more than 12 months, we’ll return 12 months of data from the most recent timestamp in your request.

Return information about a specific export.

This endpoint returns a signed link to download an export. The link expires after 15 minutes.

This endpoint lets you upload a CSV file containing people, events, objects, or relationships. It provides a handy way of adding and updating them in bulk. Uploading people, objects, or relationships is like performing an identify call for each row in your CSV; uploading events is like performing a track call.

You’ll need to provide us the public URL of your CSV as a part of this operation. We recommend that you host your CSVs from short-lived URLs. Ideally, your URLs will expire 2 hours after you initiate an import so that your customers’ information doesn’t remain publicly available after you’ve uploaded it to us.

Check out the CSV requirements based on what you’re importing: people, events, and objects or relationships.

This endpoint returns information about an “import”—a CSV file containing a group of people or events you uploaded to using v1/imports endpoint. You can use this endpoint to check to status of imports, or find out how many rows you successfully imported from a CSV file.

Returns a list of IP addresses that you need to allowlist if you’re using a firewall or Custom SMTP provider’s IP access management settings to deny access to unknown IP addresses.

These addresses apply to all message types and webhooks, except push notifications.

Return a list of deliveries, including metrics for each delivery, for messages in your workspace. The request body contains filters determining the deliveries you want to return information about.

Use the start_ts and end_ts parameters to find messages within a time range. We limit your requests to 6 months. If your request doesn’t include start_ts and end_ts parameters, we’ll return the most recent 6 months of deliveries. If start_ts is greater than 6-months before end_ts, we only send back 6 months of data. If only end_ts is specified, we return 6 months of data before this timestamp. If only start_ts is specified, we then set the end_ts to the current time and deliver 6 months of data prior to this timestamp.

Return a information about, and metrics for, a delivery—the instance of a message intended for an individual recipient person.

Returns the archived copy of a delivery, including the message body, recipient, and metrics. This endpoint is limited to 100 requests per day.

Returns a list of your newsletters and associated metadata.

Returns metadata for an individual newsletter.

Returns the content variants of a newsletter—these are either different languages in a multi-language newsletter or A/B tests.

Returns information about a specific variant of a newsletter, where a variant is either a language in a multi-language newsletter or a part of an A/B test.

Update the contents of a newsletter variant (a specific language of your message or a part of an A/B test), including the body of a newsletter.

Returns a metrics for an individual newsletter variant—either an individual language in a multi-language newsletter or a message in an A/B test. This endpoint returns metrics both in total and in steps (days, weeks, etc) over a period of time. Stepped series metrics are arranged from oldest to newest (i.e. the 0-index for any result is the oldest period/step).

You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, ?period=days&steps=1 means two days - the 48 hours before the API request was made. ?period=days&steps=0 returns the same as the maximum of the period - ?period=days&steps=45. See the steps parameter below for the maximum count of each period.

Returns link click metrics for an individual newsletter variant—an individual language in a multi-language newsletter or a message in an A/B test. Unless you specify otherwise, the response contains data for the maximum period by days (45 days).

You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, ?period=days&steps=1 means two days - the 48 hours before the API request was made. ?period=days&steps=0 returns the same as the maximum of the period - ?period=days&steps=45. See the steps parameter below for the maximum count of each period.

Returns information about a specific language variant of a newsletter. If your newsletter includes A/B tests, use Get a translation in a newsletter test group.

Update the translation of a newsletter variant. If your newsletter includes A/B tests, use Update a translation in a newsletter test group.

Returns information about the deliveries (instances of messages sent to individual people) sent from a newsletter. Provide query parameters to refine the metrics you want to return.
Use the start_ts and end_ts to find messages within a time range. If your request doesn’t include start_ts and end_ts parameters, we’ll return up to 6 months of results beginning with the first delivery generated from the newsletter. If your start_ts and end_ts range is more than 12 months, we’ll return 12 months of data from the most recent timestamp in your request.

Returns a list of metrics for an individual newsletter in steps (days, weeks, etc). We return metrics from oldest to newest (i.e. the 0-index for any result is the oldest step/period).

You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, ?period=days&steps=1 means two days - the 48 hours before the API request was made. ?period=days&steps=0 returns the same as the maximum of the period - ?period=days&steps=45. See the steps parameter below for the maximum count of each period.

Returns metrics for link clicks within a newsletter, both in total and in series periods (days, weeks, etc). series metrics are ordered oldest to newest (i.e. the 0-index for any result is the oldest step/period).

You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, ?period=days&steps=1 means two days - the 48 hours before the API request was made. ?period=days&steps=0 returns the same as the maximum of the period - ?period=days&steps=45. See the steps parameter below for the maximum count of each period.

Returns information about a specific language variant of a newsletter in an A/B test group. You can retrieve test_group_ids from Get variants in a newsletter test group.

Update the translation of a newsletter variant in an A/B test. You can retrieve a list of test_group_ids from Get variants in a newsletter test group.

Returns information about each test group in a newsletter, including content ids for each group.

Returns a list of object types in your system. Because each object type is an incrementing ID, you may need to use this endpoint to find the ID of the object type you want to query, create, or modify.

Use a set of filter conditions to find objects in your workspace. Returns a list of object IDs that you can use to look up object attributes, or to create or modify objects.

The list is paged if you have a large number of objects. You can set the limit for the number of objects returned, and use the start to page through the results. It’s possible that you’ll see duplicate entries across pages. If you want to export objects or relationships, you may want to use the export feature in our UI to return complete results.

Get a list of attributes for an object. Attributes are things you know about an object—like an account name, billing date, etc.

Get a list of people people related to an object.

You can use the start parameter with the next property in responses to return pages of results. However, it’s possible that you’ll see duplicate entries across pages. If you want to export objects or relationships, you may want to use the export feature in our UI to return complete results.

Return a list of all of your reporting webhooks

Create a new webhook configuration.

Delete a reporting webhook’s configuration.

Returns information about a specific reporting webhook.

Update the configuration of a reporting webhook. Turn events on or off, change the webhook URL, etc.

Retrieve a list of all of your segments.

Create a manual segment with a name and a description. This request creates an empty segment.

Delete a manual segment.

Return information about a segment.

Returns the membership count for a segment.

Returns customers in a segment. This endpoint returns an array of identifiers; each object in the array represents a person and contains the identifier values allowed in your workspace. In general, we recommend that you use identifiers rather than ids to find people, because it provides more information.

If your workspace does not use email as a unique identifier for people, identifiers does not contain email values. Go to your Workspace Settings to find out which identifiers your workspace supports.

The ids array only lists ID values for people in a segment; if your workspace uses both email and id as identifiers, it’s possible that a member of your segment does not have an id value, resulting in an empty string in the ids array.

Use this endpoint to find out which campaigns and newsletters use a segment.

Manually trigger a broadcast, and provide data to populate messages in your trigger. The shape of the request changes based on the type of audience you broadcast to: a segment, a list of emails, a list of customer IDs, a map of users, or a data file. You can reference properties in the data object from this request using liquid—{{trigger.<property_in_data_obj>}}.

If your broadcast produces a 422 error, you can get more information about the errors to see what went wrong.

This endpoint is rate-limited to one request every 10 seconds. After exceeding this, you’ll receive a status of 429. Broadcasts are optimized to send messages to a large audience and not for one-to-one interactions. Use our transactional API or event-triggered campaigns to respond to your audience on an individual, one-to-one basis.

Send a transactional email. You can send a message using a transactional_message_id or send your own body, subject, and from values at send time. The transactional_message_id can be either the numerical ID for the template or the Trigger Name that you assigned the template.

If you want to send your own body, subject, and from values to populate your message at send time, we recommend that you pass a transactional_message_id anyway; the values you pass in the request will override the template.

You can find your transactional_message_id from the code sample in the Overview tab for your transactional message in the user interface, or you can look up a list of your transactional messages through the App API.

Customer.io attributes metrics to a transactional_message_id; if you don’t provide a transactional_message_id, we attribute metrics to "transactional_message_id": 1. You can create empty transactional messages in the UI and override the body, subject, and from values at send time. This provides flexibility in your integration and lets you organize metrics (rather than gathering metrics for all of your transactional messages against a single ID).

Send a transactional push. You send a message using a transactional_message_id for a transactional push message template composed in the user interface. You can optionally override any of the template values at send time. The transactional_message_id can be either the numerical ID for the template or the Trigger Name that you assigned the template.

You can find your transactional_message_id from the code sample in the Overview tab for your transactional message in the user interface, or you can look up a list of your transactional messages through the App API.

Returns a list of senders in your workspace. Senders are who your messages are “from”.

Returns information about a specific sender.

Returns lists of the campaigns and newsletters that use a sender.

Returns a list of snippets in your workspace. Snippets are pieces of reusable content, like a common footer for your emails.

In your payload, you’ll pass a name and value. Snippet names are unique. If the snippet name does not exist, we’ll create a new snippet. If the name exists, we’ll update the existing snippet.

Remove a snippet. You can only remove a snippet that is not in use. If your snippet is in use, you’ll receive a 400 error.