Skip to content
Changelog

Report a bug

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>&nbsp;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

    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 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 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 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

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 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

WhatsApp

  • 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}

See How connections work for access and permissions, or browse all integrations.