v1.0.0

OAS 3.1.0

Journeys App API

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 (1 per 10 seconds) and Transactional (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 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).

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.

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. 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 endpoint is limited to 100 requests per second.
The API-triggered broadcast endpoint 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.

Server

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.

Client Libraries

Shell Curl

Send Messages

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 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¹	10000 recipients	Max number of ids or emails included in the Trigger call
Custom Per User Data¹	10000 entries	Max number of entries in `per_user_data`
Custom Per User Data¹	2MB	Max length per user in the file referenced by `data_file_url`.
Custom Per User Data¹	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

¹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` and `bcc` fields.

Send Messages Operations

post/v1/campaigns/{broadcast_id}/triggers
post/v1/newsletters/{newsletter_id}/send
post/v1/newsletters/{newsletter_id}/schedule
post/v1/send/email
post/v1/send/in_app
post/v1/send/inbox_message
post/v1/send/push
post/v1/send/sms

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

Broadcasts are optimized to send messages to a large audience and not for one-to-one interactions. Use our transactional API or event-triggered campaigns to respond to your audience on an individual, one-to-one basis.

Path Parameters

broadcast_id
Type: integer
required

The ID of the broadcast that you want to trigger.

Body

application/json

Send your broadcast to the default set of recipients defined in the UI.
data
Type: object

Contains information you want to use to populate your broadcast.

email_add_duplicates
Type: boolean

an email address associated with more than one profile id is an error.

email_ignore_missing
Type: boolean

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

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.

Responses

application/json
401

Unauthorized request. Make sure that you provided the right credentials.
404

The broadcast_id does not exist.
application/json

post/v1/campaigns/{broadcast_id}/triggers

{}

Show Schema

{
  "id": 3
}

A successful request returns the trigger ID.

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 endpoint to get a list of newsletters and their recipients.

To reschedule a newsletter, use the Schedule a newsletter endpoint instead.

Path Parameters

newsletter_id
Type: integer
required

The identifier of a newsletter.

Body

application/json

Optional rate limiting when you send or schedule a newsletter. If you set either rate_limit_email_rate or rate_limit_time_period, you must set both. Each must be a positive integer. You can set rate_limit_spread on its own or together with the other two fields.

rate_limit_email_rate
Type: integer
min:
1

Maximum number of messages per time period. NOTE: Though this states email_rate, you can use this for other message channels. Only fixed rate limits are supported, not daily ramp limits.
rate_limit_time_period
Type: integerenum

Time period in seconds for rate limiting. Must be one of 60 (minute), 3600 (hour), or 86400 (day).
values
- 60
- 3600
- 86400
rate_limit_spread
Type: boolean

When true, spreads messages evenly across the time period. Otherwise, it sends as fast as possible up to the limit in each period.

Responses

application/json
application/json
404

The newsletter does not exist.
application/json
429

Your request is over the 10-per-second limit.

post/v1/newsletters/{newsletter_id}/send

{
  "rate_limit_email_rate": 500,
  "rate_limit_time_period": 60,
  "rate_limit_spread": true
}

Show Schema

{
  "newsletter": {
    "id": 128275,
    "deduplicate_id": "128275:1484870424",
    "type": "email",
    "content_ids": [
      45
    ],
    "name": "Weekly Product Update",
    "sent_at": 1481653929,
    "created": 1481653919,
    "updated": 1481653929,
    "recipient_segment_ids": [
      42,
      99
    ],
    "tags": [
      "Product Updates"
    ],
    "subscription_topic_id": 5
  }
}

The newsletter is queued.

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 endpoint to get a list of newsletters and their recipients.

Path Parameters

newsletter_id
Type: integer
required

The identifier of a newsletter.

Body

required

application/json

Type: object
Optional rate limiting when you send or schedule a newsletter. If you set either rate_limit_email_rate or rate_limit_time_period, you must set both. Each must be a positive integer. You can set rate_limit_spread on its own or together with the other two fields.
- scheduled_at
  Type: integerFormat: unix timestamp
  required
  
  Unix timestamp for the send. Use 0 to deschedule. When greater than 0, the time must be in the future and you must send timezone so the UI displays the time correctly.
- timezone
  Type: string
  
  IANA timezone name (for example, America/New_York). Required when scheduled_at is greater than 0. Not required when descheduling (scheduled_at is 0).
- tz_match_enabled
  Type: boolean
  
  When true, sends at the same local time in each recipient's timezone. If it's set to true and rate_limit_time_period is provided, then the period can't be greater than 3600 (1 hour).
- rate_limit_email_rate
  Type: integer
  min:
  1
  
  Maximum number of messages per time period. NOTE: Though this states email_rate, you can use this for other message channels. Only fixed rate limits are supported, not daily ramp limits.
- rate_limit_time_period
  Type: integerenum
  
  Time period in seconds for rate limiting. Must be one of 60 (minute), 3600 (hour), or 86400 (day).
  
  values
  60
  3600
  86400
- rate_limit_spread
  Type: boolean
  
  When true, spreads messages evenly across the time period. Otherwise, it sends as fast as possible up to the limit in each period.

Responses

application/json
application/json
404

The newsletter does not exist.
application/json
429

Your request is over the 10-per-second limit.

post/v1/newsletters/{newsletter_id}/schedule

{
  "scheduled_at": 1719849600,
  "timezone": "America/New_York",
  "tz_match_enabled": false,
  "rate_limit_email_rate": 500,
  "rate_limit_time_period": 60,
  "rate_limit_spread": true
}

Show Schema

{
  "newsletter": {
    "id": 128275,
    "deduplicate_id": "128275:1484870424",
    "type": "email",
    "content_ids": [
      45
    ],
    "name": "Weekly Product Update",
    "sent_at": null,
    "created": 1481653919,
    "updated": 1481653929,
    "recipient_segment_ids": [
      42,
      99
    ],
    "subscription_topic_id": 5
  }
}

The newsletter is scheduled for sending.

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 for more details.

Body

application/json

- to
  Type: string
  required
  
  The message recipient(s). Supports multiple addresses separated by commas. Your request can contain up to 15 total recipients between the to and bcc keys.
  
  You can include a display or "friendly" name in "to" address, but we recommend that you use quotation marks around the friendly name to avoid potential issues with special characters, e.g. \"Person\" <person@example.com>.
- transactional_message_id
  
  The transactional message template you want to use. You can call the template by its numerical ID or by the Trigger Name that you assigned to the template in the UI (case insensitive).
  
  Type: integer · ID (integer)
  
  The ID of the transactional message you want to send.
- body
  Type: string
  
  The HTML body of your message. If you provide transactional_message_id, this overrides the template's body. If you send an AMP-enabled email (with body_amp) and the recipient's email client doesn't support AMP, this is the fallback email.
- body_amp
  Type: string
  
  You can add AMP-enabled content to emails. If your recipient's email client doesn't support AMP, they will receive the body content. Make sure you're set up to send AMP content; there are several requirements to successfully send and receive AMP-enabled emails.
- body_plain
  Type: string
  
  The plaintext body of your message. If you provide transactional_message_id, this overrides the template's plaintext body.
- subject
  Type: string
  
  The subject line for your message. If you provide transactional_message_id, this overrides the template's subject.
- from
  Type: string
  
  The address that your email is from. This address must be verified by Customer.io—see Authenticate your sending domain for how to verify a domain. If you provide transactional_message_id, this overrides the template's from address. You can include a display/friendly name in your from address, but we recommend that you use quotation marks around the friendly name to avoid potential issues with special characters, e.g. \"Person\" <person@example.com>.
  
  If you omit from (and the template has no from either, or you didn't include a template), Customer.io falls back to your workspace's default sender at render time. This requires at least one verified sending domain in your workspace.
- language
  Type: string
  
  Overrides language preferences for the person you want to send your transactional message to. Use one of our supported two- or four-letter language codes.
- identifiers
  
  Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.
  
  Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.
  
  id
  Type: string
  required
  
  The identifier for the person represented by the transactional message. NOTE: If your workspace identifies people by email, use the email identifier instead.
- message_data
  Type: object
  
  An object containing the key-value pairs referenced using liquid in your message.
- send_at
  Type: integer
  
  A unix timestamp (seconds since epoch) determining when the message will be sent. The timestamp can be up to 90 days in the future. If this value is in the past, your message is sent immediately.
- disable_message_retention
  Type: boolean
  
  If true, the message body is not retained in delivery history. Setting this value overrides the value set in the settings of your transactional_message_id.
- send_to_unsubscribed
  Type: boolean
  
  If false, your message is not sent to unsubscribed recipients. Setting this value overrides the value set in the settings of your transactional_message_id.
- queue_draft
  Type: boolean
  
  If true, your transactional message is held as a draft in Customer.io and not sent directly to your audience. You must go to the Deliveries and Drafts page to send your message.
- auto_create
  Type: boolean
  
  If true and transactional_message_id doesn't match an existing record, Customer.io creates an empty record using that value as the Trigger Name. Subsequent sends with the same value reuse the record, so they roll up under one ID in your metrics.
  
  transactional_message_id must be a string when auto_create is true. If the name already belongs to a record on a different channel, the request fails with 400. Numeric values for transactional_message_id ignore auto_create.
- bcc
  Type: string
  
  Blind copy message recipients. Supports multiple addresses separated by commas. Your request can contain up to 15 total recipients between the to and bcc keys.
- fake_bcc
  Type: boolean
  
  If true, rather than sending true copies to BCC addresses, Customer.io sends a copy of the message with the subject line containing the recipient address(es).
- reply_to
  Type: string
  
  The address that recipients can reply to, if different from the from address.
- preheader
  Type: string
  
  Also known as "preview text", this is the block block of text that users see next to, or underneath, the subject line in their inbox.
- attachments
  Type: object
  
  A dictionary of attachments where the filename is the key and the value is the base64-encoded contents. The filename must include the extension (i.e. name.csv). The total size of all attachments must be less than 2 MB.
- headers
  Type: stringFormat: json
  
  A JSON string containing an array of header objects, where each object contains a name and a value. Header names and values must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten.
- disable_css_preprocessing
  Type: boolean
  
  Set to true to disable CSS preprocessing. This setting overrides the CSS preprocessing setting on the transactional_message_id as set in the user interface. Transactional emails have CSS preprocessing enabled by default.
- tracked
  Type: boolean
  
  If true, Customer.io tracks opens and link clicks in your message.

Responses

application/json
application/json
application/json
application/json

post/v1/send/email

{
  "transactional_message_id": 44,
  "to": "cool.person@example.com",
  "from": "override-templated-address@example.com",
  "subject": "Order receipt",
  "identifiers": {
    "email": "cool.person@example.com"
  },
  "message_data": {
    "password_reset_token": "abcde-12345-fghij-d888",
    "account_id": "123dj"
  },
  "attachments": {
    "file1.csv": "base64encodedcontent",
    "file2.pdf": "base64encodedcontent"
  },
  "headers": {
    "X-Mailgun-Tag": "my-cool-tag"
  },
  "bcc": "bcc@example.com",
  "disable_message_retention": false,
  "send_to_unsubscribed": true,
  "tracked": true,
  "queue_draft": false,
  "disable_css_preprocessing": true
}

Show Schema

{
  "delivery_id": "string",
  "queued_at": 1
}

Returns a unique ID for the delivery.

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.

Note: Your workspace must have in-app messaging enabled. Requests sent to a workspace without the in-app capability return 403.

Body

application/json

Type: object

Responses

application/json
application/json
application/json

post/v1/send/in_app

{
  "transactional_message_id": "order_confirmation",
  "identifiers": {
    "id": "user_123"
  },
  "message_data": {
    "order_id": "ORD-5678",
    "tracking_url": "https://track.example.com/5678"
  }
}

Show Schema

{
  "delivery_id": "string",
  "queued_at": 1
}

Returns a unique ID for the delivery.

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.

Note: Inbox messages are currently available for web platforms only and require the Customer.io In-App Plugin to be installed.

Body

application/json

Type: object

Responses

application/json
application/json
application/json

post/v1/send/inbox_message

{
  "transactional_message_id": "order_shipped",
  "identifiers": {
    "id": "user_123"
  },
  "message_data": {
    "order_id": "ORD-5678",
    "tracking_url": "https://track.example.com/5678",
    "product_name": "Blue Widget",
    "product_image": "https://cdn.example.com/widget.jpg"
  }
}

Show Schema

{
  "delivery_id": "string",
  "queued_at": 1
}

Returns a unique ID for the delivery.

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.

Body

application/json

- transactional_message_id
  required
  
  The transactional message template that you want to use for your message. You can call the template by its numerical ID or by the Trigger Name that you assigned to the template in the UI (case insensitive).
  
  Type: integer · ID (integer)
  
  The ID of the transactional message you want to send.
- to
  Type: stringenum
  required
  
  The person's device(s) you want to send this push to. One of all, last_used, or a custom device token which belongs to the profile from the Identifiers block. Defaults to 'all'. This overrides To from the transactional template (referenced by transactional_message_id).
  
  values
  all
  last_used
  $device_token
- identifiers
  required
  
  Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.
  
  Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.
  
  id
  Type: string
  required
  
  The identifier for the person represented by the transactional message. NOTE: If your workspace identifies people by email, use the email identifier instead.
- title
  Type: string
  
  The title for your notification. This overrides the title of the transactional template (referenced by transactional_message_id).
- message
  Type: string
  
  The message body for your notification. This overrides the notification body of the transactional template (referenced by transactional_message_id).
- image_url
  Type: string
  
  An image URL to show in the push. This overrides Image from the transactional template (referenced by transactional_message_id).
- link
  Type: string
  
  A deep link to open when the push is tapped. This overrides Link from the transactional template (referenced by transactional_message_id).
- sound
  Type: stringenum
  
  For iOS Only: your notification can alert users with the device's default notification sound or play no sound at all.
  
  values
  default
  none
- custom_data
  Type: object
  
  An optional list of key/value pairs to attach to the push payload. Due to a Firebase limitation we only support sending string key value pairs. This overrides Custom Data from the transactional template (referenced by transactional_message_id).
- custom_device
  Type: object
  
  A device to perform an upsert operation at the time of send. The device will be added/updated on the profile from the Identifiers block.
- custom_payload
  Type: object
  
  An optional list of key/value pairs to attach to the push payload. Due to a Firebase limitation we only support sending string key value pairs. This overrides every other parameter, including any Custom Payload from the transactional template (referenced by transactional_message_id).
- language
  Type: string
  
  Overrides language preferences for the person you want to send your transactional message to. Use one of our supported two- or four-letter language codes.
- message_data
  Type: object
  
  An object containing the key-value pairs referenced using liquid in your message.
- send_at
  Type: integer
  
  A unix timestamp (seconds since epoch) determining when the message will be sent. The timestamp can be up to 90 days in the future. If this value is in the past, your message is sent immediately.
- disable_message_retention
  Type: boolean
  
  If true, the message body is not retained in delivery history. Setting this value overrides the value set in the settings of your transactional_message_id.
- send_to_unsubscribed
  Type: boolean
  
  If false, your message is not sent to unsubscribed recipients. Setting this value overrides the value set in the settings of your transactional_message_id.
- queue_draft
  Type: boolean
  
  If true, your transactional message is held as a draft in Customer.io and not sent directly to your audience. You must go to the Deliveries and Drafts page to send your message.
- auto_create
  Type: boolean
  
  If true and transactional_message_id doesn't match an existing record, Customer.io creates an empty record using that value as the Trigger Name. Subsequent sends with the same value reuse the record, so they roll up under one ID in your metrics.
  
  transactional_message_id must be a string when auto_create is true. If the name already belongs to a record on a different channel, the request fails with 400. Numeric values for transactional_message_id ignore auto_create.

Responses

application/json
application/json

post/v1/send/push

{
  "transactional_message_id": 44,
  "title": "Did you really login from a new location?",
  "identifiers": {
    "id": 12345
  },
  "message_data": {
    "password_reset_token": "abcde-12345-fghij-d888",
    "account_id": "123dj"
  }
}

Show Schema

{
  "delivery_id": "string",
  "queued_at": 1
}

Returns a unique ID for the delivery.

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.

Body

application/json

- transactional_message_id
  required
  
  The transactional message template that you want to use for your message. You can call the template by its numerical ID or by the Trigger Name that you assigned to the template in the UI (case insensitive).
  
  Type: integer · ID (integer)
  
  The ID of the transactional message you want to send.
- to
  Type: string
  required
  
  The phone number you want to send your SMS to. Phone numbers must be in E.164 format (e.g., +15551234567), but you can also use liquid syntax if you store users phone numbers as attributes; you don't have to pass an E.164 formatted phone number in the call.
- identifiers
  required
  
  Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.
  
  Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.
  
  id
  Type: string
  required
  
  The identifier for the person represented by the transactional message. NOTE: If your workspace identifies people by email, use the email identifier instead.
- from
  Type: string
  
  The phone number or sender ID that your SMS is from. This must be a verified phone number in your Twilio account. This overrides the from address set within the transactional template (referenced by transactional_message_id). Phone numbers must be in E.164 format (e.g., +15551234567).
- language
  Type: string
  
  Overrides language preferences for the person you want to send your transactional message to. Use one of our supported two- or four-letter language codes.
- message_data
  Type: object
  
  An object containing the key-value pairs referenced using liquid in your message.
- send_at
  Type: integer
  
  A unix timestamp (seconds since epoch) determining when the message will be sent. The timestamp can be up to 90 days in the future. If this value is in the past, your message is sent immediately.
- disable_message_retention
  Type: boolean
  
  If true, the message body is not retained in delivery history. Setting this value overrides the value set in the settings of your transactional_message_id.
- send_to_unsubscribed
  Type: boolean
  
  If false, your message is not sent to unsubscribed recipients. Setting this value overrides the value set in the settings of your transactional_message_id.
- queue_draft
  Type: boolean
  
  If true, your transactional message is held as a draft in Customer.io and not sent directly to your audience. You must go to the Deliveries and Drafts page to send your message.
- auto_create
  Type: boolean
  
  If true and transactional_message_id doesn't match an existing record, Customer.io creates an empty record using that value as the Trigger Name. Subsequent sends with the same value reuse the record, so they roll up under one ID in your metrics.
  
  transactional_message_id must be a string when auto_create is true. If the name already belongs to a record on a different channel, the request fails with 400. Numeric values for transactional_message_id ignore auto_create.

Responses

application/json
application/json
application/json

post/v1/send/sms

{
  "transactional_message_id": "confirmation code",
  "to": "+15559876543",
  "from": "+15551234567",
  "body": "Your verification code is {{trigger.confirmation_code}}",
  "identifiers": {
    "id": "123456"
  },
  "message_data": {
    "confirmation_code": "123456",
    "account_name": "Jane Doe"
  }
}

Show Schema

{
  "delivery_id": "string",
  "queued_at": 1
}

Returns a unique ID for the delivery.

API-triggered Broadcasts (Collapsed)

In the UI, we frequently refer to broadcasts that you trigger through these endpoints as "API triggered" broadcasts. Use these endpoints to trigger a broadcast and retrieve information about broadcast triggers. When you trigger a broadcast, you can include data that you reference in your message (using a liquid {{trigger.<property>}} filter).

While you can trigger and look up information about broadcasts using the API, you must perform all other create, update, and/or delete operations through the UI.

API-triggered Broadcasts Operations

get/v1/campaigns/{broadcast_id}/triggers/{trigger_id}/errors
get/v1/broadcasts
get/v1/broadcasts/{broadcast_id}
get/v1/campaigns/{broadcast_id}/triggers/{trigger_id}
get/v1/broadcasts/{broadcast_id}/metrics
get/v1/broadcasts/{broadcast_id}/metrics/links
get/v1/broadcasts/{broadcast_id}/actions
get/v1/broadcasts/{broadcast_id}/messages
get/v1/broadcasts/{broadcast_id}/actions/{action_id}
put/v1/broadcasts/{broadcast_id}/actions/{action_id}
get/v1/broadcasts/{broadcast_id}/actions/{action_id}/language/{language}
put/v1/broadcasts/{broadcast_id}/actions/{action_id}/language/{language}
get/v1/broadcasts/{broadcast_id}/actions/{action_id}/metrics
get/v1/broadcasts/{broadcast_id}/actions/{action_id}/metrics/links
get/v1/broadcasts/{broadcast_id}/triggers

Transactional Messages (Collapsed)

Send, and return information about, transactional messages. Transactional messages are messages that your audience explicitly requests or expects, like purchase receipts or password reset requests.

The transactional_id in requests represents the transactional message template. Each individual send—the instance of a message sent to an individual person—is called a "delivery".

Transactional Messages Operations

get/v1/transactional
get/v1/transactional/{transactional_id}
get/v1/transactional/{transactional_id}/contents
put/v1/transactional/{transactional_id}/content/{content_id}
get/v1/transactional/{transactional_id}/language/{language}
put/v1/transactional/{transactional_id}/language/{language}
get/v1/transactional/{transactional_id}/metrics
get/v1/transactional/{transactional_id}/metrics/links
get/v1/transactional/{transactional_id}/messages

Customers (Collapsed)

Find people (referred to as "customers" in our APIs), their attributes, the segments they belong to, etc. Use the track API to add people to your workspace and assign their attributes.

Customers Operations

get/v1/customers
post/v1/customers
get/v1/customers/{customer_id}/attributes
get/v1/customers/{customer_id}/relationships
post/v1/customers/attributes
get/v1/customers/{customer_id}/segments
get/v1/customers/{customer_id}/messages
get/v1/customers/{customer_id}/activities
get/v1/customers/{customer_id}/subscription_preferences

Objects (Collapsed)

Objects are "groups" that you can relate people to in Customer.io—like the companies they work for, the online classes they take, and so on. These APIs help you find objects, their attributes, the people they're related to, etc. Use the track API v1 or the Track v2 API to add and relate people to objects to your workspace and assign their attributes.

Objects Operations

get/v1/object_types
post/v1/objects
get/v1/objects/{object_type_id}/{object_id}/relationships
get/v1/objects/{object_type_id}/{object_id}/attributes

Campaigns (Collapsed)

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.

Campaigns Operations

get/v1/campaigns
get/v1/campaigns/{campaign_id}
get/v1/campaigns/{campaign_id}/metrics
get/v1/campaigns/{campaign_id}/metrics/links
get/v1/campaigns/{campaign_id}/actions
get/v1/campaigns/{campaign_id}/messages
get/v1/campaigns/{campaign_id}/actions/{action_id}
put/v1/campaigns/{campaign_id}/actions/{action_id}
get/v1/campaigns/{campaign_id}/actions/{action_id}/language/{language}
put/v1/campaigns/{campaign_id}/actions/{action_id}/language/{language}
get/v1/campaigns/{campaign_id}/actions/{action_id}/metrics
get/v1/campaigns/{campaign_id}/actions/{action_id}/metrics/links
get/v1/campaigns/{campaign_id}/journey_metrics

Newsletters (Collapsed)

A newsletter is a type of broadcast in Customer.io—a one-time, single message that you send to a group of people. You can also set your newsletter up with A/B test variants and/or translations.

Use the newsletter endpoints to create, send, schedule, translate, A/B test, and get metrics for newsletters.

If your newsletters include assets like images or PDFs, host them in your workspace's assets or at another public URL, and include the URL in your message content.

Newsletters Operations

get/v1/newsletters
post/v1/newsletters
get/v1/newsletters/{newsletter_id}
delete/v1/newsletters/{newsletter_id}

Segments (Collapsed)

Segments are groups of people, subsets of your audience. You get get information about segments and the customers contained by a segment. You can also create or delete manual segments through the API. Use the UI to create, update, or delete data-driven segments.

Segments Operations

post/v1/segments
get/v1/segments
get/v1/segments/{segment_id}
delete/v1/segments/{segment_id}
get/v1/segments/{segment_id}/used_by
get/v1/segments/{segment_id}/customer_count
get/v1/segments/{segment_id}/membership

Messages (Collapsed)

Return information about message and webhook "deliveries"—the instance of a message or webhook intended for an individual recipient.

Messages Operations

get/v1/messages
get/v1/messages/{message_id}
get/v1/messages/{message_id}/archived_message

Design Studio (Collapsed)

Use these endpoints to manage emails, translations, and components made with Design Studio. You can programmatically manage Design Studio content and migrate templates from an external service. To manage assets like images, use the Assets API.

These endpoints do not enable you to publish changes to connected workflows like campaigns, nor can you update global styles. They're only for content management at this time. Learn more about the best practices for sending HTML through these endpoints.

If you're an external tool and interested in being listed as one of our integrated partners, please reach out to product@customer.io to chat with a Product Manager!

Assets (Collapsed)

Manage file assets such as images and PDFs and organize them into folders.

Assets Operations

get/v1/assets
post/v1/assets/files
get/v1/assets/files/{id}
put/v1/assets/files/{id}
delete/v1/assets/files/{id}
get/v1/assets/folders
post/v1/assets/folders
get/v1/assets/folders/{id}
put/v1/assets/folders/{id}
delete/v1/assets/folders/{id}

Exports (Collapsed)

Export information about people, deliveries, etc. You can also download existing exports from these endpoints.

Exports Operations

get/v1/exports
get/v1/exports/{export_id}
get/v1/exports/{export_id}/download
post/v1/exports/customers
post/v1/exports/deliveries

Activities (Collapsed)

Return information about activities. Activities are cards in campaigns, broadcasts, etc. They might be messages, webhooks, attribute changes, etc.

Activities Operations

get/v1/activities

Sender Identities (Collapsed)

Return information about your senders—the addresses that you send messages from—including usage information for your different senders.

Sender Identities Operations

get/v1/sender_identities
get/v1/sender_identities/{sender_id}
get/v1/sender_identities/{sender_id}/used_by

Reporting Webhooks (Collapsed)

Set up webhooks to inform an external service about Customer.io events. Webhooks can notify you immediately when immediately when customer attributes change or when people open your messages.

Reporting Webhooks Operations

post/v1/reporting_webhooks
get/v1/reporting_webhooks
get/v1/reporting_webhooks/{webhook_id}
put/v1/reporting_webhooks/{webhook_id}
delete/v1/reporting_webhooks/{webhook_id}

Snippets (Collapsed)

Snippets are reusable pieces of messages, like a common email footer or link that you use in your messages. Use these endpoints to create, get, or delete snippets.

Snippets Operations

get/v1/snippets
post/v1/snippets
put/v1/snippets
delete/v1/snippets/{snippet_name}

Info (Collapsed)

Returns the list of addresses used by Customer.io. You must add add these addresses to your allowlist when using a custom SMTP provider and blocking unknown IP addresses.

Info Operations

get/v1/info/ip_addresses

Collections (Collapsed)

Collections are arbitrary sets of data that you want to use in campaign messages or workflows independent of attributes or events. They might represent things like upcoming events, coupons/promotions, etc.

Collections Operations

post/v1/collections
get/v1/collections
get/v1/collections/{collection_id}
delete/v1/collections/{collection_id}
put/v1/collections/{collection_id}
get/v1/collections/{collection_id}/content
put/v1/collections/{collection_id}/content

ESP Suppression (Collapsed)

If you use Customer.io as your email service provider (ESP), these endpoints help you retrieve information about email addresses suppressed directly by the ESP. ESP-based suppressions are different from suppression in Customer.io: these are addresses that the ESP suppressed automatically because a message bounced, a customer requested they not be contacted again, etc. These are not addresses that you deleted and suppressed either in our UI or through the API.

ESP Suppression Operations

get/v1/esp/search_suppression/{email_address}
get/v1/esp/suppression/{suppression_type}
get/v1/esp/domains/{domain_name}/suppression/{suppression_type}
delete/v1/esp/suppression/{suppression_type}/{email_address}
post/v1/esp/suppression/{suppression_type}/{email_address}

Imports (Collapsed)

APIs to upload CSV files containing lists of people. These endpoints provide a convenient way to add and update people without having to make an identify call for each individual person.

Imports Operations

post/v1/imports
get/v1/imports/{import_id}

Subscription Center (Collapsed)

A subscription center differentiates the types of messages available for your product. Your audience sets subscription preferences by name, but we record subscription preferences by topic ID. You can use these endpoints to get a list of topics and names, helping you understand your audience's subscription preferences.

Subscription Center Operations

get/v1/subscription_topics
get/v1/subscription_center/{customer_id}/token
get/v1/subscription_channels

Workspaces (Collapsed)

An API to retrieve information about your workspaces in your account. You can use this to look up counts for messages sent, monthly billable emails sent, people, and objects.

Workspaces Operations

get/v1/workspaces

Data Index (Collapsed)

Update descriptions for attributes and events in your workspace. This helps improve AI-generated content and segments.

Data Index Operations

post/v1/data_index/attributes
post/v1/data_index/events

Journeys App API

Overview

Use our Postman collection

Server addresses: US and EU

Authentication

Rate Limits

Authentication

Send Messages

API triggered broadcast limits

Transactional Message Limits

Send an API-triggered broadcast

Send a newsletter

Schedule a newsletter

Send a transactional email

Send a transactional in-app message

Send a transactional inbox message

Send a transactional push

Send a transactional SMS

API-triggered Broadcasts (Collapsed)

Transactional Messages (Collapsed)

Customers (Collapsed)

Objects (Collapsed)

Campaigns (Collapsed)

Newsletters (Collapsed)

Newsletter Variants (Collapsed)

Newsletter Metrics (Collapsed)

Segments (Collapsed)

Messages (Collapsed)

Design Studio (Collapsed)

Assets (Collapsed)

Exports (Collapsed)

Activities (Collapsed)

Sender Identities (Collapsed)

Reporting Webhooks (Collapsed)

Snippets (Collapsed)

Info (Collapsed)

Collections (Collapsed)

ESP Suppression (Collapsed)

Imports (Collapsed)

Subscription Center (Collapsed)

Workspaces (Collapsed)

Data Index (Collapsed)