Customer.io Send Messages API
Use these endpoints to send broadcasts or transactional messages to your audience. They use the same authentication method, but review the limits for both types of workflows to make sure you'll successfully trigger your messages. You can't trigger campaigns through our APIs. ## API triggered broadcast limits While [API triggered broadcasts](#operation/triggerBroadcast) are limited to 1 request every 10 seconds, they're also limited by the number of triggers you can have queued at a time, as shown in the table below. | Data Type | Limit | Description | | -- | -- | -- | | Trigger Payload | 25MB | Max length of the entire Trigger call, larger calls are typically to support `per_user_data` | | Trigger Data | 50000 bytes | Max length of the data section in the Trigger call | | Recipient List1 | 10000 recipients | Max number of ids or emails included in the Trigger call | | Custom Per User Data1 | 10000 entries | Max number of entries in `per_user_data` | | Custom Per User Data1 | 2MB | Max length per user in the file referenced by `data_file_url`. | | Custom Per User Data1 | 10GB | Max length of the entire size of the file referenced by `data_file_url` | | Trigger Queue | 5 triggers | Max number of triggers waiting to be processed consecutively | 1For larger data sets, use `data_file_url` to supply a link to a file that contains your merge data. Attempting to send too much data in a single API call will fail. ## Transactional Message Limits The `/send-*` endpoints are limited to 100 requests per second. | Data Type | Limit | Description | | -- | -- | -- | | Payload | 1MB | Max length of the payload, excepting attachments | | Attachments (email) | 2MB | Maximum size of attachments | | Recipients | 15 | Total number of recipients across the `to`, `cc`, and `bcc` fields. |
POST
/v1/campaigns/{broadcast_id}/triggers
Send an API-triggered broadcast
#
POST
/v1/newsletters/{newsletter_id}/send
Send a newsletter
#
POST
/v1/newsletters/{newsletter_id}/schedule
Schedule a newsletter
#
POST
/v1/send/email
Send a transactional email
#
POST
/v1/send/in_app
Send a transactional in-app message
#
POST
/v1/send/inbox_message
Send a transactional inbox message
#
POST
/v1/send/push
Send a transactional push
#
POST
/v1/send/sms
Send a transactional SMS
#
Documentation
Specifications
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
All 92 tools →
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/customer-io-send-messages-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no email required.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
version: 1.0.0
title: Customer.io App Send Messages API
description: 'Our App API provides ways to trigger messages and retrieve information about people, campaigns, broadcasts, and more.
# Overview
The App API provides methods to send newsletters, transactional messages, and API-triggered broadcasts. You can create newsletters from scratch and update transactional messages and API-triggered broadcasts.
For transactional messages and API-triggered broadcasts, your payload acts as a message "trigger" and can contain `data` that you reference in your messages using liquid—`{{trigger.<data>}}`.
The other endpoints help you retrieve information about people, segments, campaigns, broadcasts, etc; it also lets you update campaign actions, messages, newsletter variants, etc. Aside from the [API-triggered broadcast](#triggerBroadcast) (1 per 10 seconds) and [Transactional](#sendEmail) (100 per second) endpoints, requests are limited to 10 per second.
# Use our Postman collection
We''ve generated a Postman collection to help you get started with our APIs.
If you fork this collection, you might want to disable the *Watch original collection* option. We automatically update our Postman collection whenever we release changes to our documentation, even if we don''t change our APIs—which happens daily! Rather than being flooded with Postman notifications, you can check out our [Release Notes](/release-notes/) for updates to our APIs.
**NOTE**: Postman endpoints default to our US APIs. If you''re in our European (EU) region, you''ll need to add `-eu` to the server variables (`track_api_url` and `app_api_url`).
[<img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style="width: 128px; height: 32px;">](https://god.gw.postman.com/run-collection/23697545-2931c004-e63d-4cdc-bf4b-e685ba6da42d?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D23697545-2931c004-e63d-4cdc-bf4b-e685ba6da42d%26entityType%3Dcollection%26workspaceId%3Db886877f-fc09-475f-84fe-6221a98f4d18#?env%5BCustomer.io%20API%20Environment%5D=W3sia2V5IjoidHJhY2tfYXBpX3VybCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiJ0cmFjay5jdXN0b21lci5pbyIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBwX2FwaV91cmwiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiYXBpLmN1c3RvbWVyLmlvIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJzaXRlX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBpX2tleSIsInR5cGUiOiJzZWNyZXQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYmVhcmVyIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYnJvYWRjYXN0X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiaW1wb3J0X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiZW1haWxfYWRkcmVzcyIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InN1cHByZXNzaW9uX3R5cGUiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjb2xsZWN0aW9uX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoic25pcHBldF9uYW1lIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoid2ViaG9va19pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InNlbmRlcl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImV4cG9ydF9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6Im1lc3NhZ2VfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJzZWdtZW50X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoibmV3c2xldHRlcl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImNvbnRlbnRfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjYW1wYWlnbl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFjdGlvbl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImN1c3RvbWVyX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidHJhbnNhY3Rpb25hbF9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRyaWdnZXJfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJmb3JtX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiaWRlbnRpZmllciIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImRldmljZV9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImRlbGl2ZXJ5X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9XQ==)
# Server addresses: US and EU
Customer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.
| Region | Server Address |
| :-- | :-- |
| US | https://api.customer.io |
| EU | https://api-eu.customer.io |
# Authentication
All requests to the Customer.io App API use an [App API Key](#App-API-Key).
To authenticate, provide your key as a Bearer token in a HTTP Authorization header. You can create and manage your API keys—including keys with different scopes—in [your account settings page](https://fly.customer.io/settings/api_credentials?keyType=app). Each operation on this page references the authorization header it requires.
# Rate Limits
Most endpoints on this page are limited to 10 requests per second. The exceptions are:
* The [transactional email](#operation/sendEmail) endpoint is limited to 100 requests per second.
* The [API-triggered broadcast endpoint](#operation/triggerBroadcast) is limited to 1 request every 10 seconds.
**Rate limits are subject to change. We may adjust these thresholds to ensure stable performance for all customers.**
'
servers:
- url: https://api.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
tags:
- name: Send Messages
description: 'Use these endpoints to send broadcasts or transactional messages to your audience. They use the same authentication method, but review the limits for both types of workflows to make sure you''ll successfully trigger your messages.
You can''t trigger campaigns through our APIs.
## API triggered broadcast limits
While [API triggered broadcasts](#operation/triggerBroadcast) are limited to 1 request every 10 seconds, they''re also limited by the number of triggers you can have queued at a time, as shown in the table below.
| Data Type | Limit | Description |
| -- | -- | -- |
| Trigger Payload | 25MB | Max length of the entire Trigger call, larger calls are typically to support `per_user_data` |
| Trigger Data | 50000 bytes | Max length of the data section in the Trigger call |
| Recipient List<sup>1</sup> | 10000 recipients | Max number of ids or emails included in the Trigger call |
| Custom Per User Data<sup>1</sup> | 10000 entries | Max number of entries in `per_user_data` |
| Custom Per User Data<sup>1</sup> | 2MB | Max length per user in the file referenced by `data_file_url`. |
| Custom Per User Data<sup>1</sup> | 10GB | Max length of the entire size of the file referenced by `data_file_url` |
| Trigger Queue | 5 triggers | Max number of triggers waiting to be processed consecutively |
<sup>1</sup>For larger data sets, use `data_file_url` to supply a link to a file that contains your merge data. Attempting to send too much data in a single API call will fail.
## Transactional Message Limits
The `/send-*` endpoints are limited to 100 requests per second.
| Data Type | Limit | Description |
| -- | -- | -- |
| Payload | 1MB | Max length of the payload, excepting attachments |
| Attachments (email) | 2MB | Maximum size of attachments |
| Recipients | 15 | Total number of recipients across the `to`, `cc`, and `bcc` fields. |
'
paths:
/v1/campaigns/{broadcast_id}/triggers:
servers:
- url: https://api.customer.io
description: This API uses bearer authorization, requiring a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
parameters:
- name: broadcast_id
in: path
required: true
description: The ID of the broadcast that you want to trigger.
schema:
type: integer
post:
operationId: triggerBroadcast
tags:
- Send Messages
summary: Send an API-triggered broadcast
security:
- Bearer-Auth: []
description: '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.
'
requestBody:
content:
application/json:
x-rate-limit: 10
schema:
x-scalar-ignore: true
oneOf:
- title: Default audience
description: Send your broadcast to the default set of recipients defined in the UI.
allOf:
- x-scalar-ignore: true
type: object
properties:
data:
type: object
description: Contains information you want to use to populate your broadcast.
additionalProperties:
x-additionalPropertiesName: Broadcast liquid data
description: Insert key-values that you want to reference in your message here.
example:
headline: Roadrunner spotted in Albuquerque!
date: 1511315635
text: We received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!
email_add_duplicates:
type: boolean
default: false
description: an email address associated with more than one profile id is an error.
email_ignore_missing:
type: boolean
default: false
description: If false, a missing email causes the broadcast to error and fail. If true, the broadcast will skip over any people in your audience who don't have emails, and continue sending to the rest of your audience.
id_ignore_missing:
type: boolean
default: false
description: If false, a missing customer ID causes the broadcast to error and fail. If true, the broadcast will skip over any people in your audience who don't have IDs, and continue sending to the rest of your audience.
- title: Custom recipients
description: Send your broadcast to a group of people defined by a set of filters.
allOf:
- type: object
required:
- recipients
properties:
recipients:
x-scalar-ignore: true
title: Audience Filter
description: Use `and`, `or`, and `not` to combine segment and attribute conditions. The top-level object accepts one property; nest groups for complex filters.
oneOf:
- x-scalar-ignore: true
title: and
type: object
properties:
and:
type: array
description: Match *all* conditions to return results.
items:
type: object
properties:
or:
type: array
description: Returns results matching *any* conditions.
items:
x-scalar-ignore: true
anyOf:
- title: segment
description: Filter for people who belong to a segment.
type: object
properties:
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
- title: audience
type: object
description: filter for people who have an attribute or an attribute value.
properties:
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
example: first_name
operator:
type: string
description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
enum:
- eq
- exists
value:
type: string
description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
example:
field: unsubscribed
operator: eq
value: true
not:
description: Returns results if a condition is false. While and/or support an array of items, `not` supports a single filter object.
oneOf:
- title: and
type: object
properties:
and:
type: array
description: Match *all* conditions to return results.
items:
x-scalar-ignore: true
anyOf:
- title: segment
description: Filter for people who belong to a segment.
type: object
properties:
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
- title: audience
type: object
description: filter for people who have an attribute or an attribute value.
properties:
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
example: first_name
operator:
type: string
description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
enum:
- eq
- exists
value:
type: string
description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
example:
field: unsubscribed
operator: eq
value: true
- title: or
type: object
properties:
or:
type: array
description: Match *any* condition to return results.
items:
x-scalar-ignore: true
anyOf:
- title: segment
description: Filter for people who belong to a segment.
type: object
properties:
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
- title: audience
type: object
description: filter for people who have an attribute or an attribute value.
properties:
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
example: first_name
operator:
type: string
description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
enum:
- eq
- exists
value:
type: string
description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
example:
field: unsubscribed
operator: eq
value: true
- title: segment
type: object
properties:
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
- title: attribute
type: object
properties:
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
example: first_name
operator:
type: string
description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
enum:
- eq
- exists
value:
type: string
description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
example:
field: unsubscribed
operator: eq
value: true
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
example: first_name
operator:
type: string
description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
enum:
- eq
- exists
value:
type: string
description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
example:
field: unsubscribed
operator: eq
value: true
- x-scalar-ignore: true
title: or
type: object
properties:
or:
type: array
description: Match *any* condition to return results.
items:
type: object
properties:
and:
type: array
description: Returns results matching *all* conditions.
items:
x-scalar-ignore: true
anyOf:
- title: segment
description: Filter for people who belong to a segment.
type: object
properties:
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
- title: audience
type: object
description: filter for people who have an attribute or an attribute value.
properties:
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
# --- truncated at 32 KB (247 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/customer-io/refs/heads/main/openapi/customer-io-send-messages-api-openapi.yml