Customer.io

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.

Returns link click metrics for an individual broadcast action. Unless you specify otherwise, the response contains data for the maximum period by days (45 days). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.

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.

Returns the actions that occur as a part of a broadcast.

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.

Returns metrics for link clicks within a broadcast, both in total and in `series` periods (days, weeks, etc). `series` metrics are ordered oldest to newest (i.e. the 0-index for any result is the oldest step/period). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.

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.

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.

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](/api/app/#operation/listBroadcastTriggers).

Returns link click metrics for an individual action. Unless you specify otherwise, the response contains data for the maximum period by days (45 days). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.

Returns a list of metrics for an individual action. The response format and available parameters depend on the version parameter that you use with this endpoint. **We strongly recommend that you use `version=2`**: **Version 2 (Recommended):** - Uses `res`, `tz`, `start`, and `end` parameters - Based on resolution with flexible time ranges - Returns metrics over a period of time (resolution) from oldest to newest **Version 1 (Deprecated):** - Uses `period` and `steps` parameters - Based on steps (days, weeks, etc) - Returns 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`

Returns a list of Journey Metrics for your campaign. These metrics show how many people triggered your campaign, 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.

Returns metrics for link clicks within a campaign, both in total and in `series` periods (days, weeks, etc). `series` metrics are ordered oldest to newest (i.e. the 0-index for any result is the oldest step/period). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.

Returns a list of metrics for an individual campaign. The available parameters and response format depend on the version parameter that you use with this endpoint. **We strongly recommend that you use `version=2`** with this endpoint: **Version 2 (Recommended):** - Uses `res`, `tz`, `start`, and `end` parameters - Based on resolution and optionally, time zone, start and end times - Provides maximum flexibility for time-based metrics **Version 1 (Deprecated):** - Uses `period` and `steps` parameters - Based on steps (days, weeks, etc) - Returns 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`

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.

Creates a new folder for organizing file assets. Folder names must be unique within the same parent folder.

Creates a custom component.

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 connect it to a workflow like a campaign.

Creates a new translation for an email. If content, envelope, and/or transformers are omitted, the values are copied from the default (parent) email.

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](#tag/design-studio/listFolders).

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

Create a newsletter and optionally schedule it or send it immediately. To send the newsletter 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, the newsletter is created as a draft. 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](#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](#tag/design-studio). All requests must be less than 1 MB.

Add a language variant to a newsletter. 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 newsletter 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](#tag/design-studio/createEmailTranslation) for Design Studio emails. If the newsletter has A/B tests, use [Add a translation to a newsletter test group](#operation/createNewsletterTestLanguageVariant) instead.

Create a new A/B test group for a newsletter. This duplicates the existing newsletter 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 newsletter that has already been sent.

Add a language variant to a specific A/B test group in a newsletter. 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 newsletter's channel type: if the newsletter is an email, the payload will be an email variant; if the newsletter is an SMS, the payload will be an SMS variant. You cannot add language variants to a newsletter that has already been sent, or to newsletters created with the drag-and-drop editor or Design Studio.

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.

Create a new webhook configuration.

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.

Soft-deletes an empty folder. Folders that still contain files or subfolders cannot be deleted. Assets marked as in use also prevent deletion.

Remove a collection and associated contents. Before you delete a collection, make sure that you aren't referencing it in active campaign messages or broadcasts; references to a deleted collection will appear empty and may prevent your messages from making sense to your audience.

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 an email. You cannot delete an email that is linked to a workflow (campaign, broadcast, etc). This deletes the email and all translations.

Delete a specific language translation from an email. This fails if the email is linked to a workflow (campaign, broadcast, etc).

Delete a folder **including subfolders and all file (components, templates, and emails)**. You cannot delete a folder with emails used in your workflows (campaigns, broadcasts, etc). However, you can delete a folder with components that are referenced in emails connected to workflows, so make sure deleting a folder with components won't break your emails.

Delete a manual segment.

Delete a specific language variant of a newsletter. You cannot delete the default language variant. If your newsletter has already been sent, you cannot delete language variants. If your newsletter includes A/B tests, use [Delete a translation in a newsletter test group](#operation/deleteNewsletterTestLanguageVariant).

Delete a specific language variant of a newsletter in an A/B test group. You cannot delete the default language variant. If your newsletter 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 newsletter](#operation/getNewsletterTestGroups).

Deletes an individual newsletter, including content, settings, and metrics. It will be removed from segments, and its templates will no longer show in the Message Library. If the newsletter is an in-app message, this cancels any undelivered, in-app message, too.

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.

Remove an address from the ESP's suppression list.

Delete a reporting webhook's configuration.

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

Provide filters for the newsletter, campaign, or action you want to return delivery information from. This endpoint starts an export, but you cannot download your export from this endpoint. Use the `/exports/{export_id}` endpoint to download your export. Use the `start` and `end` to find messages within a time range. If your request doesn't include `start` and `end` parameters, we'll return the most recent 6 months of messages. If your `start` and `end` range is more than 12 months, we'll return 12 months of data from the most recent timestamp in your request. 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.

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.

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

Retrieves a single file asset by its ID. Returns 404 if the asset does not exist or is a folder.

Retrieves a single folder by its ID.

Returns metadata for an individual broadcast.

Returns information about a specific action within a broadcast.

Returns information about a translation of message in a broadcast. The message is identified by the `action_id`.

Returns information about a specific action in a campaign.

Returns a translated version of a message in a campaign. The message is identified by the `action_id`.

Returns information about the deliveries (instances of messages sent to individual people) sent from a campaign. 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.

Returns metadata for an individual campaign.

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.

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.

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

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.

Returns a list of all of your collections, including the `name` and `schema` for each collection.

Returns a single component with its full content.

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.

Returns a single email including content, envelope details, and transformers. This endpoint returns only default emails; see [Email translations](#tag/design-studio/createEmailTranslation) to access language variants.

Returns a single email translation by language code, including content, envelope, and transformers.

Return information about a specific export.

Get a folder by its UUID. You can retrieve the UUID of folders through [List folders](#tag/design-studio/listFolders).

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

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

Returns metrics for link clicks within a newsletter, both in total and in `series` periods (days, weeks, etc). `series` metrics are ordered oldest to newest (i.e. the 0-index for any result is the oldest step/period). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.

Returns a list of metrics for an individual newsletter in `steps` (days, weeks, etc). We return metrics from oldest to newest (i.e. the 0-index for any result is the oldest step/period). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.

Returns information about the "deliveries" (rendered messages) sent to your recipients for a specific newsletter. 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 newsletter. If your `start_ts` and `end_ts` range is more than 12 months, we'll return 12 months of data from the most recent timestamp in your request. 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.

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

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

Returns information about a specific language variant of a newsletter. If your newsletter includes A/B tests, use [Get a translation in a newsletter test group](/api/app/#operation/getNewsletterVariantTranslationTest).

Returns information about a specific language variant of a newsletter in an A/B test group. You can retrieve `test_group_ids` from [Get variants in a newsletter test group](/api/app/#operation/getNewsletterVariantTest).

Returns metadata for an individual newsletter.

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

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

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

Use a set of filter conditions to find objects in your workspace. Returns a list of object IDs that you can use to look up object attributes, or to create or modify objects. The list is paged if you have a large number of objects. You can set the `limit` for the number of objects returned, and use the `start` to page through the results. It's possible that you'll see duplicate entries across pages. If you want to export objects or relationships, you may want to use the export feature in our UI to return complete results.

Return attributes and devices for up to 100 customers by ID. If an ID in the request does not exist, the response omits it.

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 `[email protected]`. Unencoded special characters can return empty results without an error.

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`](#tag/Exports) API instead.

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.

Return a list of attributes for a customer profile. You can use attributes to fashion segments or as liquid merge fields in your messages.

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.

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.

Returns a list of segments that a customer profile belongs to.

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.

Return information about a segment.

Returns the membership count for a segment.

Use this endpoint to find out which campaigns and newsletters use 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.

Returns information about a specific sender.

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

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.

Look up an email address to learn if, and why, it was suppressed by the email service provider (ESP).

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.

Returns a list of subscription topics in your workspace. If there are no topics, it returns an empty array.

Returns information about an individual transactional message.

Returns information about a translation of an individual transactional message, including the message content.

Returns link click metrics for an individual newsletter variant—an individual language in a multi-language newsletter or a message in an A/B test. Unless you specify otherwise, the response contains data for the maximum period by days (45 days). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.

Returns a metrics for an individual newsletter variant—either an individual language in a multi-language newsletter or a message in an A/B test. This endpoint returns metrics both in total and in `steps` (days, weeks, etc) over a `period` of time. Stepped `series` metrics are arranged from oldest to newest (i.e. the 0-index for any result is the oldest period/step). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.

Returns information about a specific reporting webhook.

This endpoint lets you upload a CSV file containing people, events, objects, or relationships. It provides a handy way of adding and updating them in bulk. Uploading people, objects, or relationships is like performing an [`identify` call](/api/track/#operation/entity) for each row in your CSV; uploading events is like performing a [`track` call](/api/track/#operation/track). You'll need to provide us the public URL of your CSV as a part of this operation. We recommend that you host your CSVs from short-lived URLs. Ideally, your URLs will expire 2 hours after you initiate an import so that your customers' information doesn't remain publicly available after you've uploaded it to us. Check out the CSV requirements based on what you're importing: [people](/journeys/people/uploading-people/#csv-requirements), [events](/journeys/people/uploading-people/#event-csv-requirements), and [objects or relationships](/journeys/objects-data/objects/import-objects/#csv-requirements). 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](#getImport) to check on its progress. Records in your CSV 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](#getImport) to get download URLs for error and warning reports.

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.

Returns a paginated list of asset folders. Supports filtering by parent folder and choosing between direct children or the entire folder subtree.

Returns a paginated list of file assets. Supports filtering by parent folder and choosing between direct children or the entire folder subtree.

Returns a list of the `triggers` for a broadcast.

Returns a list of your API-triggered broadcasts and associated metadata.

Returns the operations in a campaign workflow. Each object in the response represents an action or 'tile' in the campaign 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.

Returns a list of your campaigns and associated metadata.

Returns a paginated list of components and any folders in the result set.

Returns all translations for an email. Each translation contains the email's content, envelope, and transformers for a specific language.

Returns a paginated list of emails and a separate array of folders that the emails belong to.

Return a list of your exports. Exports are point-in-time people or campaign metrics.

Returns a paginated list of folders. This does not include files like emails, components, etc.

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.

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

Returns a list of your newsletters and associated metadata.

Retrieve a list of all of your segments.

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

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

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.

Returns the content variants of a transactional message, where each variant represents a different language.

Return a list of all of your reporting webhooks

Returns a list of workspaces in your account.

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

Schedule a newsletter to send at a specific time. The newsletter must be in a draft state. If the newsletter has already been sent, you'll get a `400` error. If the newsletter is already scheduled, this endpoint updates the scheduled time. The recipients for the newsletter are defined when you create/update the newsletter. If you're not sure who will receive the newsletter, you can use the [List newsletters](/integrations/api/app/#tag/newsletters/listNewsletters) endpoint to get a list of newsletters and their recipients.

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.

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](#tag/Transactional). **Note**: Your workspace must have in-app messaging enabled. Requests sent to a workspace without the in-app capability return `403`.

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](#tag/Transactional). **Note**: Inbox messages are currently available for web platforms only and require the Customer.io In-App Plugin to be installed.

Send a newsletter immediately. The newsletter must be in a draft state. If the newsletter has already been sent, you'll get a `400` error. The recipients for the newsletter are defined when you create/update the newsletter. If you're not sure who will receive the newsletter, you can use the [List newsletters](/integrations/api/app/#tag/newsletters/listNewsletters) endpoint to get a list of newsletters and their recipients. To reschedule a newsletter, use the [Schedule a newsletter](#tag/send-messages/scheduleNewsletter) endpoint instead.

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](#tag/Transactional).

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](#tag/Transactional).

Returns metrics for clicked links from a transactional message, both in total and in `series` periods (days, weeks, etc). `series` metrics are ordered oldest to newest (i.e. the 0-index for any result is the oldest step/period). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.

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.

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.

Trigger a broadcast (not a newsletter) and optionally provide data to populate liquid placeholders in the message. The shape of the request depends on how you define your audience: default (the recipients set in the UI), custom filter conditions, a list of emails, a list of customer IDs, a map of users, or a data file. **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>}}`. If your broadcast produces a `422` error, you can [get more information about the errors](#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. Broadcasts are optimized to send messages to a large audience and not for one-to-one interactions. Use our [transactional API](#tag/send-messages/sendEmail) or [event-triggered campaigns](/journeys/send/campaigns/triggers/#event-trigger) to respond to your audience on an individual, one-to-one basis.

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.

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

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.

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](#tag/design-studio) instead.

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](#tag/design-studio) instead.

Update the contents of a campaign action, including the body of messages and HTTP requests. **NOTE** You cannot manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](#tag/design-studio) instead.

Update the contents of a language variant of a campaign action, including the body of the messages and HTTP requests. **NOTE**: You cannot manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](#tag/design-studio) instead.

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

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](#operation/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.

Update part of a component: its name, tag, folder, or content.

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 connected to a workflow like a campaign, you still need to click publish to make the changes live.

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 connected to a workflow like a campaign, you still need to click publish to make the changes live.

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.

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.

Update the translation of a newsletter variant in an A/B test. You can retrieve a list of `test_group_ids` from [Get variants in a newsletter test group](/api/app/#operation/getNewsletterVariantTest). **NOTE**: You cannot manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](#tag/design-studio) instead.

Update the content of a newsletter: 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](#tag/design-studio).

Update the translation of a newsletter variant. If your newsletter includes A/B tests, use [Update a translation in a newsletter test group](/api/app/#operation/updateNewsletterTestTranslation). **NOTE**: You cannot manage content made with Design Studio with this endpoint. Use the [Design Studio APIs](#tag/design-studio) instead.

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.

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](#tag/design-studio) instead.

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](#tag/design-studio) instead.

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