Customer.io integration: operations for AI agents
Customer.io connects to Type.com as an integration. This page lists the 222 operations documented for Claude and Codex in Type.com: 116 read, 67 write, 39 destructive.
About Customer.io
Customer.io API reference operations, subject to Type setup and account permissions.
Categories: Marketing & Social
How to connect Customer.io to Type.com
- Connect
- Configure provider-specific API target and authentication setup.
- Access
- Organization connection: one shared account for the workspace.
To add the connection, follow the steps in Space connections.
Documented operations
222 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.
222 operations listed.
trackRegion
- Read
Find your account region
This endpoint returns the appropriate region and URL for your Track API credentials. Use it to determine the URLs you should use to successfully complete other requests. You can perform this operation against either of the track API regional URLs; it returns your region in either case. This endpoint also returns an `environment_id`, which represents the workspace the credentials are valid for.
GET /api/v1/accounts/region
Track Customers
- Write
Add or update a customer device
Customers can have more than one device. Use this method to add iOS and Android devices to, or update devices for, a customer profile.
PUT /api/v1/customers/{identifier}/devices - Write
Unsuppress a customer profile
Unsuppressing a profile allows you to add the customer back to Customer.io. If you unsuppress a person in a workspace that identifies people by *email or ID* and the suppressed person had both an email and ID, both the person's email and ID are unsuppressed. Unsuppressing a profile does not recreate the profile that you previously suppressed. Rather, it just makes the identifier available again. Identifying a person after unsuppressing them creates a new profile, with none of the history of the previously suppressed identifier.
POST /api/v1/customers/{identifier}/unsuppress - Destructive
Add or update a customer
Adds or updates a person. If your request does _not_ include `cio_id` and the identifiers in the request body do not belong to a person, your request adds a person. If a person already exists with the identifier in the request path, your request updates that person. If the identifier in the path does not belong to a person but you use an identifier in your request body that _does_ belong to a person, your request updates the person and assigns them the identifier in the path. If the identifier in the path and request body belong to different people, your request may return `200 OK` but produce an *Attribute Update Failure* for the identifier in the payload. If you want to update a person's identifiers after they are set, you must reference them using their `cio_id` in the format `cio_<cio_id_value>`—unless when updating an `email` with the [Allow updates to email using ID](/accounts/workspaces#update-email-with-id) setting enabled. You can get the `cio_id` value from the [App API](/integrations/api/app/tag/customers/). If your request includes a `cio_id`, we'll attempt to update that person, including any identifiers in the request. If the `cio_id` does not exist or belongs to a person who was deleted, we'll drop the request. For workspaces using `email` as an identifier, `email` is case-insensitive. The addresses `person@example.com` and `PERSON@example.com` would represent the same person. **Tip**: If your workspace identifies people by both `email` and `id`, and you send an identify call with a new `id` but an `email` that already belongs to someone, we update the existing person rather than creating a new one. The existing person gets the new `id`. This is a common source of confusion during testing—if you're generating new IDs but reusing the same email address, you're updating one person repeatedly, not creating multiple people.
PUT /api/v1/customers/{identifier} - Destructive
Delete a customer
Deleting a customer removes them, and all of their information, from Customer.io. **NOTE**: Calls that update customers by ID can also create a customer. If you send data to Customer.io through other means (like the Javascript snippet), after you delete a customer, you may accidentally recreate the customer. You cannot delete a customer using the Javascript snippet alone.
DELETE /api/v1/customers/{identifier} - Destructive
Delete a customer device
Remove a device from a customer profile. If you continue sending data about a device to Customer.io, you may inadvertently re-add the device to the customer profile.
DELETE /api/v1/customers/{identifier}/devices/{device_id} - Destructive
Suppress a customer profile
Delete a customer profile and prevent the person's identifier(s) from being re-added to your workspace. Any future API calls or operations referencing the specified ID are ignored. If you suppress a person in a workspace that identifies people by *email or ID* and both identifiers are set, both the person's email and ID are suppressed. <div class="fly-panel bg-warning"> <div class="fly-panel-body"> <p class="callout-head text--bold text-warning mrg-t-none"><svg class="api-icon"><path fill-rule="evenodd" clip-rule="evenodd" d="M15.4127 13.3333L9.18133 1.43333C8.95116 0.994094 8.49623 0.718884 8.00033 0.718884C7.50444 0.718884 7.04951 0.994094 6.81933 1.43333L0.587332 13.3333C0.370821 13.7467 0.386147 14.2431 0.627743 14.6423C0.869339 15.0415 1.30205 15.2854 1.76867 15.2853H14.2313C14.698 15.2854 15.1307 15.0415 15.3723 14.6423C15.6139 14.2431 15.6292 13.7467 15.4127 13.3333ZM7.33333 5.61533C7.33333 5.24714 7.63181 4.94867 8 4.94867C8.36819 4.94867 8.66667 5.24714 8.66667 5.61533V9.61533C8.66667 9.98352 8.36819 10.282 8 10.282C7.63181 10.282 7.33333 9.98352 7.33333 9.61533V5.61533ZM8.01466 13.2887H8.03333C8.29806 13.2844 8.54988 13.1735 8.73182 12.9812C8.91376 12.7888 9.01044 12.5312 9 12.2667C8.97854 11.7209 8.53019 11.2893 7.984 11.2887H7.96533C7.70125 11.2935 7.4502 11.4043 7.26865 11.5961C7.0871 11.788 6.99029 12.0447 7 12.3087C7.02073 12.8546 7.46838 13.2869 8.01466 13.2887Z" /></svg> This API permanently deletes people</p> <div class="text-warning"><p>Suppressing a person way deletes their profile <i>and</i> suppresses the identifier you reference in the path of this call, preventing you from re-adding a person using the same identifier (until you unsuppress the identifier). You cannot recover a profile after you suppress it. In general, should use this API sparingly—for GDPR/CCPA requests, etc. </p> <p>If you want to keep a record of a person but prevent them from receiving messages, you should set the person's unsubscribed attribute (or use other attributes to represent complex subscription preferences) instead.</p></div> </div> </div>
POST /api/v1/customers/{identifier}/suppress - Destructive
Custom unsubscribe handling
This endpoint lets you set a global unsubscribed status outside of the subscription pathways native to Customer.io. If you use [custom unsubscribe links](/journeys/people/multiple-subscription-types), you can host a custom unsubscribe page and use this API to send unsubscribe data, associated with a particular delivery, to Customer.io. **NOTE**: This endpoint **requires** a `Content-type: application/json` header. This endpoint **does not require** an `Authorization` header. Your request sets a person's `unsubscribed` attribute to `true`, attributes their unsubscribe request to the individual email/delivery that they unsubscribed from, and lets you segment your audience based on `email_unsubscribed` events when you use a custom subscription center. If you use a custom subscription center (managing subscriptions to various types of messages with custom attributes), this request *does not* set a custom attribute. You must perform a [separate request](/integrations/api/track/tag/track-customers/identify/) to update a person's custom subscription attributes.
POST /unsubscribe/{delivery_id} - Destructive
Merge duplicate people
Merge two customer profiles together. The payload contains `primary` and `secondary` profile objects. The primary profile remains after the merge and the secondary is deleted. This operation is _not_ reversible. The primary profile must already exist in Customer.io for the merge operation to work. If the primary profile doesn't exist, your request won't do anything. If you perform requests concurrently or in rapid succession, you could create a race condition where the primary profile doesn't exist yet. For example, if you identify a person and send a request to this endpoint immediately, the primary profile might not exist when we process your merge request. The following information is merged into the primary profile from the secondary profile: * Attributes that are not set, or are empty, on the primary. * The most recent 30-days of event history. Events merged from the secondary person cannot trigger automations. * Manual segments that the primary person did not already belong to. * Message delivery history. * Automation journeys that the primary person has not entered. If the secondary person has started a journey that the primary person has not, the primary person continues on that automation journey after the merge. If the secondary person has completed journeys that the primary person has not, the primary person gains these historical journeys after the merge. This may be important for determining entry (or re-entry) criteria for subsequent automations, segments, etc.
POST /api/v1/merge_customers
Track Events
- Write
Track a customer event
Send an event associated with a person, referenced by the identifier in the path. There are three defined event `type` values: `page`, `screen` and `event`. Page and screen events represent website page views and mobile app screen views respectively; the `name` for these event types is intended to be the page or screen a person visited or viewed. Any other event, is given the `event` type. We automatically trim leading and trailing spaces from event names. **Reserved Properties** There are a few important values which, if sent with the events that trigger automations, will override your automation settings: * `from_address` * `recipient` * `reply_to` When using the Javascript snippet to track events, you must call the Behavioral Tracking API call after identifying the customer or the event will not associate with the customer’s profile.
POST /api/v1/customers/{identifier}/events - Write
Track an anonymous event
An anonymous event represents a person you haven't identified yet. When you identify a person, you can set their `anonymous_id` attribute. If [event merging](https://fly.customer.io/workspaces/last/settings/merge_options) is turned on in your workspace, and the attribute matches the `anonymous_id` in one or more events that were logged within the last 30 days, we associate those events with the person. If you associate an event with a person within 72 hours of the timestamp on the event, you can trigger automations from the event. There are three possible event `type` values: `page`, `screen` and `event`. Page and screen events represent website page views and mobile app screen views respectively; the `name` for these event types is intended to be the page or screen a person visited or viewed. Any other event, is given the `event` type. **Note**: Avoid using names with leading or trailing spaces, because you can't reference event names with leading or trailing spaces in automations, etc. In workspaces created after September 21, 2021, we trim leading and trailing spaces from event names automatically to fix this issue.
POST /api/v1/events - Write
Report metrics
This endpoint helps you report metrics from channels that aren't native to Customer.io or don't rely on our SDKs. When we deliver a message, we include a CIO-Delivery-ID header. This is the `delivery_id` in the payload. You can use it as a UTL and you can pass it as a UTM parameter in links, etc to track metrics when people click, convert, etc.
POST /api/v1/metrics - Write
Report push metrics (deprecated)
While this endpoint still works, you should take advantage of our [universal metrics endpoint](/integrations/api/track/tag/track-events/metrics/). It supports channels besides push and lets you provide additional information with some metrics. Use this endpoint to report device-side push metrics—opened, converted, and delivered—back to Customer.io, so you can track the effectiveness of your push notifications. Customer.io has no way of knowing about these metrics, or associating metrics with a specific message, unless you report them back to us. When Customer.io delivers a push notification, we include `CIO-Delivery-ID` and `CIO-Delivery-Token` parameters. Reference these in your payload as the `delivery_id` and `device_id` respectively with the type of device-side `event` metric that you want to associate with your push notification and the person represented by the `device_id`.
POST /api/v1/push/events
Forms
- Write
Submit a form
Submit a form response. If Customer.io does not recognize the `form_id` we create a new form connection (found on the *Data & Integrations* > *Integrations* > *Forms* page). Form submissions with the same ID are treated as submissions from the same form. The `data` object _must_ contain at least one of `id` or `email` (depending on the identifiers supported in your workspace)—or a field that is mapped to one of these identifiers—to identify the form respondent. If the person who submitted the form does not already exist, we create them (like an [identify](/integrations/api/track/tag/track-customers/identify/) request). Additional keys in the `data` object represent form fields and values from the form that a person submitted. By default, we map form fields in your request directly to attributes, e.g. if you have a form field called `first_name`, we map that field to the `first_name` attribute. **NOTES**: * You cannot disable fields that you send to this API. If you send a field (as `data`) to this API, we'll include it in the form submission. * If an identifier in your form is called something like `email_address` rather than `email` in your initial request, you'll receive a `400`, but we'll still add your form on the **Data & Integrations** > **Integrations** > **Forms** page. You can then re-map your `email_address` field to `email`, and your form will begin working normally. * Customer.io reserves `form_id`, `form_name`, `form_type`, `form_url`, and `form_url_param` keys. If your request includes these keys, Customer.io ignores them.
POST /api/v1/forms/{form_id}/submit
Track Segments
- Write
Add people to a manual segment
Add people to a manual segment by ID. You are limited to 1000 customer IDs per request. This endpoint lets you add people to manual segments, but a segment must exist before you can add people to it. You can create and find manual segments using the [App API](/integrations/api/app/tag/segments/createManSegment/). When you call this API, you can pass an `id_type` query parameter determining the type of identifier you want to use, `id`, `email`, or `cio_id`; If you don't pass this parameter, it defaults to `id`. The request body always uses `ids`, even though it'll accept either IDs, emails, or `cio_id`s depending on the query parameter. Everybody in the payload must use the same kind of identifier; we'll ignore values in the `ids` array that don't match the `id_type` parameter. **NOTE**: You cannot add people to data-driven segments using the API. See [our documentation on segments](/journeys/segmentation/segments) for more information about segments.
POST /api/v1/segments/{segment_id}/add_customers - Destructive
Remove people from a manual segment
You can remove users from a manual segment by ID. You are limited to 1000 customer IDs per request. This endpoint requires people to have `id` attributes. If your workspace does not use `id` as an identifier, or you have not assigned people `id` values, you cannot remove people from manual segments using the API. Our user interface does not have this limitation. You can remove people from manual segments through the UI as a part of an automation workflow. **NOTE**: You cannot remove people from data-driven segments using the API. See [our documentation on segments](/journeys/segmentation/segments) for more information about segments.
POST /api/v1/segments/{segment_id}/remove_customers
track_v2
- Destructive
Make a single request
This endpoint lets you create, update, or delete a single person or object—including managing relationships between objects and people. An "object" is any kind of non-person entity that you want to associate with one or more people—like a company, an educational course that people signed up for, a product, etc. Your request must be smaller than 32kb.
POST /api/v2/entity - Destructive
Send multiple requests
This endpoint lets you batch requests for different people and objects in a single request. Each object in your array represents an individual "entity" operation—it represents a change for a person, an object, or a delivery. You can mix types in this request; you are not limited to a batch containing only objects or only people. An "object" is a non-person entity that you want to associate with one or more people—like a company, an educational course that people enroll in, etc. Your batch request must be smaller than 500kb. Each of the requests within the batch must also be 32kb or smaller.
POST /api/v2/batch
Send Messages
- Write
Send an API-triggered broadcast
Trigger a broadcast and optionally provide data to populate liquid placeholders in the message. To trigger one-time send broadcasts, use the [one-time send endpoint](/integrations/api/app/tag/send-messages/sendNewsletter/). Broadcasts are optimized to send messages to a large audience and not for one-to-one interactions. Use our [transactional API](/integrations/api/app/tag/send-messages/sendEmail/) or [event-triggered automations](/journeys/send/campaigns/triggers/#event-trigger) to respond to your audience on an individual, one-to-one basis. **Define your audience** **The shape of the request depends on how you define your audience**: default (the recipients set in the UI), custom conditions, a list of emails, a list of customer IDs, a map of users, or a data file. You can narrow any of these audiences, except the default audience, with the `filter` object. This is useful when a file or a list of people is broader than the audience you want for your broadcast. **You can only trigger broadcasts to send to people you've already added to your workspace.** A broadcast cannot add or identify new people. If you reference people who don't exist in your broadcast audience, the broadcast will fail by default. You can override this behavior by setting the `email_ignore_missing` and/or `id_ignore_missing` flags to `true`. The broadcast will skip over any people who don't exist in your workspace and send to the remaining recipients. You can reference properties in the `data` object in your broadcast using liquid—`{{trigger.<property_in_data_obj>}}`. **Send or schedule your broadcast** By default, we send your broadcast as soon as you trigger it. Set `scheduled_at` to send it at a future time instead. You can [cancel the trigger](/integrations/api/app/tag/send-messages/cancelBroadcastTrigger/) to stop a scheduled send before it starts sending. You can't change a trigger's `scheduled_at` value later; if you need to reschedule your broadcast, you must cancel the trigger and re-trigger the broadcast with the new timestamp. If your broadcast produces a `422` error, you can [get more information about the errors](/integrations/api/app/tag/broadcasts/broadcastErrors/) 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`. Learn more about [API-triggered broadcast limits](/integrations/api/app/tag/send-messages/) above. If you need to trigger broadcasts more often, contact us to talk through your use case.
POST /v1/campaigns/{broadcast_id}/triggers - Write
Trigger a one-time send
Trigger a one-time send (referred to as a "newsletter" in our APIs) immediately. It must be in a draft state. If it has already been sent, you'll get a `400` error. The recipients are fixed when you create the one-time send. If you're not sure who will receive it, you can use the [List one-time sends](/integrations/api/app/tag/newsletters/listNewsletters/) endpoint to get a list of one-time sends and their recipients. To reschedule a one-time send, use the [Schedule a one-time send](/integrations/api/app/tag/send-messages/scheduleNewsletter/) endpoint instead.
POST /v1/newsletters/{newsletter_id}/send - Write
Schedule a one-time send
Schedule a one-time send (referred to as a "newsletter" in our APIs) to send at a specific time. It must be in a draft state. If it has already been sent, you'll get a `400` error. If it's already scheduled, this endpoint updates the scheduled time. The response returns the one-time send, so you can read back the schedule you set: `send_state` and `scheduled_at` are always included, and `timezone` and `tz_match_enabled` are included when they apply. To retrieve the schedule parameters after scheduling with [Get a one-time send](/integrations/api/app/tag/newsletters/getNewsletters/). After you start a send with timezone-match, `scheduled_at` reports the next timezone batch or the remainder of an A/B test instead of the time you requested. The recipients are fixed when you create the one-time send. If you're not sure who will receive it, you can use the [List one-time sends](/integrations/api/app/tag/newsletters/listNewsletters/) endpoint to get a list of one-time sends and their recipients.
POST /v1/newsletters/{newsletter_id}/schedule - Write
Send a transactional email
Send a transactional email. While not strictly required, we recommend that you include a `transactional_message_id` in your request. If you don't, Customer.io attributes metrics to `"transactional_message_id": 1`, so multiple messages can roll up under the same ID. If this is the first time you send a message with the API, you can include the `auto_create` parameter along with a `transactional_message_id` string to create a record for you. You can also include a `body`, `subject`, and `from` values to override the message template. Or, if you create your message entirely through the API, you *must* include these values because your `transactional_message_id` won't have any content. See [Examples and API parameters](/journeys/send/transactional/email/#auto-create-transactional-message-records) for more details.
POST /v1/send/email - Write
Send a transactional in-app message
Send a transactional in-app message. In-app messages render in your application through the Customer.io SDK to the devices associated with the person you target by `identifiers`. You send a message using a `transactional_message_id` for an in-app message template that you've set up in the user interface. 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](/integrations/api/app/tag/transactional/). **Note**: Your workspace must have in-app messaging enabled. Requests sent to a workspace without the in-app capability return `403`.
POST /v1/send/in_app - Write
Send a transactional inbox message
Send a transactional inbox message. Inbox messages deliver raw JSON payloads to your application through our JavaScript SDK, allowing you to build custom notification centers, message feeds, and other UI components. You send a message using a `transactional_message_id` for an inbox message template created in the user interface. 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](/integrations/api/app/tag/transactional/). **Note**: Inbox messages are currently available for web platforms only and require the Customer.io In-App Plugin to be installed.
POST /v1/send/inbox_message - Write
Send a transactional push
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](/integrations/api/app/tag/transactional/).
POST /v1/send/push - Write
Send a transactional SMS
Send a transactional SMS message. To send a message, you'll need to provide a `transactional_message_id`. This is either the numerical ID of your transactional message 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](/integrations/api/app/tag/transactional/).
POST /v1/send/sms - Write
Send a transactional WhatsApp message
Send a transactional WhatsApp message. To use this endpoint, you must be integrated with [WhatsApp Business](/messaging/send/transactional/whatsapp/#before-you-begin), not Twilio. Then you need to [create the template in the UI and have it approved by WhatsApp/Meta](/messaging/design-studio/whatsapp-design-studio/) before sending it. To send a message, you need to provide a `transactional_message_id`. This is either the numerical ID of your transactional message 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](/integrations/api/app/tag/transactional/listTransactional/).
POST /v1/send/whatsapp - Destructive
Cancel a scheduled broadcast
Cancel a trigger you [scheduled](/integrations/api/app/tag/send-messages/triggerBroadcast/) with `scheduled_at`, before it fires. The request fails if the broadcast has started calculating its audience, is already sending, or has already sent. A trigger with a `rate_limit` is the exception: you can cancel it while it sends. Canceling stops more people from entering the broadcast, and people who already entered continue through your workflow.
POST /v1/campaigns/{broadcast_id}/triggers/{trigger_id}/cancel
Broadcasts
- Read
Get broadcast error descriptions
If your broadcast produced validation errors, this endpoint can help you better understand what went wrong. Broadcast errors are generally issues in your broadcast audience and associated.
GET /v1/campaigns/{broadcast_id}/triggers/{trigger_id}/errors - Read
List broadcasts
Returns a list of your API-triggered broadcasts and associated metadata.
GET /v1/broadcasts - Read
Get a broadcast
Returns metadata for an individual broadcast.
GET /v1/broadcasts/{broadcast_id} - Read
Get the status of a broadcast
After triggering a broadcast you can retrieve the status of that broadcast using a GET of the `trigger_id`. You can retrieve the `trigger_id` from [Get broadcast triggers](/integrations/api/app/tag/broadcasts/listBroadcastTriggers/).
GET /v1/campaigns/{broadcast_id}/triggers/{trigger_id} - Read
Get broadcast metrics
Returns a list of metrics for an individual broadcast 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.
GET /v1/broadcasts/{broadcast_id}/metrics - Read
Get broadcast link metrics
Returns metrics for link clicks within a broadcast, 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.
GET /v1/broadcasts/{broadcast_id}/metrics/links - Read
List broadcast actions
Returns the actions that occur as a part of a broadcast. If a message block contains multiple languages, this endpoint returns an object for each language variant. Each language variant includes the `multi_language_branch_action_id` property with the same value. Use this id to retrieve metrics for each language variant in a single request through [Get broadcast action metrics](/integrations/api/app/tag/broadcasts/broadcastActionMetrics/).
GET /v1/broadcasts/{broadcast_id}/actions - Read
Get messages for a broadcast
Returns information about the deliveries (instances of messages sent to individual people) sent from an API-triggered broadcast. 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 results for the 1 month period after the first trigger. 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. Timestamps reflect when deliveries were created in our system, not when they were actually sent to recipients. There may be a delay between creation and sending.
GET /v1/broadcasts/{broadcast_id}/messages - Read
Get a broadcast action
Returns information about a specific action within a broadcast.
GET /v1/broadcasts/{broadcast_id}/actions/{action_id} - Read
Get a translation of a broadcast message
Returns information about a translation of message in a broadcast. The message is identified by the `action_id`.
GET /v1/broadcasts/{broadcast_id}/actions/{action_id}/language/{language} - Read
Get broadcast action metrics
Returns a list of metrics for an individual action both in total and in `steps` (days, weeks, etc) over a period of time. Stepped `series` metrics return 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. **Multi-language messages** If the action is a [multi-language](/messaging/channels/localization/getting-started/) message, you can retrieve metrics for a single language variant or all language variants. To retrieve metrics for a single language variant, pass the `id` of the action. To retrieve aggregate metrics and a breakdown for each language variant, pass the `multi_language_branch_action_id`, which is the same for each variant of a message. You can get both ids from the [List broadcast actions](/integrations/api/app/tag/broadcasts/broadcastActions/) endpoint. If you pass the `multi_language_branch_action_id`, then the `metric` object shows the *total* across every variant. The `language_variants` object shows a breakdown for each language variant. If you want to get the sum of all metrics across all of a broadcast's actions, you can use each action id of a multi-language message, like you would for other types of actions.
GET /v1/broadcasts/{broadcast_id}/actions/{action_id}/metrics - Read
Get broadcast action link metrics
Returns link click metrics for an individual broadcast action. 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.
GET /v1/broadcasts/{broadcast_id}/actions/{action_id}/metrics/links - Read
Get broadcast triggers
Returns a list of the `triggers` for a broadcast.
GET /v1/broadcasts/{broadcast_id}/triggers - Write
Update a broadcast action
Update the contents of a broadcast action, including the body of messages or HTTP requests. **NOTE** You cannot manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](/integrations/api/design-studio/) instead.
PUT /v1/broadcasts/{broadcast_id}/actions/{action_id} - Write
Update a translation of a broadcast message
Update a translation of a specific broadcast action, including the body of messages or HTTP requests. **NOTE** You cannot manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](/integrations/api/design-studio/) instead.
PUT /v1/broadcasts/{broadcast_id}/actions/{action_id}/language/{language}
Live Notifications
- Read
Get a live notification's status
Look up a live notification's current state, lifecycle timestamps, and the status of its most recent delivery.
GET /v1/live_notifications/{instance_id} - Write
Start a live notification
Start a live notification for a profile. Customer.io mints an `instance_id` for the new activity and returns it. You'll use this ID to update, end, or check the status of the activity. [On iOS](/integrations/sdk/ios/live-activities/set-up/#step-5-start-an-activity), this delivers a push-to-start event through APNs, so the person's device must have a registered push-to-start token for the `notification_type` (the SDK registers one automatically when your app registers the activity type). Push-to-start requires iOS 17.2 or later. iOS starts also require a `push_payload.alert` with a title and body. [On Android](/integrations/sdk/android/live-notifications/set-up/#step-4-start-a-notification), this delivers an FCM data message, which the SDK renders without your app being open.
POST /v1/live_notifications/start - Destructive
Update a live notification
Push a new content state to a running activity, referenced by its `instance_id`. The device re-renders the activity from the state you send. Send the **full** content state on every update, not just the fields that changed—the platforms don't support partial updates. `push_payload` is optional on updates, whether Customer.io delivers directly through APNs or relays through Firebase Cloud Messaging (FCM). If you include a `push_payload.alert`, it must contain both a `title` and a `body`.
POST /v1/live_notifications/update - Destructive
End a live notification
End a running activity, referenced by its `instance_id`. On iOS, the system dismisses the activity from the Lock Screen. On Android, the SDK normally renders the final content as a non-ongoing notification; it cancels the notification only when there's no final notification to render. You can include a final `content_state` to show before the activity ends. `push_payload` is optional on the end call, whether Customer.io delivers directly through APNs or relays through Firebase Cloud Messaging (FCM). If you include a `push_payload.alert`, it must contain both a `title` and a `body`.
POST /v1/live_notifications/end
Automations
- Read
List automations
Returns a list of your automations and associated metadata.
GET /v1/campaigns - Read
Get an automation
Returns metadata for an individual automation.
GET /v1/campaigns/{campaign_id} - Read
Get automation metrics
Returns metrics for an individual automation as a series of counts, oldest first—the 0-index of any result is the oldest point in the window. **We recommend version 2. Send `version=2`.** It accepts an explicit `start`, `end`, and `res`, reported in the `tz` you choose. Without it, the endpoint answers with version 1 behavior instead: a window built from `period` and `steps`, always in Eastern time. Version 1 can't return fewer than 2 steps of any period. `?period=days&steps=1` means two days—the 48 hours before the request—and `?period=days&steps=0` returns the maximum for the period, the same as `?period=days&steps=45`.
GET /v1/campaigns/{campaign_id}/metrics - Read
Get automation link metrics
Returns metrics for link clicks within an automation, 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.
GET /v1/campaigns/{campaign_id}/metrics/links - Read
List automation actions
Returns the operations in an automation workflow. Each object in the response represents an action or 'tile' in the automation builder. This endpoint returns up to 10 `actions` at a time. If there is another page of results, the response will include a `next` string. Pass this string as the `start` parameter to get the next page of results. You get the actions that have content, like messages, attribute updates, and events—not delays or flow control blocks like t/f branches. If a message block contains multiple languages, this endpoint returns an object for each language variant. Each language variant includes the `multi_language_branch_action_id` property with the same value. Use this id to retrieve metrics for each language variant in a single request through [Get automation action metrics](/integrations/api/app/tag/automations/campaignActionMetrics/).
GET /v1/campaigns/{campaign_id}/actions - Read
Get automation message metadata
Returns information about the deliveries (instances of messages sent to individual people) sent from an automation. 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 the most recent 6 months of messages. 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. Timestamps reflect when deliveries were created in our system, not when they were actually sent to recipients. There may be a delay between creation and sending.
GET /v1/campaigns/{campaign_id}/messages - Read
Get an automation action
Returns information about a specific action in an automation.
GET /v1/campaigns/{campaign_id}/actions/{action_id} - Read
Get a translation of an automation message
Returns a translated version of a message in an automation. The message is identified by the `action_id`.
GET /v1/campaigns/{campaign_id}/actions/{action_id}/language/{language} - Read
Get automation action metrics
Returns metrics for an individual action, both in total and as a series of counts, oldest first—the 0-index of any result is the oldest point in the window. **We recommend version 2. Send `version=2`.** It accepts an explicit `start`, `end`, and `res`, reported in the `tz` you choose. Without it, the endpoint answers with version 1 behavior instead: a window built from `period` and `steps`, always in Eastern time. Version 1 can't return fewer than 2 steps of any period. `?period=days&steps=1` means two days—the 48 hours before the request—and `?period=days&steps=0` returns the maximum for the period, the same as `?period=days&steps=45`. **Multi-language messages** If the action is a [multi-language](/messaging/channels/localization/getting-started/) message, you can retrieve metrics for a single language variant or all language variants. To retrieve metrics for a single language variant, pass the `id` of the action. To retrieve aggregate metrics and a breakdown for each language variant, pass the `multi_language_branch_action_id`, which is the same for each variant of a message. You can get both ids from the [List automation actions](/integrations/api/app/tag/automations/listCampaignActions/) endpoint. If you pass the `multi_language_branch_action_id`, then the `metric` object shows the *total* across every variant. The `language_variants` object shows a breakdown for each language variant. If you want to get the sum of all metrics across all of an automation's actions, you can use each action id of a multi-language message, like you would for other types of actions.
GET /v1/campaigns/{campaign_id}/actions/{action_id}/metrics - Read
Get link metrics for an action
Returns link click metrics for an individual action. 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.
GET /v1/campaigns/{campaign_id}/actions/{action_id}/metrics/links - Read
Get automation journey metrics
Returns a list of Journey Metrics for your automation. These metrics show how many people triggered your automation, were messaged, etc for the time period and "resolution" you set. You must provide the `start`, `end`, and `resolution` parameters or your request will return `400`. Metrics in the response are arrays, and each index in the array corresponds to the `resolution` in your request. If you request metrics in `days`, the first result in each metric array is the first day of results and each successive increment represents another day. Each increment represents the number of journeys that started within a time period and eventually achieved a particular metric. For example, array index 0 for the `converted` metric represents the number of journeys that started on the first day/month of results that achieved a conversion.
GET /v1/campaigns/{campaign_id}/journey_metrics - Write
Update an automation action
Update the contents of an automation action, including the body of messages and HTTP requests. **NOTE**: You can't manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](/integrations/api/design-studio/) instead.
PUT /v1/campaigns/{campaign_id}/actions/{action_id} - Write
Update a translation of an automation message
Update the contents of a language variant of an automation action, including the body of the messages and HTTP requests. **NOTE**: You can't manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](/integrations/api/design-studio/) instead.
PUT /v1/campaigns/{campaign_id}/actions/{action_id}/language/{language}
Activities
- Read
List activities
This endpoint returns a list of "activities" for people, similar to your workspace's Activity Logs. This endpoint is guaranteed to return activity history within the past 30 days. It _might_ return data older than 30 days in some circumstances, but activites older than 30 days are not guaranteed.
GET /v1/activities
Assets
- Read
List file assets
Returns a paginated list of file assets. Supports filtering by parent folder and choosing between direct children or the entire folder subtree.
GET /v1/assets - Read
Get a file asset
Retrieves a single file asset by its ID. Returns 404 if the asset does not exist or is a folder.
GET /v1/assets/files/{id} - Read
List folders
Returns a paginated list of asset folders. Supports filtering by parent folder and choosing between direct children or the entire folder subtree.
GET /v1/assets/folders - Read
Get a folder
Retrieves a single folder by its ID.
GET /v1/assets/folders/{id} - Write
Create a file asset
Creates a new file asset. Accepted file types: `image/bmp`, `image/jpeg`, `image/jpg`, `image/png`, `image/gif`, `application/pdf`. Maximum file size: 2 MB. Maximum image dimensions: 4096px.
POST /v1/assets/files - Write
Update a file asset
Updates the name and/or parent folder of a file asset. The file itself (path, size) cannot be changed. At least one of `name` or `parent_folder_id` must be provided.
PUT /v1/assets/files/{id} - Write
Create a folder
Creates a new folder for organizing file assets. Folder names must be unique within the same parent folder.
POST /v1/assets/folders - Write
Update a folder
Updates the name and/or parent folder of an existing folder. At least one of `name` or `parent_folder_id` must be provided. Moving a folder into itself or one of its descendants is not allowed (cycle detection).
PUT /v1/assets/folders/{id} - Destructive
Delete a file asset
Soft-deletes a file asset by setting its `deleted_at` timestamp. The underlying file in cloud storage is not removed. Assets that are currently in use cannot be deleted.
DELETE /v1/assets/files/{id} - Destructive
Delete a folder
Soft-deletes an empty folder. Folders that still contain files or subfolders cannot be deleted. Assets marked as in use also prevent deletion.
DELETE /v1/assets/folders/{id}
Data Index
- Write
Add or update attributes
Attributes are customer data like their name and email. Use this endpoint to add new attributes or update existing attributes in your workspace. To add attributes to customers, use our Pipelines or Track APIs. **NOTE:** If you add new attributes, they will not appear in your [Data Index](/journeys/people/find/using-data-index/) until you've added it to a customer's profile. Add descriptions for attributes [so our AI tools can better understand your data](/ai/cio-with-llms/). For instance, this influences how our segment builder generates conditions with AI. If you're on a Premium plan, you can also specify [whether an attribute is sensitive or not](/accounts/settings/team/intro-account-access/#hide-sensitive-attributes). Then Admins and Workspace Admins can decide which teammates to hide sensitive data from.
POST /v1/data_index/attributes - Write
Add or update events
Events are actions your customers have performed. Use this endpoint to add new events or update existing events in your workspace. To associate events with customers, use our Pipelines or Track APIs. **NOTE:** If you add new events, they will not appear in your [Data Index](/journeys/people/find/using-data-index/) until you've associated it with a customer. Add descriptions for events [so our AI tools can better understand your data](/ai/cio-with-llms/). For instance, this influences how our segment builder generates conditions with AI.
POST /v1/data_index/events
ESP Suppression
- Read
Look up an ESP-suppressed address
Look up an email address to learn if, and why, it was suppressed by the email service provider (ESP).
GET /v1/esp/search_suppression/{email_address} - Read
Get ESP-suppressed emails by type
Find addresses suppressed by the Email Service Provider (ESP) for a particular reason—bounces, blocks, spam reports, or invalid email addresses. You can get up to 1000 addresses per request. Use the `offset` parameter to get addresses beyond the first 1000. If you have multiple sending domains, we recommend querying for each domain separately, as an email address may be suppressed on multiple domains. **Note**: If you have a large number of suppressions, consider using the [Get ESP-suppressed emails by domain](/integrations/api/app/tag/esp-suppression/getDomainSuppressionsByType/) endpoint. It's more performant for large datasets.
GET /v1/esp/suppression/{suppression_type} - Read
Get ESP-suppressed emails by domain
Find addresses suppressed by the Email Service Provider (ESP) for a particular reason on a specific sending domain. You can get up to 1000 addresses per request. Use the `start` parameter with the `next` value from the previous response to paginate through results.
GET /v1/esp/domains/{domain_name}/suppression/{suppression_type} - Write
Suppress an email at the ESP
Suppress an email address at the email service provider (ESP). Addresses suppressed this way are only suppressed through the ESP; these adresses are _not_ suppressed in Customer.io, so the person can remain in your workspace (though emails to the address would be blocked at the ESP).
POST /v1/esp/suppression/{suppression_type}/{email_address} - Destructive
Un-suppress an ESP-suppressed address
Remove an address from the ESP's suppression list.
DELETE /v1/esp/suppression/{suppression_type}/{email_address}
Exports
- Read
List exports
Return a list of your exports. Exports are point-in-time people or automation metrics.
GET /v1/exports - Read
Get an export
Return information about a specific export.
GET /v1/exports/{export_id} - Read
Download an export
This endpoint returns a signed link to download an export. The link expires after 15 minutes.
GET /v1/exports/{export_id}/download - Write
Export customer data
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.
POST /v1/exports/customers - Write
Export information about deliveries
Provide filters for the one-time send, automation, 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. Timestamps reflect when deliveries were created in our system, not when they were actually sent to recipients. There may be a delay between creation and sending.
POST /v1/exports/deliveries
Imports
- Read
Retrieve a bulk import
This endpoint returns information about an "import"—a file of people, events, objects, relationships, or geofences that you uploaded using the `v1/imports` endpoint. You can use this endpoint to check the status of imports, or find out how many rows you successfully imported from a file.
GET /v1/imports/{import_id} - Destructive
Import items in bulk
This endpoint lets you upload a file containing people, events, objects, relationships, or geofences. It provides a handy way of adding and updating them in bulk. Uploading people, objects, or relationships is like performing an [`identify` call](/integrations/api/track/tag/track_v2/entity/) for each row in your CSV; uploading events is like performing a [`track` call](/integrations/api/track/tag/track-events/track/). Uploading geofences adds or updates them in a geofence set, the same way an import in the UI does. Geofence imports are available on Premium and Enterprise plans. You'll need to provide us the public URL of your file as a part of this operation. We recommend that you host your files 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 file requirements based on what you're importing: [people](/journeys/people/uploading-people/#csv-requirements), [events](/journeys/people/uploading-people/#event-csv-requirements), [objects or relationships](/journeys/objects-data/objects/import-objects/#csv-requirements), and [geofences](/messaging/people/location/import-geofences/). This endpoint performs some basic validation on the request and then queues the import for processing. The import happens in multiple stages after your request, and may even fail. You'll need to [lookup the status of the import](/integrations/api/app/tag/imports/getImport/) to check on its progress. Records in your file might result in errors or warnings during the import. We make the errors and warnings available in CSV files that you can download via our export endpoints. [Lookup your import](/integrations/api/app/tag/imports/getImport/) to get download URLs for error and warning reports.
POST /v1/imports
Info
- Read
List IP addresses
Returns a list of IP addresses that you need to allowlist if you're using a firewall or [Custom SMTP](/journeys/channels/email/deliverability/custom-smtp/use-your-smtp-server) 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.
GET /v1/info/ip_addresses
Messages
- Read
List messages
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. Timestamps reflect when deliveries were created in our system, not when they were actually sent to recipients. There may be a delay between creation and sending.
GET /v1/messages - Read
Get a message
Return a information about, and metrics for, a delivery—the instance of a message intended for an individual recipient person.
GET /v1/messages/{message_id} - Read
Get an archived message
Returns the archived copy of a delivery, including the message body, recipient, and metrics. This endpoint is limited to 100 requests per day.
GET /v1/messages/{message_id}/archived_message
Newsletters
- Read
List one-time sends
Returns a list of your one-time sends (referred to as "newsletters" in our APIs) and associated metadata.
GET /v1/newsletters - Read
Get a one-time send
Returns metadata for an individual one-time send (referred to as a "newsletter" in our APIs).
GET /v1/newsletters/{newsletter_id} - Write
Create and send a one-time send
Create a one-time send (referred to as a "newsletter" in our APIs) and optionally schedule it or send it immediately. Set the audience with either `recipients` (a filter over segments and profile attributes) or `recipient_file_url` (a CSV of recipients). One of the two is required, and a request carrying both is rejected. To send it immediately, set `send_now` to `true`. To schedule for later, set `scheduled_at` to a Unix timestamp in the future. If you don't set either, it's created as a draft. A `recipient_file_url` audience resolves in the background, so you can't send or schedule in the same request. Poll [Get a one-time send](/integrations/api/app/tag/newsletters/getNewsletters/) until `recipient_file_status` is `done`, then call [send](/integrations/api/app/tag/send-messages/sendNewsletter/) or [schedule](/integrations/api/app/tag/send-messages/scheduleNewsletter/). There's no endpoint that updates a one-time send, so `name`, the audience, and `deduped` are fixed once you create it. To change them on a draft, delete it and create a new one. You can still edit content through the [variant endpoints](/integrations/api/app/tag/newsletter-variants/listNewsletterVariants/) until it sends. If you [enabled a subscription center](/journeys/channels/subscriptions/center/#enable-sub-center) in your workspace, `subscription_topic_id` is required. Use the [subscription center endpoint](/integrations/api/app/tag/subscription-center/getTopics/) to find IDs. Use standard HTML/CSS for the `body` of an email; this endpoint can't pull in global style variables or render our Design Studio's component syntax. You can create Design Studio emails through [other endpoints](/integrations/api/design-studio/). All requests must be less than 1 MB.
POST /v1/newsletters - Destructive
Delete a one-time send
Deletes an individual one-time send (referred to as a "newsletter" in our APIs), including content, settings, and metrics. It will be removed from segments, and its templates will no longer show in the Message Library. If it's an in-app message, this cancels any undelivered, in-app message, too.
DELETE /v1/newsletters/{newsletter_id}
Newsletter Metrics
- Read
Get one-time send metrics
Returns a list of metrics for an individual one-time send (referred to as a "newsletter" in our APIs) 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.
GET /v1/newsletters/{newsletter_id}/metrics - Read
Get click metrics for one-time send links
Returns metrics for link clicks within a one-time send (referred to as a "newsletter" in our APIs), 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.
GET /v1/newsletters/{newsletter_id}/metrics/links - Read
Get delivery data for a one-time send
Returns information about the "deliveries" (rendered messages) sent to your recipients for a specific one-time send (referred to as a "newsletter" in our APIs). Provide query parameters to refine the metrics you want to return. Use `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 one-time send. 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. Timestamps reflect when deliveries were created in our system, not when they were actually sent to recipients. There may be a delay between creation and sending.
GET /v1/newsletters/{newsletter_id}/messages - Read
Get metrics for a test or translation variant of a one-time send
Returns a metrics for an individual one-time send (referred to as a "newsletter" in our APIs) variant—either an individual language in a multi-language one-time send 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.
GET /v1/newsletters/{newsletter_id}/contents/{content_id}/metrics - Read
Get click metrics for links in one-time send variants
Returns link click metrics for an individual one-time send (referred to as a "newsletter" in our APIs) variant—an individual language in a multi-language one-time send 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.
GET /v1/newsletters/{newsletter_id}/contents/{content_id}/metrics/links
Newsletter Variants
- Read
List one-time send variants
Returns a one-time send's content variants (a one-time send is referred to as a "newsletter" in our APIs)—these are either different languages in a multi-language one-time send or A/B tests.
GET /v1/newsletters/{newsletter_id}/contents - Read
Get a one-time send variant
Returns information about a specific variant of a one-time send (referred to as a "newsletter" in our APIs), where a variant is either a language in a multi-language one-time send or a part of an A/B test.
GET /v1/newsletters/{newsletter_id}/contents/{content_id} - Read
Get a one-time send translation
Returns information about a specific language variant of a one-time send (referred to as a "newsletter" in our APIs). If it includes A/B tests, use [Get a translation in a one-time send test group](/integrations/api/app/tag/newsletter-variants/getNewsletterVariantTranslationTest/).
GET /v1/newsletters/{newsletter_id}/language/{language} - Read
List a one-time send's A/B test groups
Returns information about each test group in a one-time send (referred to as a "newsletter" in our APIs), including content ids for each group.
GET /v1/newsletters/{newsletter_id}/test_groups - Read
Get a translation in a one-time send test group
Returns information about a specific language variant of a one-time send (referred to as a "newsletter" in our APIs) in an A/B test group. You can retrieve `test_group_ids` from [List a one-time send's A/B test groups](/integrations/api/app/tag/newsletter-variants/getNewsletterTestGroups/).
GET /v1/newsletters/{newsletter_id}/test_group/{test_group_id}/language/{language} - Write
Update a one-time send variant
Update the content of a one-time send (referred to as a "newsletter" in our APIs): the default message, a test variant in an A/B test group, or a translation. For an email, you can also update the envelope: from address, subject line, etc. **NOTE**: You cannot manage content made with the drag-and-drop editor via API, and you cannot use this endpoint to update Design Studio emails. You can, however, [manage Design Studio content with other endpoints](/integrations/api/design-studio/). You also can't update in-app or inbox message content through the API—use the message editor instead.
PUT /v1/newsletters/{newsletter_id}/contents/{content_id} - Write
Add a translation to a one-time send
Add a language variant to a one-time send (referred to as a "newsletter" in our APIs). If you omit optional fields, the values from the default template are copied over untranslated. Make sure you translate all aspects of your default template. You can't add language variants to a one-time send that has already been sent. You can't manage emails created with the drag-and-drop editor or Design Studio via this endpoint—use [Create an email translation](/integrations/api/design-studio/tag/emails/createEmailTranslation/) for Design Studio emails. If it has A/B tests, use [Add a translation to a one-time send test group](/integrations/api/app/tag/newsletter-variants/createNewsletterTestLanguageVariant/) instead.
POST /v1/newsletters/{newsletter_id}/language - Write
Update a translation of a one-time send
Update the translation of a one-time send (referred to as a "newsletter" in our APIs) variant. If it includes A/B tests, use [Update a translation in a one-time send test group](/integrations/api/app/tag/newsletter-variants/updateNewsletterTestTranslation/). **NOTE**: You cannot manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](/integrations/api/design-studio/) instead. You also can't update in-app or inbox message content through the API—change it in the message editor.
PUT /v1/newsletters/{newsletter_id}/language/{language} - Write
Create an A/B test group for a one-time send
Create a new A/B test group for a one-time send (referred to as a "newsletter" in our APIs). This duplicates the existing one-time send's content into a new test group, allowing you to test different versions of your message. This endpoint does not require a request body. The new test group is created as a copy of the existing content. You cannot add test groups to a one-time send that has already been sent.
POST /v1/newsletters/{newsletter_id}/test_groups - Write
Add a translation to a one-time send test group
Add a language variant to a specific A/B test group in a one-time send (referred to as a "newsletter" in our APIs). The new variant is a copy of the default template in the test group with the content you provide. The payload the endpoint accepts depends on the parent one-time send's channel type: if it's an email, the payload will be an email variant; if it's an SMS, the payload will be an SMS variant. You cannot add language variants to a one-time send that has already been sent, or to one-time sends created with the drag-and-drop editor or Design Studio.
POST /v1/newsletters/{newsletter_id}/test_group/{test_group_id}/language - Write
Update a translation in a one-time send test group
Update the translation of a one-time send (referred to as a "newsletter" in our APIs) variant in an A/B test. You can retrieve a list of `test_group_ids` from [List a one-time send's A/B test groups](/integrations/api/app/tag/newsletter-variants/getNewsletterTestGroups/). **NOTE**: You cannot manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](/integrations/api/design-studio/) instead. You also can't update in-app or inbox message content through the API—change it in the message editor.
PUT /v1/newsletters/{newsletter_id}/test_group/{test_group_id}/language/{language} - Destructive
Delete a translation of a one-time send
Delete a specific language variant of a one-time send (referred to as a "newsletter" in our APIs). You cannot delete the default language variant. If it has already been sent, you cannot delete language variants. If it includes A/B tests, use [Delete a translation in a one-time send test group](/integrations/api/app/tag/newsletter-variants/deleteNewsletterTestLanguageVariant/).
DELETE /v1/newsletters/{newsletter_id}/language/{language} - Destructive
Delete a translation in a one-time send test group
Delete a specific language variant of a one-time send (referred to as a "newsletter" in our APIs) in an A/B test group. You cannot delete the default language variant. If it has already been sent, you cannot delete language variants. You can retrieve a list of `test_group_ids` from [List A/B test groups in a one-time send](/integrations/api/app/tag/newsletter-variants/getNewsletterTestGroups/).
DELETE /v1/newsletters/{newsletter_id}/test_group/{test_group_id}/language/{language}
Objects
- Read
List object types
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.
GET /v1/object_types - Read
Get Object Relationships
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.
GET /v1/objects/{object_type_id}/{object_id}/relationships - Read
Get Object Attributes
Get a list of attributes for an object. Attributes are things you know about an object—like an account name, billing date, etc.
GET /v1/objects/{object_type_id}/{object_id}/attributes - Write
Find objects
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.
POST /v1/objects
Opt-outs
- Read
List opt-outs in the workspace
Return a workspace-wide list of opt-outs across all channels. Each entry represents a person and the senders/channels (SMS or WhatsApp) they've opted out of. A person opts out of a specific sender on a specific channel—for example, a person can opt out of SMS messages from one sender number while continuing to receive messages from another. An entry's presence in the `optouts` array means the person is opted out of that sender/channel. Use the `from` parameter to filter for a specific sender. Use the `start` parameter with the `next` value from the previous response to paginate through results. **Note**: SMS sender values are stored normalized (trimmed and lowercased). For alphanumeric SMS senders and messaging-service SIDs, the response recovers the original casing from your workspace's Twilio sender identities. E.164 phone numbers are unaffected.
GET /v1/optouts - Read
Lookup a customer's opt-outs
Return a list of the senders and channels that a person has opted out of, across all channels. An entry's presence in the `optouts` array means the person is opted out of that sender/channel. Use the [`PUT /v1/customers/{customer_id}/optouts`](/integrations/api/app/tag/opt-outs/updatePersonOptouts/) endpoint to opt a person out of, or back in to, specific senders.
GET /v1/customers/{customer_id}/optouts - Write
Update a customer's opt-outs
Opt a person out of, or back in to, specific senders and channels. Provide one entry per sender/channel in the `optouts` array. Set `optout` to `true` to opt the person out of a sender, or `false` to opt them back in. The `channel` field is optional and defaults to `sms`. This request is processed asynchronously; it may take a moment for changes to reflect in read requests. Customer.io also writes a [consent record](/messaging/channels/subscriptions/consent-records/) for each entry, with the collection point `api`.
PUT /v1/customers/{customer_id}/optouts
Reporting Webhooks
- Read
List reporting webhooks
Return a list of all of your reporting webhooks
GET /v1/reporting_webhooks - Read
Get a reporting webhook
Returns information about a specific reporting webhook.
GET /v1/reporting_webhooks/{webhook_id} - Write
Create a reporting webhook
Create a new webhook configuration.
POST /v1/reporting_webhooks - Write
Update a webhook configuration
Update the configuration of a reporting webhook. Turn events on or off, change the webhook URL, etc.
PUT /v1/reporting_webhooks/{webhook_id} - Destructive
Delete a reporting webhook
Delete a reporting webhook's configuration.
DELETE /v1/reporting_webhooks/{webhook_id}
Segments
- Read
List segments
Retrieve a list of your segments. The list doesn't include [archived segments](/messaging/segmentation/segments/#archive-unarchive-a-segment).
GET /v1/segments - Read
Get a segment
Return information about a segment.
GET /v1/segments/{segment_id} - Read
Get a segment's dependencies
Use this endpoint to find out which automations and one-time sends use a segment.
GET /v1/segments/{segment_id}/used_by - Read
Get a segment customer count
Returns the membership count for a segment.
GET /v1/segments/{segment_id}/customer_count - Read
List customers in 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](/accounts/workspaces#migrate-workspace) 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.
GET /v1/segments/{segment_id}/membership - Write
Create a manual segment
Create a manual segment with a name and a description. This request creates an empty segment. You can't create a data-driven or snapshot segment with this endpoint.
POST /v1/segments - Destructive
Delete a segment
Delete a manual segment. You can't delete a data-driven or snapshot segment with this request. You also can't delete a manual segment used in another segment, an automation, an unsent one-time send, or a SQL import.
DELETE /v1/segments/{segment_id}
Sender Identities
- Read
List sender identities
Returns a list of senders in your workspace. Senders are who your messages are "from".
GET /v1/sender_identities - Read
Get a sender
Returns information about a specific sender.
GET /v1/sender_identities/{sender_id} - Read
Get sender usage data
Returns lists of the automations and one-time sends that use a sender.
GET /v1/sender_identities/{sender_id}/used_by
Snippets
- Read
List snippets
Returns a list of snippets in your workspace. Snippets are pieces of reusable content, like a common footer for your emails.
GET /v1/snippets - Write
Create a snippet
Create a new snippet. If a snippet with that name already exists, we'll return a `422` error. If the value contains Liquid, we validate it.
POST /v1/snippets - Write
Update snippets
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.
PUT /v1/snippets - Destructive
Delete a 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.
DELETE /v1/snippets/{snippet_name}
Subscription Center
- Read
List subscription topics
Returns a list of subscription topics in your workspace. If there are no topics, it returns an empty array.
GET /v1/subscription_topics - Read
Generate a subscription center token
Generates a signed token and URL for a person's standalone subscription center page. The token is valid for 24 hours. Use the returned `url` to link people to a hosted subscription center page where they can manage their subscription preferences outside of a message. This is useful when you want to provide a direct link to the subscription center—for example, in your app's account settings or in a custom email. The `customer_id` path parameter is the person's identifier (e.g. an email address or customer ID) as it appears in Customer.io. The identifier must match an existing person in your workspace.
GET /v1/subscription_center/{customer_id}/token - Read
List subscription channels
Returns a list of subscription channels available in your workspace. Channels represent the delivery methods that people can subscribe to or unsubscribe from—email, SMS, push, etc. If you haven't set up channel options in your subscription center, this endpoint returns an empty array.
GET /v1/subscription_channels
Transactional
- Read
List transactional messages
Returns a list of your transactional messages—the transactional IDs that you use to trigger an individual transactional delivery. This endpoint does not return information about deliveries (instances of a message sent to a person) themselves.
GET /v1/transactional - Read
Get a transactional message
Returns information about an individual transactional message.
GET /v1/transactional/{transactional_id} - Read
List all variants of a transactional message
Returns the content variants of a transactional message, where each variant represents a different language.
GET /v1/transactional/{transactional_id}/contents - Read
Get a translation of a transactional by ID
Returns an individual translation variant of a transactional message, including the message content. To look up a translation by its language instead of its id, see [Get a translation of a transactional message](/integrations/api/app/tag/transactional/getTransactionalVariant/).
GET /v1/transactional/{transactional_id}/contents/{content_id} - Read
Get a translation of a transactional message
Returns information about a translation of an individual transactional message, including the message content. To look up a translation by its id instead of its language, see [Get a translation of a transactional by ID](/integrations/api/app/tag/transactional/getTransactionalTranslationById/).
GET /v1/transactional/{transactional_id}/language/{language} - Read
Get transactional message metrics
Returns a list of metrics for a transactional message 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.
GET /v1/transactional/{transactional_id}/metrics - Read
Get transactional message link metrics
Returns metrics for clicked links from a transactional message, 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.
GET /v1/transactional/{transactional_id}/metrics/links - Read
Get transactional message deliveries
Returns information about the deliveries (instances of messages sent to individual people) from a transactional message. 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 the most recent 6 months of messages. 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. Timestamps reflect when deliveries were created in our system, not when they were actually sent to recipients. There may be a delay between creation and sending.
GET /v1/transactional/{transactional_id}/messages - Destructive
Update a transactional message
Update the body of a transactional email. This fully overwrites your existing transactional message. We'll use your updated content for any future transactional requests (`/v1/send/email`), so make sure that you test your message before you update it. **NOTE**: You cannot manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](/integrations/api/design-studio/) instead.
PUT /v1/transactional/{transactional_id}/content/{content_id} - Destructive
Update a translation of a transactional message
Update the body and other data of a specific language variant for a transactional message. This fully overwrites this specific translation of your existing transactional message. **NOTE**: You cannot manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](/integrations/api/design-studio/) instead.
PUT /v1/transactional/{transactional_id}/language/{language}
Workspaces
- Read
List workspaces
Returns a list of workspaces in your account.
GET /v1/workspaces
Collections
- Read
List your collections
Returns a list of all of your collections, including the `name` and `schema` for each collection.
GET /v1/collections - Read
Lookup a collection
Retrieves details about a collection, including the `schema` and `name`. This request does not include the `content` of the collection (the values associated with keys in the schema).
GET /v1/collections/{collection_id} - Read
Lookup collection contents
Retrieve the contents of a collection (the `data` from when you created or updated a collection). Each `row` in the collection is represented as a JSON blob in the response.
GET /v1/collections/{collection_id}/content - Write
Create a collection
Create a new collection and provide the `data` that you'll access from the collection or the `url` that you'll download CSV or JSON data from. **Note**: A collection cannot be more than 10 MB in size. No individual row in the collection can be more than 10 KB.
POST /v1/collections - Destructive
Delete a collection
Remove a collection and associated contents. Before you delete a collection, make sure that you aren't referencing it in active automation messages or broadcasts; references to a deleted collection will appear empty and may prevent your messages from making sense to your audience.
DELETE /v1/collections/{collection_id} - Destructive
Update a collection
Update the `name` or replace the contents of a collection. Updating the `data` or `url` for your collection fully replaces the contents of the collection. **Note**: * If you reference your collection by name in active automation messages, changing the name of the collection will cause references to the previous name to return an empty data set. * A collection cannot be more than 10 MB in size. No individual row in the collection can be more than 10 KB.
PUT /v1/collections/{collection_id} - Destructive
Update the contents of a collection
Replace the contents of a collection (the `data` from when you created or updated a collection). The request is a free-form object containing the keys you want to reference from the collection and the corresponding values. This request replaces the current contents of the collection entirely. If you don't want to update the contents directly—you want to change the `name` or data `url` for your collection, use the [update a collection](/integrations/api/app/tag/collections/updateCollection/) endpoint. **Note**: A collection cannot be more than 10 MB in size. No individual row in the collection can be more than 10 KB.
PUT /v1/collections/{collection_id}/content
Customers
- Read
Get customers by email
Return a list of people in your workspace matching an email address. If the email contains special characters like `+`, make sure you [percent-encode](/integrations/api/customerio-apis/#url-encoding) them in the query parameter. For example, use `jane%2Bnotifications%40example.com` instead of `jane+notifications@example.com`. Unencoded special characters can return empty results without an error.
GET /v1/customers - Read
Lookup a customer's attributes
Return a list of attributes for a customer profile. You can use attributes to fashion segments or as liquid merge fields in your messages.
GET /v1/customers/{customer_id}/attributes - Read
Lookup a customer's relationships
Return a list of objects that a person is related to. 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.
GET /v1/customers/{customer_id}/relationships - Read
Lookup a customer's segments
Returns a list of segments that a customer profile belongs to.
GET /v1/customers/{customer_id}/segments - Read
Lookup messages sent to a customer
Returns information about the deliveries sent to a person. Provide query parameters to refine the data 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 the most recent 6 months of messages. If your `start_ts` and `end_ts` range is more than 6 months, we'll return 6 months of data from the most recent timestamp in your request. Timestamps reflect when deliveries were created in our system, not when they were actually sent to recipients. There may be a delay between creation and sending.
GET /v1/customers/{customer_id}/messages - Read
Lookup a customer's activities
Return a list of activities performed by, or for, a customer. Activities are things like attribute changes and message sends. This endpoint is guaranteed to return activity history within the past 30 days. It might return data older than 30 days in some circumstances, but activites older than 30 days are not guaranteed.
GET /v1/customers/{customer_id}/activities - Read
Lookup a customer's subscription preferences
Returns a list of subscription preferences for a person, including the custom header of the subscription preferences page, topic names, and topic descriptions. Returns translated data when you send a language in the query.
GET /v1/customers/{customer_id}/subscription_preferences - Write
Search for customers
Provide a filter to search for people in your workspace. Your filter can filter people by segment (using the Segment ID) and attribute values; when you filter by attributes, you can use `eq` (matching an attribute value) or `exists` (matching when a person has the attribute). Use the `and` array, `or` array, and `not` object to create a complex filter. The `not` selector is an object that takes a single filter. Returns arrays of `identifiers` and `ids`. In general, you should rely on the newer `identifiers` array, which contains more complete information about each person captured by the filter in your request, than the `ids` array, which only contains `id` values. You can return up to 1000 people per request. If you want to return a larger set of people in a single request, you may want to use the [`/exports`](/integrations/api/app/tag/exports/) API instead.
POST /v1/customers - Write
List customers, attributes, and devices
Return attributes and devices for up to 100 customers by ID. If an ID in the request does not exist, the response omits it.
POST /v1/customers/attributes
Folders
- Read
List folders
Returns a paginated list of folders. This does not include files like emails, components, etc.
GET /v1/design_studio/folders - Read
Get a folder
Get a folder by its UUID. You can retrieve the UUID of folders through [List folders](/integrations/api/design-studio/tag/folders/listFolders/).
GET /v1/design_studio/folders/{id} - Write
Create a folder
Create a new folder at the root level or under a parent folder. To create a child folder, you need the UUID of the parent folder, which you can retrieve with [List folders](/integrations/api/design-studio/tag/folders/listFolders/).
POST /v1/design_studio/folders - Write
Update a folder
Update part of a folder: the name and/or the folder it belongs to. If you move a folder, all files stay nested in the folder.
PUT /v1/design_studio/folders/{id} - Destructive
Delete a folder
Delete a folder **including subfolders and all file (components, templates, and emails)**. You cannot delete a folder with emails used in your workflows (automations, broadcasts, etc). However, you can delete a folder with components that are referenced in emails linked to workflows, so make sure deleting a folder with components won't break your emails.
DELETE /v1/design_studio/folders/{id}
Emails
- Read
List emails
Returns a paginated list of emails and a separate array of folders that the emails belong to.
GET /v1/design_studio/emails - Read
Get an email
Returns a single email including content, envelope details, and transformers. This endpoint returns only default emails; see [Email translations](/integrations/api/design-studio/tag/emails/createEmailTranslation/) to access language variants.
GET /v1/design_studio/emails/{id} - Read
List email translations
Returns all translations for an email. Each translation contains the email's content, envelope, and transformers for a specific language.
GET /v1/design_studio/emails/{id}/languages - Read
Get an email translation
Returns a single email translation by language code, including content, envelope, and transformers.
GET /v1/design_studio/emails/{id}/languages/{language} - Read
List email versions
Returns an email's saved versions, newest first. A version is a named checkpoint of the email's content and envelope. - Design Studio creates a version automatically every time you [publish](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/) the email. - You can save a version manually with [Save an email version](/integrations/api/design-studio/tag/emails/saveVersion/). Pass `start_date` to filter for versions created after a certain time. Or pass `start_date` and `end_date` together to filter for versions created in a certain time range. You can retrieve your email's UUID through [List emails](/integrations/api/design-studio/tag/emails/listEmails/). If your email has language variants, *List emails* only returns the UUID for the default language. Use this default ID to retrieve variant IDs through [List email translations](/integrations/api/design-studio/tag/emails/listEmailTranslations/).
GET /v1/design_studio/emails/{id}/versions - Read
Get an email version
Returns a snapshot of the version's content including the code for any custom components referenced in the email (see `dependencies` for more).
GET /v1/design_studio/emails/{id}/versions/{version_id} - Write
Create an email
Create an email. Note, you can create an email without filling out all required fields for sending. You can fill in the envelope, like a to and from address, with this method, but that's not required until you link it to a workflow like an automation.
POST /v1/design_studio/emails - Write
Update an email
Update part of an email: an email's name, template status, folder, content, envelope, or transformers. Note, this does not publish your email; if the email is linked to a workflow like an automation, you still need to click publish to make the changes live.
PUT /v1/design_studio/emails/{id} - Write
Create an email translation
Creates a new translation for an email. If content, envelope, and/or transformers are omitted, the values are copied from the default (parent) email.
POST /v1/design_studio/emails/{id}/languages - Write
Update an email translation
Update part of an email translation: the content, envelope, or transformers for a specific email translation. Note, this does not publish your email; if the email is linked to a workflow like an automation, you still need to click publish to make the changes live.
PUT /v1/design_studio/emails/{id}/languages/{language} - Write
Save an email version
Saves a version of the email's current content, envelope, and any component dependencies it references. If you need to revert to a previous version, use [Restore an email version](/integrations/api/design-studio/tag/emails/restoreVersion/). If the email is identical to the most recent version, this returns that version with `"created": false` instead of saving a duplicate. If the code of a referenced custom component changes, you can save a new version of the email with the latest component changes; however, the code diff in Design Studio will show no change because the component code isn't compiled in that view.
POST /v1/design_studio/emails/{id}/versions - Destructive
Delete an email
Delete an email. You cannot delete an email that is linked to a workflow (automation, broadcast, etc). This deletes the email and all translations.
DELETE /v1/design_studio/emails/{id} - Destructive
Delete an email translation
Delete a specific language translation from an email. This fails if the email is linked to a workflow (automation, broadcast, etc).
DELETE /v1/design_studio/emails/{id}/languages/{language} - Destructive
Delete an email version
Deletes a version. You can't delete a version that Design Studio created automatically during a publish.
DELETE /v1/design_studio/emails/{id}/versions/{version_id} - Destructive
Restore an email version
Returns the email to a saved version. This restores only the email itself; if the code for a referenced custom component changed since this version was saved, the latest component code renders in Design Studio, not the original. This only edits the draft in Design Studio. If you already linked the email to a workflow, you need to [publish it](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/) to push the restored content live.
POST /v1/design_studio/emails/{id}/versions/{version_id}/restore
Email link and publish
- Read
Get publish status
Check the status of a multi-language publish that returned `"status": "pending"`. Pass the `publish_id` from the [Publish an email](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/) response. When the publish is still running, the response returns `"status": "pending"`; when it finishes, it returns `"status": "done"` with the template version mappings. If the publish fails, this endpoint returns an error rather than a status. You get the same error a single-language publish returns inline—a `422` for liquid errors, a `409` when the destination automation is backfilling, and so on.
GET /v1/design_studio/emails/{id}/publish_status - Read
Check for unpublished changes
Check whether a linked email, or any of its translations, has content changes that haven't been published yet. Use this to decide whether you need to publish before changes go live. Returns `false` for emails that aren't linked to a workflow or that have no pending changes.
GET /v1/design_studio/emails/{id}/unpublished_changes - Write
Publish an email
Publish a linked Design Studio email. This pushes its current content to the workflow it's linked to. You must link an email to a workflow before you can publish it. Publishing pushes updates to all language variants: the default language and all of the translations. For a single-language email, the publish runs inline and returns `"status": "done"` with the resulting template version mappings. For a multi-language email, the publish may take longer; if it doesn't finish within the request window, the response returns `"status": "pending"` along with a `publish_id` you can poll with [Get publish status](/integrations/api/design-studio/tag/email-email-link-and-publish/getPublishStatus/).
POST /v1/design_studio/emails/{id}/publish - Destructive
Link an email to a workflow
Link a Design Studio email to a workflow: a transactional message, a one-time send, an automation, or an API-triggered broadcast. After you link an email, [publish it](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/) to push the content live. You can only link an email to one workflow or action at a time. If the workflow or action is already linked to a *different* Design Studio email, the request fails with a `409` unless you pass `"force": true`, which replaces (and unlinks) the other email.
POST /v1/design_studio/emails/{id}/link
Email testing
- Read
Render an email
Returns email-ready HTML. Use this endpoint to inspect your compiled markup. Liquid tags are left intact—`{{customer.first_name}}` stays in the output as written. To evaluate liquid against real profile data instead, use [Preview an email](/integrations/api/design-studio/tag/email-testing/previewEmail/). The render, preview, review, link, and publish endpoints share a rate limit of 5 requests per second per workspace.
GET /v1/design_studio/emails/{id}/render - Read
Review an email
Checks an email's saved content for errors and suggests how to improve accessibility, styling, and more. This runs the same process as the [*Review* panel in Design Studio](/messaging/design-studio/emails/qa-in-design-studio/) and returns a readiness score, a status per check, and how to fix issues. This endpoint reviews **a single translation** based on the `:id` you pass. Call this endpoint for each language variant to review each translation. **Checks** - `liquid` — Liquid syntax: broken tags, invalid filters, unclosed blocks. Does not report missing variables; use the [preview endpoint](/integrations/api/design-studio/tag/email-testing/previewEmail/) with sample data to validate variable resolution. - `failed-components` — Custom components that fail to compile. Always `skipped` on the API; it's a browser-runtime-only signal. - `source` — Raw markup the editor stores, before liquid rendering. Checks for reserved internal HTML attributes, multiple root elements, and design-token clashes. - `links` — Broken URLs, validated over HTTP (capped at 100 links per review). - `images` — Broken image URLs and missing alt text (capped at 100 images per review). - `accessibility` — WCAG accessibility issues. - `spam` — SpamAssassin score. - `unsubscribe` — Presence of an unsubscribe link. - `implied-links` — Bare URLs or email addresses that should be wrapped in `<a>` tags. - `html-clip` — Gmail's 102 KB clipping threshold. - `preheader` — Preheader text presence and quality. The render, preview, review, link, and publish endpoints share a rate limit of 5 requests per second per workspace.
GET /v1/design_studio/emails/{id}/review - Read
List inbox preview options
Returns the catalog of email clients and devices available for [inbox previews](/messaging/design-studio/emails/qa-in-design-studio/#inbox-preview). Use the `id` values returned by this endpoint as `client_ids` when you [send for an inbox preview](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/).
GET /v1/design_studio/inbox_previews/clients - Read
Get preview credit balance
Returns your account's credit balance for inbox previews. Your credit balance determines how many previews you can generate in your account. Learn more about [how inbox previews use credits](/accounts/billing/inbox-previews/).
GET /v1/design_studio/inbox_previews/credits - Read
Get an inbox preview job
Returns the status of a preview job submitted with [Send for inbox previews](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/), including each preview's settings.
GET /v1/design_studio/emails/{id}/inbox_previews/{run_id} - Read
Get a preview screenshot
Returns the image bytes for a single preview job, proxied from the vendor. The response's content type matches whatever the vendor sent for that capture, which isn't always PNG, and the `Content-Disposition` filename's extension matches it. You can also use the URL paths in the response of [Get an inbox preview job](/integrations/api/design-studio/tag/email-testing/getInboxPreviewJob/) to complete this request.
GET /v1/design_studio/emails/{id}/inbox_previews/{run_id}/captures/{client_id} - Read
List inbox preview history
Returns a paginated history of inbox preview jobs across your workspace, or for a single email when you pass `node_id`. Only lists runs recent enough for their screenshots to still be viewable—an older run won't appear here even though it still exists.
GET /v1/design_studio/inbox_previews/jobs - Write
Preview an email
Returns an email with liquid fully evaluated against data you provide. The response includes the final HTML as a recipient would see it, along with liquid errors. Omit the body or send `{}` to render your fallback values: a variable with a `default` filter renders its fallback, and each variable without one reports an error in the response's `errors` object. The render, preview, review, link, and publish endpoints share a rate limit of 5 requests per second per workspace.
POST /v1/design_studio/emails/{id}/preview - Write
Send a test email
Sends a test email to a real inbox through your sending domain using the content saved to Design Studio. The test includes the tracking pixel and link parameters a real send would add, so you can see your email as it would appear in an actual email client. To get the rendered HTML back in the API response instead, use [Preview an email](/integrations/api/design-studio/tag/email-testing/previewEmail/). * **If you already linked the email to a workflow**, then keep in mind that what's *saved* to Design Studio may differ from what's *published* to the linked workflow. Make sure you publish your changes when you're ready to push them to your linked workflow. * **If your email has translations**, you have to send this request separately for each language variant. Pass the ID of the specific translation you want to test, which you can retrieve from [List email translations](/integrations/api/design-studio/tag/emails/listEmailTranslations/). * **If the email contains liquid variables**, you can provide sample data in the request body to check how the liquid renders. Without sample data, the send still succeeds, but each variable renders as an empty string and the response includes a warning. A variable with a fallback filter like `default` renders its fallback instead. A liquid syntax error, like a missing close tag, always fails the request. Your account has a set number of test emails you can send per day. This endpoint counts towards that quota. Learn more in [Plan features](/accounts/billing/plan-features/#general-features).
POST /v1/design_studio/emails/{id}/test_send - Write
Send for inbox previews
Initiate one or more inbox previews for an email. This uses inbox preview credits; check your balance with [Get preview credit balance](/integrations/api/design-studio/tag/email-testing/getInboxPreviewCredits/). [**Learn how billing for inbox previews work before you call this endpoint.**](/accounts/billing/inbox-previews/) Use [List emails](/integrations/api/design-studio/tag/emails/listEmails/) to get your email's ID. If the email has translations, call [List email translations](/integrations/api/design-studio/tag/emails/listEmailTranslations/) to get the ID of the language variant you want a preview of. You can retrieve client IDs from [List inbox preview options](/integrations/api/design-studio/tag/email-testing/listInboxPreviewClients/). This call does not return the preview file. It returns a `run_id`; poll [Get an inbox preview job](/integrations/api/design-studio/tag/email-testing/getInboxPreviewJob/) with it, then fetch each tile's capture URL from that response. Submitting the same email, content, and devices again on the same UTC day returns the existing run instead of starting a new one, with `replayed` set to `true` and no second charge. The same happens the next day if that run is still processing, or if a concurrent identical request gets there first. Resubmitting a stuck run is safe and free—it hands you the same run back rather than starting a second one.
POST /v1/design_studio/emails/{id}/inbox_previews
SMS
- Read
List SMS
Returns a paginated list of your SMS messages and a separate array of the folders they belong to. Each item in the list is a summary; to see an SMS's content, recipient, and sender, [get the SMS](/integrations/api/design-studio/tag/sms/getSms/).
GET /v1/design_studio/sms - Read
Get an SMS
Returns a single SMS, including its content, recipient, and sender.
GET /v1/design_studio/sms/{id} - Write
Create an SMS
This endpoint creates an SMS message in Design Studio. After you create an SMS, [link it](/integrations/api/design-studio/tag/sms-link-and-publish/linkSms/) to a workflow. If you make updates after linking the message, make sure you [publish changes](/integrations/api/design-studio/tag/sms-link-and-publish/publishSms/) to send the latest content to your audience. Not all accounts are set up to create SMS through Design Studio. [Learn more about your options](/integrations/api/design-studio/tag/sms/).
POST /v1/design_studio/sms - Destructive
Update an SMS
Update an SMS's name, folder, content, recipient, or sender. You only need to send the fields you want to change; Customer.io keeps the current value of any field you leave out. If the SMS is linked to a workflow, you need to [publish your changes](/integrations/api/design-studio/tag/sms-link-and-publish/publishSms/) so your audience receives the latest content.
PUT /v1/design_studio/sms/{id} - Destructive
Delete an SMS
Delete an SMS. You can't delete an SMS that's linked to a workflow, like a transactional message, a one-time send, or an automation action.
DELETE /v1/design_studio/sms/{id}
SMS link and publish
- Write
Publish an SMS
If you made changes to a [linked SMS message](/integrations/api/design-studio/tag/sms-link-and-publish/linkSms/), you need to publish the SMS when you're ready so your workflows send the latest content.
POST /v1/design_studio/sms/{id}/publish - Destructive
Link an SMS to a workflow
Link an existing SMS to a workflow—a transactional message, a one-time send, an automation action, or an API-triggered broadcast—to send it to your audience. If your workflow is already live, people start receiving this SMS as soon as you link it. If you make changes to the message after linking it, you need to [publish the SMS](/integrations/api/design-studio/tag/sms-link-and-publish/publishSms/) to send the latest content to your audience. You can only link an SMS to one workflow at a time. If you try to link an SMS to a workflow or action that's already linked to a *different* message, the request fails with a `409` unless you pass `"force": true`. The `force` parameter replaces (and unlinks) the other message.
POST /v1/design_studio/sms/{id}/link
- Read
List WhatsApp templates
Returns a paginated list of the WhatsApp templates you made in Design Studio and a separate array of the folders they belong to. Each item in the list is a summary that includes the template's Meta approval status. To see a template's content, category, language, recipient, and sender, [get the template](/integrations/api/design-studio/tag/whatsapp/getWhatsApp/). The list doesn't include templates you created in your Meta account outside of Design Studio.
GET /v1/design_studio/whatsapp - Read
Get a WhatsApp template
Returns a single WhatsApp template, including its content, category, language, recipient, sender, and Meta approval status.
GET /v1/design_studio/whatsapp/{id} - Write
Create a WhatsApp template
This endpoint creates a WhatsApp template in Design Studio. Creating a template doesn't send anything to Meta. Before you can send the template to your audience, you need to submit it to Meta for approval, and Meta needs to approve it. You write the template's `content` as WhatsApp markup, a set of elements that match the components you can add in Design Studio. See [WhatsApp building blocks](/messaging/design-studio/whatsapp-design-studio/#whatsapp-building-blocks) for every element and the rules the markup follows. Make sure the template's content, category, and language are right before you submit it. After you submit a template, you can't change those fields unless Meta rejects it.
POST /v1/design_studio/whatsapp - Write
Update a WhatsApp template
Update a WhatsApp template's name, folder, category, language, content, recipient, or sender. You only need to send the fields you want to change; Customer.io keeps the current value of any field you leave out. Meta reviews a template's content, category, and language. After you submit the template to Meta, you can't change those three fields unless Meta rejects the template. To change an approved template, create a new template and submit that one instead. You can change the name, folder, recipient, and sender at any time. Renaming a template only changes the name your team sees in Design Studio. It doesn't rename the template you submitted to Meta.
PUT /v1/design_studio/whatsapp/{id} - Destructive
Delete a WhatsApp template
Delete a WhatsApp template from Design Studio. You can't delete a template that's linked to a workflow, like a transactional message, a one-time send, or an automation action. Deleting a template in Customer.io doesn't delete the template you submitted to Meta. If you want to remove it from your WhatsApp Business Account too, delete it in WhatsApp Manager.
DELETE /v1/design_studio/whatsapp/{id}
WhatsApp approval
- Read
Get a WhatsApp template's Meta status
Returns a WhatsApp template's Meta approval status. After you [submit a template](/integrations/api/design-studio/tag/whatsapp-approval/submitWhatsApp/), call this endpoint periodically to find out when Meta approves or rejects it. If you haven't submitted the template, the response has `submitted` set to `false` and no other fields. Unlike the `status` on [Get a WhatsApp template](/integrations/api/design-studio/tag/whatsapp/getWhatsApp/), this endpoint returns an error when Customer.io can't look up the status, so an empty response always means you haven't submitted the template.
GET /v1/design_studio/whatsapp/{id}/status - Write
Submit a WhatsApp template to Meta
Submit a WhatsApp template to Meta for approval. Customer.io sends the template's content, category, and language to Meta, which creates a new template in your WhatsApp Business Account. Submitting doesn't change any workflow the template is linked to. To update the workflow, you need to publish the template. You can submit a template once. You can only submit it again if Meta rejects it. Each submission creates a new template in Meta, named after your Design Studio template with a unique suffix. After you submit a template, you can't change its content, category, or language unless Meta rejects it. Meta asks for a sample value for each liquid variable in a template so it can review the message. You can't set samples through the API. If your template contains liquid, add variable samples in Design Studio before you submit it. Meta's review can take some time. Check the template's status to find out when Meta approves or rejects it.
POST /v1/design_studio/whatsapp/{id}/submit
WhatsApp link and publish
- Write
Publish a WhatsApp template
Publish a linked WhatsApp template, pushing its current content, recipient, and sender to the workflow it's linked to. Publishing doesn't send anything to Meta, so you can publish as often as you need to, like after you change the template's recipient or sender. You need to [link the template](/integrations/api/design-studio/tag/whatsapp-link-and-publish/linkWhatsApp/) and [submit it to Meta](/integrations/api/design-studio/tag/whatsapp-approval/submitWhatsApp/) before you can publish it. You can't publish a template that Meta rejected. You can publish a template while Meta is still reviewing it, but your audience might not receive it until Meta approves it. Make sure the template's [status](/integrations/api/design-studio/tag/whatsapp-approval/getWhatsAppStatus/) is `APPROVED` before you start sending.
POST /v1/design_studio/whatsapp/{id}/publish - Destructive
Link a WhatsApp template to a workflow
Link a WhatsApp template to a workflow or action: a transactional message, a one-time send, an automation action, or an API-triggered broadcast. The workflow or action needs to send WhatsApp messages. Linking copies the template's current content, recipient, and sender to the workflow right away. You can link a template before you submit it to Meta. After you submit the template, [publish it](/integrations/api/design-studio/tag/whatsapp-link-and-publish/publishWhatsApp/) to push it to the workflow, and wait until its status is `APPROVED` before you start sending. You can only link a template to one workflow or action at a time. If you try to link a template to a workflow or action that's already linked to a *different* message, the request fails with a `409` unless you pass `"force": true`. The `force` parameter replaces (and unlinks) the other message.
POST /v1/design_studio/whatsapp/{id}/link
Components
- Read
List components
Returns a paginated list of components and any folders in the result set.
GET /v1/design_studio/components - Read
Get a component
Returns a single component with its full content.
GET /v1/design_studio/components/{id} - Write
Create a component
Creates a custom component.
POST /v1/design_studio/components - Write
Update a component
Update part of a component: its name, tag, folder, or content.
PUT /v1/design_studio/components/{id} - Destructive
Delete a component
Delete a component. Note, this deletes any component. If you delete a component in use, the emails that reference it could fail to send.
DELETE /v1/design_studio/components/{id}
No operations match.
See How connections work for access and permissions, or browse all integrations.