Customer.io Campaigns API
Retrieve information about campaigns, campaign actions, and campaign metrics in your workspace.
Work with this as data
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/customer-io-campaigns-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
version: 1.0.0
title: Customer.io App Campaigns 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: Campaigns
x-displayName: Campaigns
description: 'A campaign is a workflow that people in your audience trigger and traverse. The items that happen within the workflow—messages, attribute changes, webhooks, etc that your audience triggers—are called actions.
These endpoints return information about campaigns including metrics and the actions included in campaigns. You can update individual campaign actions from these endpoints, but you must perform all other create, update, and/or delete operations through the UI.
'
paths:
/v1/campaigns:
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).
get:
summary: List campaigns
operationId: listCampaigns
security:
- Bearer-Auth: []
description: Returns a list of your campaigns and associated metadata.
tags:
- Campaigns
responses:
'200':
description: Returns an array of campaign objects.
content:
application/json:
schema:
type: object
properties:
campaigns:
type: array
description: Each object is a campaign in your workspace with one of seven types of campaign triggers.
items:
x-scalar-ignore: true
type: object
oneOf:
- title: Segment
type: object
properties:
id:
x-scalar-ignore: true
description: The identifier for a campaign.
type: integer
example: 5
deduplicate_id:
x-scalar-ignore: true
type: string
readOnly: true
description: An identifier in the format `id:timestamp` where the id is for the object you're working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated.
example: 15:1492548073
name:
x-scalar-ignore: true
type: string
description: The name of the campaign.
readOnly: true
description:
x-scalar-ignore: true
type: string
description: The description of the campaign, if one was set.
example: Sends a welcome series to new trial signups.
type:
type: string
deprecated: true
description: The type of campaign trigger. **Sunsetting on March 30, 2025**
enum:
- segment
created:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was created.
example: 1552341937
readOnly: true
updated:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was last updated.
example: 1552341937
readOnly: true
active:
x-scalar-ignore: true
type: boolean
description: If true, the campaign is active and can still send messages.
state:
x-scalar-ignore: true
type: string
description: The status of the campaign.
enum:
- running
- draft
- stopped
actions:
x-scalar-ignore: true
type: array
description: An array of actions contained within the campaign.
items:
type: object
properties:
type:
type: string
description: The action type.
example: email
id:
type: integer
description: The identifier for the action.
example: 259
first_started:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date and time when you first started the campaign and it first became eligible to be triggered.
example: 1552341937
tags:
x-scalar-ignore: true
type: array
description: An array of tags you set on this campaign.
items:
type: string
example:
- new
- welcome
trigger_segment_ids:
description: A list of segments used in the campaign trigger, returned if the campaign trigger included one or more segment conditions.
type: array
items:
type: integer
example:
- 90
filter_segment_ids:
x-scalar-ignore: true
description: A list of segments used in the campaign filter, returned if the campaign audience was filtered on one or more segments.
type: array
items:
type: integer
example:
- 21
- 42
msg_templates:
type: array
deprecated: true
description: Indicates the message templates used in this campaign.
items:
type: object
properties:
type:
type: string
description: The message type the template represents.
enum:
- email
- sms
- push
- slack
id:
type: integer
description: The identifier for the template.
- title: Event
type: object
properties:
id:
x-scalar-ignore: true
description: The identifier for a campaign.
type: integer
example: 5
deduplicate_id:
x-scalar-ignore: true
type: string
readOnly: true
description: An identifier in the format `id:timestamp` where the id is for the object you're working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated.
example: 15:1492548073
name:
x-scalar-ignore: true
type: string
description: The name of the campaign.
readOnly: true
description:
x-scalar-ignore: true
type: string
description: The description of the campaign, if one was set.
example: Sends a welcome series to new trial signups.
type:
type: string
deprecated: true
description: The type of campaign trigger. **Sunsetting on March 30, 2025**
enum:
- event
created:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was created.
example: 1552341937
readOnly: true
updated:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was last updated.
example: 1552341937
readOnly: true
active:
x-scalar-ignore: true
type: boolean
description: If true, the campaign is active and can still send messages.
state:
x-scalar-ignore: true
type: string
description: The status of the campaign.
enum:
- running
- draft
- stopped
actions:
x-scalar-ignore: true
type: array
description: An array of actions contained within the campaign.
items:
type: object
properties:
type:
type: string
description: The action type.
example: email
id:
type: integer
description: The identifier for the action.
example: 259
first_started:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date and time when you first started the campaign and it first became eligible to be triggered.
example: 1552341937
tags:
x-scalar-ignore: true
type: array
description: An array of tags you set on this campaign.
items:
type: string
example:
- new
- welcome
filter_segment_ids:
x-scalar-ignore: true
description: A list of segments used in the campaign filter, returned if the campaign audience was filtered on one or more segments.
type: array
items:
type: integer
example:
- 21
- 42
event_name:
description: The name of the event. How you reference the event in campaigns or segments.
type: string
- title: Form
type: object
properties:
id:
x-scalar-ignore: true
description: The identifier for a campaign.
type: integer
example: 5
deduplicate_id:
x-scalar-ignore: true
type: string
readOnly: true
description: An identifier in the format `id:timestamp` where the id is for the object you're working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated.
example: 15:1492548073
name:
x-scalar-ignore: true
type: string
description: The name of the campaign.
readOnly: true
description:
x-scalar-ignore: true
type: string
description: The description of the campaign, if one was set.
example: Sends a welcome series to new trial signups.
type:
type: string
deprecated: true
description: The type of campaign trigger. **Sunsetting on March 30, 2025**
enum:
- form
created:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was created.
example: 1552341937
readOnly: true
updated:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was last updated.
example: 1552341937
readOnly: true
active:
x-scalar-ignore: true
type: boolean
description: If true, the campaign is active and can still send messages.
state:
x-scalar-ignore: true
type: string
description: The status of the campaign.
enum:
- running
- draft
- stopped
actions:
x-scalar-ignore: true
type: array
description: An array of actions contained within the campaign.
items:
type: object
properties:
type:
type: string
description: The action type.
example: email
id:
type: integer
description: The identifier for the action.
example: 259
first_started:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date and time when you first started the campaign and it first became eligible to be triggered.
example: 1552341937
tags:
x-scalar-ignore: true
type: array
description: An array of tags you set on this campaign.
items:
type: string
example:
- new
- welcome
filter_segment_ids:
x-scalar-ignore: true
description: A list of segments used in the campaign filter, returned if the campaign audience was filtered on one or more segments.
type: array
items:
type: integer
example:
- 21
- 42
- title: Date
type: object
properties:
id:
x-scalar-ignore: true
description: The identifier for a campaign.
type: integer
example: 5
deduplicate_id:
x-scalar-ignore: true
type: string
readOnly: true
description: An identifier in the format `id:timestamp` where the id is for the object you're working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated.
example: 15:1492548073
name:
x-scalar-ignore: true
type: string
description: The name of the campaign.
readOnly: true
description:
x-scalar-ignore: true
type: string
description: The description of the campaign, if one was set.
example: Sends a welcome series to new trial signups.
type:
type: string
deprecated: true
description: The type of campaign trigger. **Sunsetting on March 30, 2025**
enum:
- date
created:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was created.
example: 1552341937
readOnly: true
updated:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was last updated.
example: 1552341937
readOnly: true
active:
x-scalar-ignore: true
type: boolean
description: If true, the campaign is active and can still send messages.
state:
x-scalar-ignore: true
type: string
description: The status of the campaign.
enum:
- running
- draft
- stopped
actions:
x-scalar-ignore: true
type: array
description: An array of actions contained within the campaign.
items:
type: object
properties:
type:
type: string
description: The action type.
example: email
id:
type: integer
description: The identifier for the action.
example: 259
first_started:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date and time when you first started the campaign and it first became eligible to be triggered.
example: 1552341937
tags:
x-scalar-ignore: true
type: array
description: An array of tags you set on this campaign.
items:
type: string
example:
- new
- welcome
filter_segment_ids:
x-scalar-ignore: true
description: A list of segments used in the campaign filter, returned if the campaign audience was filtered on one or more segments.
type: array
items:
type: integer
example:
- 21
- 42
frequency:
description: How often a person will receive this campaign based on the date specified in the campaign trigger.
type: string
enum:
- once
- monthly
- yearly
date_attribute:
description: The attribute on people's profiles you use to configure the date of the campaign trigger.
type: string
timezone:
description: The time zone you set to configure the date of the campaign trigger.
type: string
example: America/Chicago
use_customer_timezone:
description: If you chose "the user's time zone" while configuring the date of the campaign trigger, this is `true`. Otherwise, you set a specific time zone so it's `false`.
type: boolean
start_hour:
description: The hour you set the campaign to trigger. Follows the 24-hour clock.
type: integer
start_minutes:
description: The minutes you set the campaign to trigger. Follows the 24-hour clock.
type: integer
- title: Relationship
type: object
properties:
id:
x-scalar-ignore: true
description: The identifier for a campaign.
type: integer
example: 5
deduplicate_id:
x-scalar-ignore: true
type: string
readOnly: true
description: An identifier in the format `id:timestamp` where the id is for the object you're working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated.
example: 15:1492548073
name:
x-scalar-ignore: true
type: string
description: The name of the campaign.
readOnly: true
description:
x-scalar-ignore: true
type: string
description: The description of the campaign, if one was set.
example: Sends a welcome series to new trial signups.
type:
type: string
deprecated: true
description: The type of campaign trigger. **Sunsetting on March 30, 2025**
enum:
- relationship
created:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was created.
example: 1552341937
readOnly: true
updated:
x-sca
# --- truncated at 32 KB (381 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/customer-io/refs/heads/main/openapi/customer-io-campaigns-api-openapi.yml