How do AI agents use Customer.io App API through Open Connector?

Your user connects Customer.io App API once with one of its cataloged authentication methods. Open Connector stores the credential in an encrypted vault and exposes Customer.io App API tools to your agent over MCP or a typed API, with credentials injected server-side on each call.

Is this a Customer.io App API MCP server?

Yes. Open Connector can serve Customer.io App API as a named MCP server with a scoped allowlist and a per-user connection URL, so any MCP client can call Customer.io App API actions with credentials injected server-side.

Where do Customer.io App API credentials live?

In your own infrastructure. Open Connector keeps credentials in its own vault and injects them at call time, so they never leave your environment.

Customer.io App API integration

Customer.io App API integration for AI agents.

Customer.io App API integration for AI agents with secure authentication and server-side credential injection. Open Connector runs the OAuth, seals the token in an encrypted vault, and serves Customer.io App API tools to your agent over MCP or a typed API — credentials injected server-side, every call audited, nothing leaving your infrastructure. Open source (AGPL-3.0) and self-hostable.

View source on GitHub All integrations →

What your agents can do

Real Customer.io App API actions, managed and audited.

Your user connects Customer.io App API once; your agent can then manage Customer.io campaigns, newsletters, broadcasts, segments, and people through the App API — scoped to the OAuth permissions you grant and the tool allowlist you configure. Every action is least-privilege and written to a tamper-evident audit trail.

1
Your user grants Customer.io App API access once (OAuth) — the token lands in the vault.
2
Your agent calls a tool over MCP or the typed API; Open Connector injects the credential server-side.
3
Every routed call appends a hash-chained audit record — nothing leaves your infra.

Tools & triggers

Supported Customer.io App API tools.

159 tools are generated from the published Customer.io App API catalog. Descriptions are plain text; each action remains subject to its configured authentication and tool allowlist.

Showing 159 tools. All published catalog entries are included in this page's server-rendered HTML.

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.; Collections
Get broadcast action link metrics: Returns link click metrics for an individual broadcast action. Unless you specify otherwise, the response contains data for the maximum period by days (45 days). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.; Broadcasts
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.; Broadcasts
List broadcast actions: Returns the actions that occur as a part of a broadcast.; Broadcasts
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.; Broadcasts
Get broadcast link metrics: Returns metrics for link clicks within a broadcast, both in total and in `series` periods (days, weeks, etc). `series` metrics are ordered oldest to newest (i.e. the 0-index for any result is the oldest step/period). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.; Broadcasts
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.; Broadcasts
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.; Broadcasts
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](/api/app/#operation/listBroadcastTriggers).; Broadcasts
Get link metrics for an action: Returns link click metrics for an individual action. Unless you specify otherwise, the response contains data for the maximum period by days (45 days). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.; Campaigns
Get campaign action metrics: 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`; Campaigns
Get campaign journey metrics: 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.; Campaigns
Get campaign link metrics: 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.; Campaigns
Get campaign metrics: 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`; Campaigns
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.; Assets
Create a folder: Creates a new folder for organizing file assets. Folder names must be unique within the same parent folder.; Assets
Create a component: Creates a custom component.; Design Studio
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 connect it to a workflow like a campaign.; Design Studio
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.; Design Studio
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](#tag/design-studio/listFolders).; Design Studio
Create a manual segment: Create a manual segment with a name and a description. This request creates an empty segment.; Segments
Create and send a newsletter: 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.; Newsletters
Add a translation to a newsletter: 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.; Newsletter Variants
Create an A/B test group for a newsletter: 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.; Newsletter Variants
Add a translation to a newsletter test group: 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.; Newsletter Variants
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.; Snippets
Create a reporting webhook: Create a new webhook configuration.; Reporting Webhooks
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.; Assets
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.; Assets
Delete a collection: 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.; Collections
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.; Design Studio
Delete an email: Delete an email. You cannot delete an email that is linked to a workflow (campaign, broadcast, etc). This deletes the email and all translations.; Design Studio
Delete an email translation: Delete a specific language translation from an email. This fails if the email is linked to a workflow (campaign, broadcast, etc).; Design Studio
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 (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.; Design Studio
Delete a segment: Delete a manual segment.; Segments
Delete a translation of a newsletter: 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).; Newsletter Variants
Delete a translation in a newsletter test group: 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).; Newsletter Variants
Delete a newsletter: 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.; Newsletters
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.; Snippets
Un-suppress an ESP-suppressed address: Remove an address from the ESP's suppression list.; ESP Suppression
Delete a reporting webhook: Delete a reporting webhook's configuration.; Reporting Webhooks
Download an export: This endpoint returns a signed link to download an export. The link expires after 15 minutes.; Exports
Export information about deliveries: 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.; Exports
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.; Exports
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.; Messages
Get a file asset: Retrieves a single file asset by its ID. Returns 404 if the asset does not exist or is a folder.; Assets
Get a folder: Retrieves a single folder by its ID.; Assets
Get a broadcast: Returns metadata for an individual broadcast.; Broadcasts
Get a broadcast action: Returns information about a specific action within a broadcast.; Broadcasts
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`.; Broadcasts
Get a campaign action: Returns information about a specific action in a campaign.; Campaigns
Get a translation of a campaign message: Returns a translated version of a message in a campaign. The message is identified by the `action_id`.; Campaigns
Get campaign message metadata: 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.; Campaigns
Get a campaign: Returns metadata for an individual campaign.; Campaigns
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.; Subscription Center
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.; Info
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).; Collections
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.; Collections
List your collections: Returns a list of all of your collections, including the `name` and `schema` for each collection.; Collections
Get a component: Returns a single component with its full content.; Design Studio
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.; ESP Suppression
Get an email: 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.; Design Studio
Get an email translation: Returns a single email translation by language code, including content, envelope, and transformers.; Design Studio
Get an export: Return information about a specific export.; Exports
Get a folder: Get a folder by its UUID. You can retrieve the UUID of folders through [List folders](#tag/design-studio/listFolders).; Design Studio
Retrieve a bulk import: 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.; Imports
Get a message: Return a information about, and metrics for, a delivery—the instance of a message intended for an individual recipient person.; Messages
Get click metrics for newsletter links: 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.; Newsletter Metrics
Get newsletter metrics: 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.; Newsletter Metrics
Get delivery data for a newsletter: 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.; Newsletter Metrics
List a newsletter's A/B test groups: Returns information about each test group in a newsletter, including content ids for each group.; Newsletter Variants
Get a newsletter variant: 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.; Newsletter Variants
Get a newsletter translation: 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).; Newsletter Variants
Get a translation in a newsletter test group: 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).; Newsletter Variants
Get a newsletter: Returns metadata for an individual newsletter.; Newsletters
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.; Objects
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.; Objects
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.; Objects
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.; Objects
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.; Customers
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.; Customers
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`](#tag/Exports) API instead.; Customers
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.; Customers
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.; Customers
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.; Customers
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.; Customers
Lookup a customer's segments: Returns a list of segments that a customer profile belongs to.; Customers
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.; Customers
Get a segment: Return information about a segment.; Segments
Get a segment customer count: Returns the membership count for a segment.; Segments
Get a segment's dependencies: Use this endpoint to find out which campaigns and newsletters use a segment.; Segments
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.; Segments
Get a sender: Returns information about a specific sender.; Sender Identities
Get sender usage data: Returns lists of the campaigns and newsletters that use a sender.; Sender Identities
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.; Subscription Center
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).; ESP Suppression
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.; ESP Suppression
List subscription topics: Returns a list of subscription topics in your workspace. If there are no topics, it returns an empty array.; Subscription Center
Get a transactional message: Returns information about an individual transactional message.; Transactional
Get a translation of a transactional message: Returns information about a translation of an individual transactional message, including the message content.; Transactional
Get click metrics for links in newsletter variants: 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.; Newsletter Metrics
Get metrics for a test or translation variant of a newsletter: Returns a metrics for an individual newsletter variant—either an individual language in a multi-language newsletter or a message in an A/B test. This endpoint returns metrics both in total and in `steps` (days, weeks, etc) over a `period` of time. Stepped `series` metrics are arranged from oldest to newest (i.e. the 0-index for any result is the oldest period/step). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.; Newsletter Metrics
Get a reporting webhook: Returns information about a specific reporting webhook.; Reporting Webhooks
Import items in bulk: 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.; Imports
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.; Activities
List folders: Returns a paginated list of asset folders. Supports filtering by parent folder and choosing between direct children or the entire folder subtree.; Assets
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.; Assets
Get broadcast triggers: Returns a list of the `triggers` for a broadcast.; Broadcasts
List broadcasts: Returns a list of your API-triggered broadcasts and associated metadata.; Broadcasts
List campaign actions: 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.; Campaigns
List campaigns: Returns a list of your campaigns and associated metadata.; Campaigns
List components: Returns a paginated list of components and any folders in the result set.; Design Studio
List email translations: Returns all translations for an email. Each translation contains the email's content, envelope, and transformers for a specific language.; Design Studio
List emails: Returns a paginated list of emails and a separate array of folders that the emails belong to.; Design Studio
List exports: Return a list of your exports. Exports are point-in-time people or campaign metrics.; Exports
List folders: Returns a paginated list of folders. This does not include files like emails, components, etc.; Design Studio
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.; Messages
List newsletter variants: Returns a newsletter's content variants—these are either different languages in a multi-language newsletter or A/B tests.; Newsletter Variants
List newsletters: Returns a list of your newsletters and associated metadata.; Newsletters
List segments: Retrieve a list of all of your segments.; Segments
List sender identities: Returns a list of senders in your workspace. Senders are who your messages are "from".; Sender Identities
List snippets: Returns a list of snippets in your workspace. Snippets are pieces of reusable content, like a common footer for your emails.; Snippets
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.; Transactional
List all variants of a transactional message: Returns the content variants of a transactional message, where each variant represents a different language.; Transactional
List reporting webhooks: Return a list of all of your reporting webhooks; Reporting Webhooks
List workspaces: Returns a list of workspaces in your account.; Workspaces
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).; ESP Suppression
Schedule a newsletter: 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 Messages
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.; Send Messages
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](#tag/Transactional). **Note**: Your workspace must have in-app messaging enabled. Requests sent to a workspace without the in-app capability return `403`.; Send Messages
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](#tag/Transactional). **Note**: Inbox messages are currently available for web platforms only and require the Customer.io In-App Plugin to be installed.; Send Messages
Send a newsletter: 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 Messages
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](#tag/Transactional).; Send Messages
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](#tag/Transactional).; Send Messages
Get transactional message link metrics: Returns metrics for clicked links from a transactional message, both in total and in `series` periods (days, weeks, etc). `series` metrics are ordered oldest to newest (i.e. the 0-index for any result is the oldest step/period). You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, `?period=days&steps=1` means two days - the 48 hours before the API request was made. `?period=days&steps=0` returns the same as the maximum of the period - `?period=days&steps=45`. See the `steps` parameter below for the maximum count of each period.; Transactional
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.; Transactional
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.; Transactional
Send an API-triggered broadcast: 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.; Send Messages
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.; Assets
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).; Assets
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.; Data Index
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](#tag/design-studio) instead.; Broadcasts
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](#tag/design-studio) instead.; Broadcasts
Update a campaign action: 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.; Campaigns
Update a translation of a campaign message: 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.; Campaigns
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 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.; Collections
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](#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.; Collections
Update a component: Update part of a component: its name, tag, folder, or content.; Design Studio
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 connected to a workflow like a campaign, you still need to click publish to make the changes live.; Design Studio
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 connected to a workflow like a campaign, you still need to click publish to make the changes live.; Design Studio
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.; Data Index
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.; Design Studio
Update a translation in a newsletter test group: Update the translation of a newsletter variant in an A/B test. You can retrieve a list of `test_group_ids` from [Get variants in a newsletter test group](/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.; Newsletter Variants
Update a newsletter variant: 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).; Newsletter Variants
Update a translation of a newsletter: 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.; Newsletter Variants
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.; Snippets
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](#tag/design-studio) instead.; Transactional
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](#tag/design-studio) instead.; Transactional
Update a webhook configuration: Update the configuration of a reporting webhook. Turn events on or off, change the webhook URL, etc.; Reporting Webhooks

FAQ

Customer.io App API integration, answered

How do AI agents use Customer.io App API through Open Connector?: Your user connects Customer.io App API once with one of its cataloged authentication methods. Open Connector stores the credential in an encrypted vault and exposes Customer.io App API tools to your agent over MCP or a typed API, with credentials injected server-side on each call.
Is this a Customer.io App API MCP server?: Yes. Open Connector can serve Customer.io App API as a named MCP server with a scoped allowlist and a per-user connection URL, so any MCP client can call Customer.io App API actions with credentials injected server-side.
Where do Customer.io App API credentials live?: In your own infrastructure. Open Connector keeps credentials in its own vault and injects them at call time, so they never leave your environment.

Give your agents Customer.io App API — keep the keys.

Open source, self-hostable, with Customer.io App API credentials that never leave your infrastructure. Run it from source today.

View source on GitHub How the MCP gateway works →