Journeys App API

Download OpenAPI specification:Download

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 transactional messages and trigger broadcasts. In both cases, 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.

You're looking at our US regional endpoints

The only difference in our US and European Union (EU) regions is the subdomain—api-eu for our EU region as rather than app.customer.io/v1 for the US; there are no other differences between the two regions. If your account is based in the European Union (EU) data center, click here to show EU endpoints in our code samples and documentation below.

If you don't know your region, you can find your account region on your account's privacy page, or get your region using the API.

You're looking at our EU regional endpoints

The only difference in our US and European Union (EU) regions is the subdomain—api for our US region rather than api-eu.customer.io/v1 for our EU region; there are no other differences between the two regions. If your account is based in the European Union (EU) data center, you can click here to to show US endpoints in our code samples and documentation below.

Note that if your account is based in the United States (US) data center and you send requests to the EU region (the track-eu subdomain), your requests will fail. If you don't know your region, you can find your account region on your account's privacy page, or get your region using the API.

Customer.io hosts services in the United States (US) and European Union (EU, host subdomains are suffixed with -eu). Select the appropriate region for server addresses that apply to your region.

Host/ServerPurpose
https://api.customer.io/Use the App API to send Transactional messages and API triggered broadcasts. This API uses bearer token authorization, helping you control who uses it. Most requests to this API are limited to 10 pers second. The exceptions are API-triggered broadcasts, which are limited to 1 request every 10 seconds, and Transactional messages which are limited to 100 per second.

Use our Postman collection

We've generated a Postman collection with all of our APIs—not just the ones on this page—with a starter environment (called "CIO Env") containing variables for authorization and path parameters.

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 server variables (track_api_url and app_api_url).

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.

Bearer Auth

The App API uses a bearer authentication scheme.

You can generate a bearer token, known as an App API Key, with a defined scope in your account settings. Learn more about bearer authorization in Customer.io.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

App API limits

Aside from Transactional and Broadcast trigger endpoints, this API is limited to 10 requests per second. The transactional email endpoint is limited to 100 requests per second. The API-triggered broadcast endpoint is limited to 1 request every 10 seconds.

Send Messages

These two endpoints trigger messages to your audience. They use the same authentication method, but have different limits than the rest of the endpoints.

Trigger a broadcast

Manually trigger a broadcast, and provide data to populate messages in your trigger. The shape of the request changes based on the type of audience you broadcast to: a segment, a list of emails, a list of customer IDs, a map of users, or a data file. You can reference properties in the data object from this request 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. 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.

Authorization:
path Parameters
broadcast_id
required
integer

The ID of the broadcast that you want to trigger.

Request Body: application/json
One of
object

Contains information you want to use to populate your broadcast.

email_add_duplicates
boolean
Default: false

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

email_ignore_missing
boolean
Default: false

If false a missing email address is an error.

id_ignore_missing
boolean
Default: false

If false, a missing customer ID is an error.

Responses

Request samples

Content type
application/json
Example
{
  • "data": {
    • "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": false,
  • "email_ignore_missing": false,
  • "id_ignore_missing": false
}

Response samples

Content type
application/json
{
  • "id": 3
}

Send a transactional email

Send a transactional email. You can send a message using a transactional_message_id or send your own body, subject, and from 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.

If you want to send your own body, subject, and from values to populate your message at send time, we recommend that you pass a transactional_message_id anyway; the values you pass in the request will override 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.

Customer.io attributes metrics to a transactional_message_id; if you don't provide a transactional_message_id, we attribute metrics to "transactional_message_id": 1. You can create empty transactional messages in the UI and override the body, subject, and from values at send time. This provides flexibility in your integration and lets you organize metrics (rather than gathering metrics for all of your transactional messages against a single ID).

Authorization:
Request Body: application/json
One of
required
integer or string

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 the template (case insensitive).

to
required
string

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

required
object

Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.

body
string

The HTML body of your message. This overrides the body of the transactional template (referenced by transactional_message_id). 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
string

If your message is an email, this is the AMP-enabled body of your message. If your recipient's email client doesn't support AMP, the body represents your fallback message.

body_plain
string

The plaintext body of your message. This overrides the body of your transactional template (referenced by transactional_message_id).

subject
string

The subject line for your message. This overrides the subject of the transactional template (referenced by transactional_message_id).

from
string

The address that your email is from. This address must be verified by Customer.io. This overrides the from address set within the transactional template (referenced by transactional_message_id). 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>.

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

object

An object containing the key-value pairs referenced using liquid in your message.

send_at
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
boolean
Default: false

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
boolean
Default: true

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
boolean
Default: false

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.

bcc
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
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
string

The address that recipients can reply to, if different from the from address.

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

Array of objects

A dictionary of attachments where the filename is the key and the value is the base64-encoded contents. The total size of all attachments must be less than 2 MB. Some filetype extensions are restricted.

Array of objects

Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten.

disable_css_preprocessing
boolean
Default: false

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
boolean
Default: true

If true, Customer.io tracks opens and link clicks in your message.

Responses

Request samples

Content type
application/json
Example
{
  • "transactional_message_id": 44,
  • "to": "cool.person@example.com",
  • "from": "override-templated-address@example.com",
  • "subject": "Did you really login from a new location?",
  • "identifiers": {
    • "email": "cool.person@example.com"
    },
  • "message_data": {
    • "password_reset_token": "abcde-12345-fghij-d888",
    • "account_id": "123dj"
    },
  • "bcc": "bcc@example.com",
  • "disable_message_retention": false,
  • "send_to_unsubscribed": true,
  • "tracked": true,
  • "queue_draft": false,
  • "disable_css_preprocessing": true
}

Response samples

Content type
application/json
{
  • "delivery_id": "string",
  • "queued_at": 0
}

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.

Authorization:
Request Body: application/json
required
integer or string

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 the template (case insensitive).

to
required
string
Default: "all"
Enum: "all" "last_used" "$device_token"

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

required
object

Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.

title
string

The title for your notification. This overrides the title of the transactional template (referenced by transactional_message_id).

message
string

The message body for your notification. This overrides the notification body of the transactional template (referenced by transactional_message_id).

image_url
string

An image URL to show in the push. This overrides Image from the transactional template (referenced by transactional_message_id).

link
string

A deep link to open when the push is tapped. This overrides Link from the transactional template (referenced by transactional_message_id).

sound
string
Default: "default"
Enum: "default" "none"

For iOS Only: your notification can alert users with the device's default notification sound or play no sound at all.

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

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.

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

object

An object containing the key-value pairs referenced using liquid in your message.

send_at
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
boolean
Default: false

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
boolean
Default: true

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
boolean
Default: false

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.

Responses

Request samples

Content type
application/json
{
  • "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"
    }
}

Response samples

Content type
application/json
{
  • "delivery_id": "string",
  • "queued_at": 0
}

Message sending limits

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 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-email (transactional email) endpoint is limited to 100 requests per second.

Data Type Limit Description
Payload 1MB Max length of the payload, excepting attachments
Attachments 2MB Maximum size of attachments
Recipients 15 Total number of recipients across the to and bcc fields.

Activities

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

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.

Authorization:
query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

type
string
Enum: "attempted_action" "attribute_change" "failed_attribute_change" "failed_batch_update" "skipped_update" "failed_query_collection" … 48 more
Example: type=sent_email

The type of activity you want to search for. Types with _o:<object_type_id> are for objects and types with _r:<object_type_id> are for relationships.

name
string
Example: name=something_happened

The name of the event or attribute you want to return.

deleted
boolean
Default: false

If true, return results for deleted people.

customer_id
string

The identifier of the person you want to look up. By default, this is a person's id. You can use the id_type parameter to look up a person by email or cio_id.

If you use a person's cio_id, you must prefix the value value with cio_ when using it to find or reference a person (i.e. cio_03000010 for a cio_id value of 03000010).

id_type
string
Enum: "id" "email" "cio_id"

The type of customer_id you want to use to reference a person. If you don't provide this parameter, we assume that the customer_id in your request is a person's id.

limit
integer <= 100
Default: 10

The maximum number of results you want to retrieve per page.

Responses

Request samples

curl --request GET \
  --url 'https://api.customer.io/v1/activities?start=SOME_STRING_VALUE&type=sent_email&name=something_happened&deleted=SOME_BOOLEAN_VALUE&customer_id=SOME_STRING_VALUE&id_type=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE'

Response samples

Content type
application/json
{
  • "activities": [
    • {
      }
    ],
  • "next": "string"
}

Broadcasts

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.

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.

Authorization:
path Parameters
broadcast_id
required
integer

The ID of the broadcast that you want to return information about.

trigger_id
required
integer
Example: 3

The ID of the campaign trigger that you want to return information for.

query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer

The maximum number of results you want to retrieve per page.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/campaigns/{broadcast_id}/triggers/{trigger_id}/errors

Response samples

Content type
application/json
{
  • "errors": [
    • "string"
    ],
  • "next": "string"
}

List broadcasts

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

Authorization:

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/broadcasts

Response samples

Content type
application/json
{
  • "broadcasts": [
    • {
      }
    ]
}

Get a broadcast

Returns metadata for an individual broadcast.

Authorization:
path Parameters
broadcast_id
required
integer

The identifier of a broadcast.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/broadcasts/{broadcast_id}

Response samples

Content type
application/json
{
  • "broadcast": {
    • "id": 2,
    • "deduplicate_id": "2:1520467200",
    • "created": 1520467200,
    • "type": "triggered_broadcast",
    • "updated": 1520467200,
    • "name": "basic",
    • "active": true,
    • "state": "running",
    • "actions": [
      ],
    • "tags": "nil",
    • "first_started": 1520467200,
    • "created_by": "ExamplePerson"
    }
}

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.

Authorization:
path Parameters
broadcast_id
required
integer

The ID of the broadcast that you want to return information about.

trigger_id
required
integer
Example: 3

The ID of the campaign trigger that you want to return information for.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/campaigns/{broadcast_id}/triggers/{trigger_id}

Response samples

Content type
application/json
{
  • "id": 0,
  • "broadcast_id": 2,
  • "created_at": 1552341937,
  • "processed_at": 0
}

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.

Authorization:
path Parameters
broadcast_id
required
integer

The identifier of a broadcast.

query Parameters
period
string
Default: "days"
Enum: "hours" "days" "weeks" "months"

The unit of time for your report.

steps
integer

The number of periods you want to return. Defaults to the maximum available, or 12 if the period is in months. Maximums are 24 hours, 45 days, 12 weeks, or 120 months.

type
string
Enum: "email" "webhook" "twilio" "slack" "push" "in_app"

The type of item you want to return metrics for. When empty, the response contains metrics for all possible types.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/broadcasts/{broadcast_id}/metrics

Response samples

Content type
application/json
{
  • "metric": {
    • "series": {
      }
    }
}

List broadcast actions

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

Authorization:
path Parameters
broadcast_id
required
integer

The identifier of a broadcast.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/broadcasts/{broadcast_id}/actions

Response samples

Content type
application/json
{
  • "actions": [
    • {
      }
    ]
}

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.

Authorization:
path Parameters
broadcast_id
required
integer

The identifier of a broadcast.

query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer

The maximum number of results you want to retrieve per page.

metric
string
Enum: "attempted" "sent" "delivered" "opened" "clicked" "converted" … 6 more

Determines the metric(s) you want to return.

state
string
Enum: "failed" "sent" "drafted" "attempted"

The state of a broadcast.

type
string
Enum: "email" "webhook" "twilio" "slack" "push" "in_app"

The type of item you want to return metrics for. When empty, the response contains metrics for all possible types.

start_ts
integer <unix timestamp>

The beginning timestamp for your query.

end_ts
integer <unix timestamp>

The ending timestamp for your query.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/broadcasts/{broadcast_id}/messages

Response samples

Content type
application/json
{
  • "messages": [
    • {
      }
    ]
}

Get a broadcast action

Returns information about a specific action within a broadcast.

Authorization:
path Parameters
broadcast_id
required
integer

The identifier of a broadcast.

action_id
required
integer

The action you want to lookup or act on.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/broadcasts/{broadcast_id}/actions/{action_id}

Response samples

Content type
application/json
{
  • "action": {
    • "id": 96,
    • "broadcast_id": 2,
    • "deduplicate_id": "15:1492548073",
    • "name": "Opening Message",
    • "layout": "string",
    • "created": 1552341937,
    • "updated": 1552341937,
    • "body": "string",
    • "type": "email",
    • "sending_state": "automatic",
    • "language": "fr",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ],
    • "body_amp": "string"
    }
}

Update a broadcast action

Update the contents of a broadcast action, including the body of messages or HTTP requests.

Authorization:
path Parameters
broadcast_id
required
integer

The identifier of a broadcast.

action_id
required
integer

The action you want to lookup or act on.

Request Body: application/json
One of
body
string

The body of the action. You cannot modify the body if you created it with our drag-and-drop editor.

sending_state
string
Enum: "automatic" "draft" "off"

Determines the sending behavior for the action. automatic sends the action automatically when triggered; draft queues drafts when the action is triggered; or off to disable the action.

from_id
integer

The identifier of the from address, commonly known as the "sender". You can list your sender identities to match the ID to a specific address.

reply_to_id
integer Nullable

The identifier for the reply_to address, if applicable. You can list your sender identities to match the ID to a specific address.

recipient
string

The recipient address for an action.

subject
string

The subject line for an email action.

preheader_text
string

Also known as "preview text", this specifies the small block of text shown in an end-user's email inbox, next to, or underneath, the subject line.

Array of objects

Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten.

body_amp
string

If your message is an email, this is the AMP-enabled body of your message. If your recipient's email client doesn't support AMP, the body represents your fallback message.

Responses

Request samples

Content type
application/json
Example
{
  • "body": "string",
  • "sending_state": "automatic",
  • "from_id": 1,
  • "reply_to_id": 38,
  • "recipient": "{{customer.email}}",
  • "subject": "Did you get that thing I sent you?",
  • "preheader_text": "string",
  • "headers": [
    • {
      }
    ],
  • "body_amp": "string"
}

Response samples

Content type
application/json
{
  • "action": {
    • "id": 96,
    • "broadcast_id": 2,
    • "deduplicate_id": "15:1492548073",
    • "name": "Opening Message",
    • "layout": "string",
    • "created": 1552341937,
    • "updated": 1552341937,
    • "body": "string",
    • "type": "email",
    • "sending_state": "automatic",
    • "language": "fr",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ],
    • "body_amp": "string"
    }
}

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.

Authorization:
path Parameters
broadcast_id
required
integer

The identifier of a broadcast.

action_id
required
integer

The action you want to lookup or act on.

language
string

A language tag of a language variant. If you don't provide a language, we target your default template. If the language variant does not exist, we throw an error.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/broadcasts/{broadcast_id}/actions/{action_id}/language/{language}

Response samples

Content type
application/json
{
  • "action": {
    • "id": 96,
    • "broadcast_id": 2,
    • "deduplicate_id": "15:1492548073",
    • "name": "Opening Message",
    • "layout": "string",
    • "created": 1552341937,
    • "updated": 1552341937,
    • "body": "string",
    • "type": "email",
    • "sending_state": "automatic",
    • "language": "fr",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ],
    • "body_amp": "string"
    }
}

Update a translation of a broadcast message

Update a translation of a specific broadcast action, including the body of messages or HTTP requests.

Authorization:
path Parameters
broadcast_id
required
integer

The identifier of a broadcast.

action_id
required
integer

The action you want to lookup or act on.

language
string

A language tag of a language variant. If you don't provide a language, we target your default template. If the language variant does not exist, we throw an error.

Request Body: application/json
One of
body
string

The body of the action. You cannot modify the body if you created it with our drag-and-drop editor.

sending_state
string
Enum: "automatic" "draft" "off"

Determines the sending behavior for the action. automatic sends the action automatically when triggered; draft queues drafts when the action is triggered; or off to disable the action.

from_id
integer

The identifier of the from address, commonly known as the "sender". You can list your sender identities to match the ID to a specific address.

reply_to_id
integer Nullable

The identifier for the reply_to address, if applicable. You can list your sender identities to match the ID to a specific address.

recipient
string

The recipient address for an action.

subject
string

The subject line for an email action.

preheader_text
string

Also known as "preview text", this specifies the small block of text shown in an end-user's email inbox, next to, or underneath, the subject line.

Array of objects

Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten.

body_amp
string

If your message is an email, this is the AMP-enabled body of your message. If your recipient's email client doesn't support AMP, the body represents your fallback message.

Responses

Request samples

Content type
application/json
Example
{
  • "body": "string",
  • "sending_state": "automatic",
  • "from_id": 1,
  • "reply_to_id": 38,
  • "recipient": "{{customer.email}}",
  • "subject": "Did you get that thing I sent you?",
  • "preheader_text": "string",
  • "headers": [
    • {
      }
    ],
  • "body_amp": "string"
}

Response samples

Content type
application/json
{
  • "action": {
    • "id": 96,
    • "broadcast_id": 2,
    • "deduplicate_id": "15:1492548073",
    • "name": "Opening Message",
    • "layout": "string",
    • "created": 1552341937,
    • "updated": 1552341937,
    • "body": "string",
    • "type": "email",
    • "sending_state": "automatic",
    • "language": "fr",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ],
    • "body_amp": "string"
    }
}

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.

Authorization:
path Parameters
broadcast_id
required
integer

The identifier of a broadcast.

action_id
required
integer

The action you want to lookup or act on.

query Parameters
period
string
Default: "days"
Enum: "hours" "days" "weeks" "months"

The unit of time for your report.

steps
integer

The number of periods you want to return. Defaults to the maximum available, or 12 if the period is in months. Maximums are 24 hours, 45 days, 12 weeks, or 120 months.

type
string
Enum: "email" "webhook" "twilio" "slack" "push" "in_app"

The type of item you want to return metrics for. When empty, the response contains metrics for all possible types.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/broadcasts/{broadcast_id}/actions/{action_id}/metrics

Response samples

Content type
application/json
{
  • "metric": {
    • "series": {
      }
    }
}

Get broadcast triggers

Returns a list of the triggers for a broadcast.

Authorization:
path Parameters
broadcast_id
required
integer

The identifier of a broadcast.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/broadcasts/{broadcast_id}/triggers

Response samples

Content type
application/json
{
  • "triggers": [
    • {
      }
    ]
}

Campaigns

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.

List campaigns

Returns a list of your campaigns and associated metadata.

Authorization:

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/campaigns

Response samples

Content type
application/json
{
  • "campaigns": [
    • {
      }
    ]
}

Get a campaign

Returns metadata for an individual campaign.

Authorization:
path Parameters
campaign_id
required
integer
Example: 2

The ID of the campaign that you want to trigger or return information about.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/campaigns/{campaign_id}

Response samples

Content type
application/json
{
  • "campaign": {
    • "id": 5,
    • "deduplicate_id": "15:1492548073",
    • "name": "string",
    • "type": "segment",
    • "created": 1552341937,
    • "updated": 1552341937,
    • "active": true,
    • "state": "running",
    • "actions": [
      ],
    • "first_started": 1552341937,
    • "tags": [
      ],
    • "trigger_segment_ids": [
      ],
    • "filter_segment_ids": [
      ],
    • "msg_templates": [
      ]
    }
}

Get campaign metrics

Returns a list of metrics for an individual campaign 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.

Authorization:
path Parameters
campaign_id
required
integer
Example: 2

The ID of the campaign that you want to trigger or return information about.

query Parameters
period
string
Default: "days"
Enum: "hours" "days" "weeks" "months"

The unit of time for your report.

steps
integer

The number of periods you want to return. Defaults to the maximum available, or 12 if the period is in months. Maximums are 24 hours, 45 days, 12 weeks, or 120 months.

type
string
Enum: "email" "webhook" "twilio" "slack" "push" "in_app"

The type of item you want to return metrics for. When empty, the response contains metrics for all possible types.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/campaigns/{campaign_id}/metrics

Response samples

Content type
application/json
{
  • "metric": {
    • "series": {
      }
    }
}

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.

Authorization:
path Parameters
campaign_id
required
integer
Example: 2

The ID of the campaign that you want to trigger or return information about.

query Parameters
period
string
Default: "days"
Enum: "hours" "days" "weeks" "months"

The unit of time for your report.

steps
integer

The number of periods you want to return. Defaults to the maximum available, or 12 if the period is in months. Maximums are 24 hours, 45 days, 12 weeks, or 120 months.

unique
boolean
Default: false

If true, the response contains only unique customer results, i.e. a customer who clicks a link twice is only counted once. If false, the response contains the total number of results without regard to uniqueness.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/campaigns/{campaign_id}/metrics/links

Response samples

Content type
application/json
{}

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.

Authorization:
path Parameters
campaign_id
required
integer
Example: 2

The ID of the campaign that you want to trigger or return information about.

query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/campaigns/{campaign_id}/actions

Response samples

Content type
application/json
{
  • "actions": [
    • {
      }
    ],
  • "next": "string"
}

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.

Authorization:
path Parameters
campaign_id
required
integer
Example: 2

The ID of the campaign that you want to trigger or return information about.

query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer <= 1000
Default: 50

The maximum number of results you want to retrieve per page.

type
string
Enum: "email" "webhook" "twilio" "slack" "push" "in_app"

The type of item you want to return metrics for. When empty, the response contains metrics for all possible types.

metric
string
Enum: "attempted" "sent" "delivered" "opened" "clicked" "converted" … 6 more

Determines the metric(s) you want to return.

drafts
boolean

If true, your request returns drafts rather than active/sent messages.

start_ts
integer <unix timestamp>

The beginning timestamp for your query.

end_ts
integer <unix timestamp>

The ending timestamp for your query.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/campaigns/{campaign_id}/messages

Response samples

Content type
application/json
{
  • "messages": [
    • {
      }
    ]
}

Get a campaign action

Returns information about a specific action in a campaign.

Authorization:
path Parameters
campaign_id
required
integer
Example: 2

The ID of the campaign that you want to trigger or return information about.

action_id
required
integer

The action you want to lookup or act on.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/campaigns/{campaign_id}/actions/{action_id}

Response samples

Content type
application/json
{
  • "action": {
    • "id": 96,
    • "campaign_id": 5,
    • "parent_action_id": 1,
    • "deduplicate_id": "15:1492548073",
    • "name": "Opening Message",
    • "layout": "string",
    • "created": 1552341937,
    • "updated": 1552341937,
    • "body": "string",
    • "body_amp": "string",
    • "language": "fr",
    • "type": "email",
    • "sending_state": "automatic",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ]
    }
}

Update a campaign action

Update the contents of a campaign action, including the body of messages and HTTP requests.

Authorization:
path Parameters
campaign_id
required
integer
Example: 2

The ID of the campaign that you want to trigger or return information about.

action_id
required
integer

The action you want to lookup or act on.

Request Body: application/json
One of
body
string

The body of the action. For emails, this is the HTML-body of a message. You cannot modify the body if you created it with our drag-and-drop editor.

body_amp
string

If your message is an email, this is the AMP-enabled body of your message. If your recipient's email client doesn't support AMP, the body represents your fallback message.

sending_state
string
Enum: "automatic" "draft" "off"

Determines the sending behavior for the action. automatic sends the action automatically when triggered; draft queues drafts when the action is triggered; or off to disable the action.

from_id
integer

The identifier of the from address, commonly known as the "sender". You can list your sender identities to match the ID to a specific address.

reply_to_id
integer Nullable

The identifier for the reply_to address, if applicable. You can list your sender identities to match the ID to a specific address.

recipient
string

The recipient address for an action.

subject
string

The subject line for an email action.

preheader_text
string

Also known as "preview text", this specifies the small block of text shown in an end-user's email inbox, next to, or underneath, the subject line.

Array of objects

Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten.

Responses

Request samples

Content type
application/json
Example
{
  • "body": "string",
  • "body_amp": "string",
  • "sending_state": "automatic",
  • "from_id": 1,
  • "reply_to_id": 38,
  • "recipient": "{{customer.email}}",
  • "subject": "Did you get that thing I sent you?",
  • "preheader_text": "string",
  • "headers": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "action": {
    • "id": 96,
    • "campaign_id": 5,
    • "parent_action_id": 1,
    • "deduplicate_id": "15:1492548073",
    • "name": "Opening Message",
    • "layout": "string",
    • "created": 1552341937,
    • "updated": 1552341937,
    • "body": "string",
    • "body_amp": "string",
    • "language": "fr",
    • "type": "email",
    • "sending_state": "automatic",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ]
    }
}

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.

Authorization:
path Parameters
campaign_id
required
integer
Example: 2

The ID of the campaign that you want to trigger or return information about.

action_id
required
integer

The action you want to lookup or act on.

language
string

A language tag of a language variant. If you don't provide a language, we target your default template. If the language variant does not exist, we throw an error.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/campaigns/{campaign_id}/actions/{action_id}/language/{language}

Response samples

Content type
application/json
{
  • "action": {
    • "id": 96,
    • "campaign_id": 5,
    • "parent_action_id": 1,
    • "deduplicate_id": "15:1492548073",
    • "name": "Opening Message",
    • "layout": "string",
    • "created": 1552341937,
    • "updated": 1552341937,
    • "body": "string",
    • "body_amp": "string",
    • "language": "fr",
    • "type": "email",
    • "sending_state": "automatic",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ]
    }
}

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.

Authorization:
path Parameters
campaign_id
required
integer
Example: 2

The ID of the campaign that you want to trigger or return information about.

action_id
required
integer

The action you want to lookup or act on.

language
string

A language tag of a language variant. If you don't provide a language, we target your default template. If the language variant does not exist, we throw an error.

Request Body: application/json
One of
body
string

The body of the action. For emails, this is the HTML-body of a message. You cannot modify the body if you created it with our drag-and-drop editor.

body_amp
string

If your message is an email, this is the AMP-enabled body of your message. If your recipient's email client doesn't support AMP, the body represents your fallback message.

sending_state
string
Enum: "automatic" "draft" "off"

Determines the sending behavior for the action. automatic sends the action automatically when triggered; draft queues drafts when the action is triggered; or off to disable the action.

from_id
integer

The identifier of the from address, commonly known as the "sender". You can list your sender identities to match the ID to a specific address.

reply_to_id
integer Nullable

The identifier for the reply_to address, if applicable. You can list your sender identities to match the ID to a specific address.

recipient
string

The recipient address for an action.

subject
string

The subject line for an email action.

preheader_text
string

Also known as "preview text", this specifies the small block of text shown in an end-user's email inbox, next to, or underneath, the subject line.

Array of objects

Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten.

Responses

Request samples

Content type
application/json
Example
{
  • "body": "string",
  • "body_amp": "string",
  • "sending_state": "automatic",
  • "from_id": 1,
  • "reply_to_id": 38,
  • "recipient": "{{customer.email}}",
  • "subject": "Did you get that thing I sent you?",
  • "preheader_text": "string",
  • "headers": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "action": {
    • "id": 96,
    • "campaign_id": 5,
    • "parent_action_id": 1,
    • "deduplicate_id": "15:1492548073",
    • "name": "Opening Message",
    • "layout": "string",
    • "created": 1552341937,
    • "updated": 1552341937,
    • "body": "string",
    • "body_amp": "string",
    • "language": "fr",
    • "type": "email",
    • "sending_state": "automatic",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ]
    }
}

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

Authorization:
path Parameters
campaign_id
required
integer
Example: 2

The ID of the campaign that you want to trigger or return information about.

action_id
required
integer

The action you want to lookup or act on.

query Parameters
period
string
Default: "days"
Enum: "hours" "days" "weeks" "months"

The unit of time for your report.

steps
integer

The number of periods you want to return. Defaults to the maximum available, or 12 if the period is in months. Maximums are 24 hours, 45 days, 12 weeks, or 120 months.

type
string
Enum: "email" "webhook" "twilio" "slack" "push" "in_app"

The type of item you want to return metrics for. When empty, the response contains metrics for all possible types.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/campaigns/{campaign_id}/actions/{action_id}/metrics

Response samples

Content type
application/json
{
  • "metric": {
    • "series": {
      }
    }
}

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.

Authorization:
path Parameters
campaign_id
required
integer
Example: 2

The ID of the campaign that you want to trigger or return information about.

query Parameters
start
required
integer <unix timestamp>
Example: start=1652718066

The unix timestamp for the beginning of your journey metrics report.

end
required
integer <unix timestamp>

The unix timestamp for the end of your journey metrics report.

resolution
required
string
Enum: "hours" "hourly" "days" "daily" "weeks" "weekly" … 2 more

Determines increment for journey metrics—hourly, daily, weekly, or monthly.

Responses

Request samples

curl --request GET \
--url 'https://api.customer.io/v1/campaigns/{campaign_id}/journey_metrics?start=1650151266&end=1652052066&resolution=weeks' \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "journey_metric": {
    • "started": [
      ],
    • "activated": [
      ],
    • "exited_early": [
      ],
    • "finished": [
      ],
    • "converted": [
      ],
    • "never_activated": [
      ],
    • "messaged": [
      ]
    }
}

Collections

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.

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.

Authorization:
Request Body: application/json
One of
name
required
string

The name of the collection. This is how you'll reference your collection in messages—{{collection_name.data-property}}.

required
Array of objects

An array of data objects that you want to reference in this collection.

Responses

Request samples

Content type
application/json
{
  • "name": "events",
  • "data": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "collection": {
    • "bytes": 296,
    • "created_at": 1552341937,
    • "updated_at": 1552341937,
    • "id": 1,
    • "name": "upcoming events",
    • "rows": 2,
    • "schema": [
      ]
    }
}

List your collections

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

Authorization:

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/collections

Response samples

Content type
application/json
{
  • "collections": [
    • {
      }
    ]
}

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

Authorization:
path Parameters
collection_id
required
integer

The identifier for a collection.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/collections/{collection_id}

Response samples

Content type
application/json
{
  • "collection": {
    • "bytes": 296,
    • "created_at": 1552341937,
    • "updated_at": 1552341937,
    • "id": 1,
    • "name": "upcoming events",
    • "rows": 2,
    • "schema": [
      ]
    }
}

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.

Authorization:
path Parameters
collection_id
required
integer

The identifier for a collection.

Responses

Request samples

curl --request DELETE \
  --url https://api.customer.io/v1/collections/{collection_id}

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.
Authorization:
path Parameters
collection_id
required
integer

The identifier for a collection.

Request Body: application/json
One of
name
string

The name of the collection. This is how you'll reference your collection in messages—{{collection_name.data-property}}.

Array of objects

An array of data objects that you want to reference in this collection.

Responses

Request samples

Content type
application/json
{
  • "name": "events",
  • "data": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "collection": {
    • "bytes": 296,
    • "created_at": 1552341937,
    • "updated_at": 1552341937,
    • "id": 1,
    • "name": "upcoming events",
    • "rows": 2,
    • "schema": [
      ]
    }
}

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.

Authorization:
path Parameters
collection_id
required
integer

The identifier for a collection.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/collections/{collection_id}/content

Response samples

Content type
application/json
{
  • "eventName": "christmas",
  • "eventDate": "2021-12-25T12:00:00.000Z",
  • "presents": {
    • "something_you_want": "toys",
    • "something_you_need": "socks",
    • "total": 2
    }
}

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

Note: A collection cannot be more than 10 MB in size. No individual row in the collection can be more than 10 KB.

Authorization:
path Parameters
collection_id
required
integer

The identifier for a collection.

Request Body: application/json

Your request is a free form object representing the contents of your collection. This request replaces the contents of the collection entirely, so include all contents that you want to remain in the collection—whether they change or not.

collection contents*
any

Responses

Request samples

Content type
application/json
{
  • "eventName": "christmas",
  • "eventDate": "2021-12-25T12:00:00.000Z",
  • "presents": {
    • "something_you_want": "toys",
    • "something_you_need": "socks",
    • "total": 2
    }
}

Response samples

Content type
application/json
{
  • "collection": {
    • "bytes": 296,
    • "created_at": 1552341937,
    • "updated_at": 1552341937,
    • "id": 1,
    • "name": "upcoming events",
    • "rows": 2,
    • "schema": [
      ]
    }
}

Customers

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.

Get customers by email

Return a list of people in your workspace matching an email address.

Authorization:
query Parameters
email
required
string <email>

The email address you want to search for.

Responses

Request samples

curl --request GET \
  --url 'https://api.customer.io/v1/customers?email=SOME_STRING_VALUE'

Response samples

Content type
application/json
{
  • "results": [
    • {
      }
    ]
}

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 API instead.

Authorization:
query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer <= 1000
Default: 50

The maximum number of results you want to retrieve per page.

Request Body: application/json
required
object

Describe the customers you want to return. Use and, or, and not arrays to group and determine the logic for filter criteria. You can nest and, or, and not arrays to produce complex filters.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "and": [
      ]
    }
}

Response samples

Content type
application/json
{
  • "identifiers": [
    • {
      },
    • {
      }
    ],
  • "ids": [
    • 1,
    • 2
    ],
  • "next": "MDox"
}

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.

Authorization:
path Parameters
customer_id
required
string
Example: 12345

The ID of the customer you want to perform an operation against.

query Parameters
id_type
string
Enum: "id" "email" "cio_id"

The type of customer_id you want to use to reference a person. If you don't provide this parameter, we assume that the customer_id in your request is a person's id.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/customers/{customer_id}/attributes

Response samples

Content type
application/json
{
  • "customer": {
    • "id": "1",
    • "attributes": {
      },
    • "timestamps": {
      },
    • "unsubscribed": false,
    • "devices": [
      ]
    }
}

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.

Authorization:
path Parameters
customer_id
required
string
Example: 12345

The ID of the customer you want to perform an operation against.

query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer

The maximum number of results you want to retrieve per page.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/customers/{customer_id}/relationships

Response samples

Content type
application/json
{
  • "cio_relationships": [
    • {
      }
    ],
  • "next": "string"
}

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.

Authorization:
Request Body: application/json
ids
required
Array of strings [ 1 .. 100 ] items

An array of up to 100 customer IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    • "string"
    ]
}

Response samples

Content type
application/json
{
  • "customers": [
    • {
      }
    ]
}

Lookup a customer's segments

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

Authorization:
path Parameters
customer_id
required
string
Example: 12345

The ID of the customer you want to perform an operation against.

query Parameters
id_type
string
Enum: "id" "email" "cio_id"

The type of customer_id you want to use to reference a person. If you don't provide this parameter, we assume that the customer_id in your request is a person's id.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/customers/{customer_id}/segments

Response samples

Content type
application/json
{
  • "segments": [
    • {
      }
    ]
}

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.

Authorization:
path Parameters
customer_id
required
string
Example: 12345

The ID of the customer you want to perform an operation against.

query Parameters
id_type
string
Enum: "id" "email" "cio_id"

The type of customer_id you want to use to reference a person. If you don't provide this parameter, we assume that the customer_id in your request is a person's id.

start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer <= 1000
Default: 50

The maximum number of results you want to retrieve per page.

start_ts
integer <unix timestamp>

The beginning timestamp for your query.

end_ts
integer <unix timestamp>

The ending timestamp for your query.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/customers/{customer_id}/messages

Response samples

Content type
application/json
{
  • "messages": [
    • {
      }
    ]
}

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.

Authorization:
path Parameters
customer_id
required
string
Example: 12345

The ID of the customer you want to perform an operation against.

query Parameters
id_type
string
Enum: "id" "email" "cio_id"

The type of customer_id you want to use to reference a person. If you don't provide this parameter, we assume that the customer_id in your request is a person's id.

start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer <= 100
Default: 10

The maximum number of results you want to retrieve per page.

type
string
Enum: "attempted_action" "attribute_change" "failed_attribute_change" "failed_batch_update" "skipped_update" "failed_query_collection" … 48 more
Example: type=sent_email

The type of activity you want to search for. Types with _o:<object_type_id> are for objects and types with _r:<object_type_id> are for relationships.

name
string

For event and attribute_update types, you can search by event or attribute name respectively.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/customers/{customer_id}/activities

Response samples

Content type
application/json
{
  • "activities": [
    • {
      }
    ]
}

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.

Authorization:
path Parameters
customer_id
required
string
Example: 12345

The ID of the customer you want to perform an operation against.

query Parameters
id_type
string
Enum: "id" "email" "cio_id"

The type of customer_id you want to use to reference a person. If you don't provide this parameter, we assume that the customer_id in your request is a person's id.

language
string

A language tag you want the content translated in. If none is provided, the content will be sent in the default language of your subscription center.

header Parameters
Accept-Language
string <string>

The language tag you want the content translated in. If none is provided, the content will be sent in the default lanauge of your subscription center.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/customers/{customer_id}/subscription_preferences

Response samples

Content type
application/json
{
  • "customer": {
    • "id": "1",
    • "identifiers": {
      },
    • "topics": [
      ],
    • "unsubscribed": false,
    • "header": {
      }
    }
}

ESP Suppression

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.

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

Authorization:
path Parameters
email_address
required
string

The email address of the person you want to look up.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/esp/search_suppression/{email_address}

Response samples

Content type
application/json
{
  • "category": "bounces",
  • "suppressions": [
    • {
      }
    ]
}

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.

Authorization:
path Parameters
suppression_type
required
string
Enum: "bounces" "spam_reports"

The reason a person's email address was suppressed by the email service provider (ESP).

query Parameters
limit
integer <= 1000
Default: 100

The maximum number of results you want to retrieve per page.

offset
integer
Default: 0

The number of records to skip before retrieving results.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/esp/suppression/{suppression_type}

Response samples

Content type
application/json
{
  • "category": "bounces",
  • "suppressions": [
    • {
      }
    ]
}

Un-suppress an ESP-suppressed address

Remove an address from the ESP's suppression list.

Authorization:
path Parameters
suppression_type
required
string
Enum: "bounces" "spam_reports"

The reason a person's email address was suppressed by the email service provider (ESP).

email_address
required
string

The email address of the person you want to look up.

Responses

Request samples

curl --request DELETE \
  --url https://api.customer.io/v1/esp/suppression/{suppression_type}/{email_address}

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

Authorization:
path Parameters
suppression_type
required
string
Enum: "bounces" "spam_reports"

The reason a person's email address was suppressed by the email service provider (ESP).

email_address
required
string

The email address of the person you want to look up.

Responses

Request samples

curl --request POST \
  --url https://api.customer.io/v1/esp/suppression/{suppression_type}/{email_address}

Response samples

Content type
application/json
{ }

Exports

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

List exports

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

Authorization:

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/exports

Response samples

Content type
application/json
{
  • "exports": [
    • {
      }
    ]
}

Get an export

Return information about a specific export.

Authorization:
path Parameters
export_id
required
integer

The export_id you want to access.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/exports/{export_id}

Response samples

Content type
application/json
{
  • "export": {
    • "id": 110,
    • "user_id": 0,
    • "user_email": "person@email.com",
    • "total": 1234,
    • "deduplicate_id": "110:1530296738",
    • "type": "customers",
    • "failed": false,
    • "status": "done",
    • "description": "Customers with segment filters—in \\Purchased Flowers\\",
    • "downloads": 2,
    • "created_at": 1530296738,
    • "updated_at": 1530296738
    }
}

Download an export

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

Authorization:
path Parameters
export_id
required
integer

The export_id you want to access.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/exports/{export_id}/download

Response samples

Content type
application/json
{
  • "url": "string"
}

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.

Authorization:
Request Body: application/json
required
object

When filtering for people, you can use and and or arrays to determine the logic for a group of filter conditions. not reverses the filter condition and matches when the condition is false. segment and attribute represent the individual conditions you can filter a group of people for.

The top level of this object can only contain a single property, but you can nest and and or properties to produce complex filters.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    • "and": [
      ]
    }
}

Response samples

Content type
application/json
{
  • "export": {
    • "id": 110,
    • "user_id": 0,
    • "user_email": "person@email.com",
    • "total": 1234,
    • "deduplicate_id": "110:1530296738",
    • "type": "customers",
    • "failed": false,
    • "status": "done",
    • "description": "Customers with segment filters—in \\Purchased Flowers\\",
    • "downloads": 2,
    • "created_at": 1530296738,
    • "updated_at": 1530296738
    }
}

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.

Authorization:
Request Body: application/json
One of
newsletter_id
required
integer

The ID of a newsletter you want to export information from.

start
integer <unix timestamp>

The unix timestamp representing the beginning of the export.

end
integer <unix timestamp>

The unix timestamp representing the end of the export.

attributes
Array of strings

The names of attributes you want to include in your export; each attribute name is an additional column in the export. If your message included liquid, you may add the attribute names used in your message so you can see the values populated for each delivery.

metric
string
Enum: "created" "attempted" "sent" "delivered" "opened" "clicked" … 7 more

Determines the metric(s) you want to return.

drafts
boolean

If true, your request returns both drafts and active/sent messages.

Responses

Request samples

Content type
application/json
Example
{
  • "newsletter_id": 999,
  • "start": 1517529600,
  • "end": 1517702400,
  • "attributes": [
    • "string"
    ],
  • "metric": "created",
  • "drafts": true
}

Response samples

Content type
application/json
{
  • "export": {
    • "id": "111,",
    • "deduplicate_id": "110:1530296738",
    • "type": "deliveries",
    • "failed": false,
    • "description": "Full deliveries export (created via the api)",
    • "downloads": 0,
    • "created_at": 1530296742,
    • "updated_at": 1530296742
    }
}

Imports

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.

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 for each row in your CSV; uploading events is like performing a track call.

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, events, and objects or relationships.

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 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 to get download URLs for error and warning reports.

Authorization:
Request Body: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "import": {
    • "name": "string",
    • "data_file_url": "string",
    • "type": "people",
    • "identifier": "id",
    • "data_to_process": "all",
    • "description": "string"
    }
}

Response samples

Content type
application/json
{
  • "import": {
    • "id": 30,
    • "name": "account-object-import",
    • "description": "importing accounts",
    • "created_at": 1706081641,
    • "updated_at": 1706081645,
    • "rows_to_import": 3,
    • "rows_imported": 3,
    • "state": "imported",
    • "type": "object",
    • "data_to_process": "all",
    • "people_to_process": "all",
    • "object_type_id": 1,
    • "error": "possible error - The specified Object Type does not exist."
    }
}

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.

Authorization:
path Parameters
import_id
required
integer

The id of the import you want to lookup. This value is returned from an import that was accepted and queued for processing.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/imports/{import_id}

Response samples

Content type
application/json
{
  • "import": {
    • "id": 30,
    • "name": "account-object-import",
    • "description": "importing accounts",
    • "created_at": 1706081641,
    • "updated_at": 1706081645,
    • "rows_to_import": 3,
    • "rows_imported": 3,
    • "state": "imported",
    • "type": "object",
    • "data_to_process": "all",
    • "people_to_process": "all",
    • "object_type_id": 1,
    • "error": "possible error - The specified Object Type does not exist.",
    • "error_export_id": 2,
    • "warning_export_id": 1,
    }
}

Info

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.

List IP addresses

Returns a list of IP addresses that you need to allowlist if you're using a firewall or Custom SMTP 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.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/info/ip_addresses

Response samples

Content type
application/json
{
  • "ip_addresses": [
    • "35.188.196.183",
    • "104.198.177.219",
    • "104.154.232.87",
    • "130.211.229.195",
    • "104.198.221.24",
    • "104.197.27.15",
    • "35.194.9.154",
    • "104.154.144.51",
    • "104.197.210.12",
    • "35.225.6.73"
    ]
}

Messages

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

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.

Authorization:
query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer <= 1000
Default: 50

The maximum number of results you want to retrieve per page.

type
string
Enum: "email" "webhook" "twilio" "slack" "push" "in_app"

The type of item you want to return metrics for. When empty, the response contains metrics for all possible types.

metric
string
Enum: "attempted" "sent" "delivered" "opened" "clicked" "converted" … 6 more

Determines the metric(s) you want to return.

drafts
boolean

If true, your request returns drafts rather than active/sent messages.

campaign_id
integer

The campaign you want to filter for.

newsletter_id
integer

The newsletter you want to filter for.

action_id
integer

The action you want to filter for.

start_ts
integer <unix timestamp>

The beginning timestamp for your query.

end_ts
integer <unix timestamp>

The ending timestamp for your query.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/messages

Response samples

Content type
application/json
{
  • "messages": [
    • {
      }
    ]
}

Get a message

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

Authorization:
path Parameters
message_id
required
string

The identifier of a message.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/messages/{message_id}

Response samples

Content type
application/json
{
  • "message": {
    • "id": "ag1q6QWq6QUBAAF4_CGoeVX7mFkDbRFu7ek=",
    • "deduplicate_id": "ag1q6QWq6QUBAAF4_CGoeVX7mFkDbRFu7ek=:1619137768",
    • "msg_template_id": 43,
    • "action_id": 215,
    • "parent_action_id": null,
    • "customer_id": null,
    • "recipient": "person@example.com",
    • "subject": "Did you get that thing I sent you?",
    • "metrics": {
      },
    • "created": 1619137767,
    • "failure_message": null,
    • "newsletter_id": null,
    • "content_id": null,
    • "campaign_id": 23,
    • "broadcast_id": null,
    • "trigger_event_id": null,
    • "type": "email",
    • "forgotten": false
    }
}

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.

Authorization:
path Parameters
message_id
required
string

The identifier of a message.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/messages/{message_id}/archived_message

Response samples

Content type
application/json
{
  • "archived_message": {
    • "id": "dgOq6QWq6QUBAAF4_CGoeVX7mFkDbRFu7ek=",
    • "body": "<!DOCTYPE html><html><head>\\n<meta http-equiv=\\\"Content-Type\\\" content=\\\"text/html; charset=UTF-8\\\"/><h1>Hello World</h1>\\n\\n</body></html>",
    • "from": "sentFrom@example.com",
    • "reply_to": "replyto@example.com",
    • "recipient": "person@example.com",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "request_method": "POST",
    • "headers": [
      ],
    • "forgotten": false
    }
}

Newsletters

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.

These endpoints return information about newsletters including metrics and A/B test variants. You can update variants in newsletters from these endpoints, but you must perform all other create, update, and/or delete operations through the UI.

List newsletters

Returns a list of your newsletters and associated metadata.

Authorization:
query Parameters
limit
integer

The maximum number of results you want to retrieve per page. The maximum value is 100.

sort
string
Enum: "asc" "desc"

Determine how you want to sort results, asc for chronological order and desc for reverse chronological order.

start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/newsletters

Response samples

Content type
application/json
{
  • "newsletters": [
    • {
      }
    ],
  • "next": "string"
}

Get a newsletter

Returns metadata for an individual newsletter.

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/newsletters/{newsletter_id}

Response samples

Content type
application/json
{
  • "newsletter": {
    • "id": 128275,
    • "deduplicate_id": "128275:1484870424",
    • "type": "email",
    • "content_ids": [
      ],
    • "name": "Example Newsletter",
    • "sent_at": null,
    • "created": 1481653929,
    • "updated": 1484870424,
    • "tags": [
      ],
    • "recipient_segment_ids": [
      ],
    • "subscription_topic_id": 1
    }
}

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.

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

Responses

Request samples

curl --request DELETE \
  --url https://api.customer.io/v1/newsletters/{newsletter_id}

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.

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

query Parameters
period
string
Default: "days"
Enum: "hours" "days" "weeks" "months"

The unit of time for your report.

steps
integer

The number of periods you want to return. Defaults to the maximum available, or 12 if the period is in months. Maximums are 24 hours, 45 days, 12 weeks, or 120 months.

type
string
Enum: "email" "webhook" "twilio" "slack" "push" "in_app"

The type of item you want to return metrics for. When empty, the response contains metrics for all possible types.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/newsletters/{newsletter_id}/metrics

Response samples

Content type
application/json
{
  • "metric": {
    • "series": {
      }
    }
}

List newsletter variants

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

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/newsletters/{newsletter_id}/contents

Response samples

Content type
application/json
{
  • "contents": [
    • {
      }
    ]
}

Get newsletter message metadata

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

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer

The maximum number of results you want to retrieve per page.

metric
string
Enum: "attempted" "sent" "delivered" "opened" "clicked" "converted" … 6 more

Determines the metric(s) you want to return.

start_ts
integer <unix timestamp>

The beginning timestamp for your query.

end_ts
integer <unix timestamp>

The ending timestamp for your query.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/newsletters/{newsletter_id}/messages

Response samples

Content type
application/json
{
  • "messages": [
    • {
      }
    ]
}

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.

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

content_id
required
integer

The identifier of a message in a newsletter. If your newsletter is an A/B test or has multiple languages, you may have multiple content_id values for your newsletter. You can get a newsletter to find your newsletter's content IDs.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/newsletters/{newsletter_id}/contents/{content_id}

Response samples

Content type
application/json
{
  • "content": {
    • "id": 0,
    • "newsletter_id": 10,
    • "deduplicate_id": "15:1492548073",
    • "name": "newsletter variant A",
    • "layout": "<html><body>{{ content }}</body></html>",
    • "body": "<strong>Hello from the API</strong>",
    • "body_amp": "string",
    • "language": "fr",
    • "type": "email",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ]
    }
}

Update a newsletter variant

Update the contents of a newsletter variant (a specific language of your message or a part of an A/B test), including the body of a newsletter.

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

content_id
required
integer

The identifier of a message in a newsletter. If your newsletter is an A/B test or has multiple languages, you may have multiple content_id values for your newsletter. You can get a newsletter to find your newsletter's content IDs.

Request Body: application/json
body
string

The body of the variant. You cannot modify the body if you created it with our drag-and-drop editor.

body_amp
string

If your message is an email, this is the AMP-enabled body of your message. If your recipient's email client doesn't support AMP, the body represents your fallback message.

from_id
integer

The identifier of the from address, commonly known as the "sender". You can list your sender identities to match the ID to a specific address.

reply_to_id
integer Nullable

The identifier for the reply_to address, if applicable. You can list your sender identities to match the ID to a specific address.

recipient
string

The recipient address for an action.

subject
string

The subject line for an email action.

preheader_text
string

Also known as "preview text", this specifies the small block of text shown in an end-user's email inbox, next to, or underneath, the subject line.

Array of objects

Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten.

Responses

Request samples

Content type
application/json
{
  • "body": "<strong>Hello from the API</strong>",
  • "body_amp": "string",
  • "from_id": 1,
  • "reply_to_id": 38,
  • "recipient": "{{customer.email}}",
  • "subject": "Did you get that thing I sent you?",
  • "preheader_text": "string",
  • "headers": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "content": {
    • "id": 0,
    • "newsletter_id": 10,
    • "deduplicate_id": "15:1492548073",
    • "name": "newsletter variant A",
    • "layout": "<html><body>{{ content }}</body></html>",
    • "body": "<strong>Hello from the API</strong>",
    • "body_amp": "string",
    • "language": "fr",
    • "type": "email",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ]
    }
}

Get a translation of a newsletter variant

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.

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

language
string

A language tag of a language variant. If you don't provide a language, we target your default template. If the language variant does not exist, we throw an error.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/newsletters/{newsletter_id}/language/{language}

Response samples

Content type
application/json
{
  • "content": {
    • "id": 0,
    • "newsletter_id": 10,
    • "deduplicate_id": "15:1492548073",
    • "name": "newsletter variant A",
    • "layout": "<html><body>{{ content }}</body></html>",
    • "body": "<strong>Hello from the API</strong>",
    • "body_amp": "string",
    • "language": "fr",
    • "type": "email",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ]
    }
}

Update a translation of a newsletter variant

Update the translation of a newsletter variant. If your newsletter includes A/B tests, use Update a translation in a newsletter test group.

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

language
string

A language tag of a language variant. If you don't provide a language, we target your default template. If the language variant does not exist, we throw an error.

Request Body: application/json
body
string

The body of the variant. You cannot modify the body if you created it with our drag-and-drop editor.

body_amp
string

If your message is an email, this is the AMP-enabled body of your message. If your recipient's email client doesn't support AMP, the body represents your fallback message.

from_id
integer

The identifier of the from address, commonly known as the "sender". You can list your sender identities to match the ID to a specific address.

reply_to_id
integer Nullable

The identifier for the reply_to address, if applicable. You can list your sender identities to match the ID to a specific address.

recipient
string

The recipient address for an action.

subject
string

The subject line for an email action.

preheader_text
string

Also known as "preview text", this specifies the small block of text shown in an end-user's email inbox, next to, or underneath, the subject line.

Array of objects

Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten.

Responses

Request samples

Content type
application/json
{
  • "body": "<strong>Hello from the API</strong>",
  • "body_amp": "string",
  • "from_id": 1,
  • "reply_to_id": 38,
  • "recipient": "{{customer.email}}",
  • "subject": "Did you get that thing I sent you?",
  • "preheader_text": "string",
  • "headers": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "content": {
    • "id": 0,
    • "newsletter_id": 10,
    • "deduplicate_id": "15:1492548073",
    • "name": "newsletter variant A",
    • "layout": "<html><body>{{ content }}</body></html>",
    • "body": "<strong>Hello from the API</strong>",
    • "body_amp": "string",
    • "language": "fr",
    • "type": "email",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ]
    }
}

List A/B test groups in a newsletter

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

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/newsletters/{newsletter_id}/test_groups

Response samples

Content type
application/json
{
  • "test_groups": [
    • {
      },
    • {
      }
    ]
}

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.

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

test_group_id
required
string

The ID of the A/B test group.

language
string

A language tag of a language variant. If you don't provide a language, we target your default template. If the language variant does not exist, we throw an error.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/newsletters/{newsletter_id}/test_group/{test_group_id}/language/{language}

Response samples

Content type
application/json
{
  • "content": {
    • "id": 0,
    • "newsletter_id": 10,
    • "deduplicate_id": "15:1492548073",
    • "name": "newsletter variant A",
    • "layout": "<html><body>{{ content }}</body></html>",
    • "body": "<strong>Hello from the API</strong>",
    • "body_amp": "string",
    • "language": "fr",
    • "type": "email",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ]
    }
}

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.

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

test_group_id
required
string

The ID of the A/B test group.

language
string

A language tag of a language variant. If you don't provide a language, we target your default template. If the language variant does not exist, we throw an error.

Request Body: application/json
body
string

The body of the variant. You cannot modify the body if you created it with our drag-and-drop editor.

body_amp
string

If your message is an email, this is the AMP-enabled body of your message. If your recipient's email client doesn't support AMP, the body represents your fallback message.

from_id
integer

The identifier of the from address, commonly known as the "sender". You can list your sender identities to match the ID to a specific address.

reply_to_id
integer Nullable

The identifier for the reply_to address, if applicable. You can list your sender identities to match the ID to a specific address.

recipient
string

The recipient address for an action.

subject
string

The subject line for an email action.

preheader_text
string

Also known as "preview text", this specifies the small block of text shown in an end-user's email inbox, next to, or underneath, the subject line.

Array of objects

Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten.

Responses

Request samples

Content type
application/json
{
  • "body": "<strong>Hello from the API</strong>",
  • "body_amp": "string",
  • "from_id": 1,
  • "reply_to_id": 38,
  • "recipient": "{{customer.email}}",
  • "subject": "Did you get that thing I sent you?",
  • "preheader_text": "string",
  • "headers": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "content": {
    • "id": 0,
    • "newsletter_id": 10,
    • "deduplicate_id": "15:1492548073",
    • "name": "newsletter variant A",
    • "layout": "<html><body>{{ content }}</body></html>",
    • "body": "<strong>Hello from the API</strong>",
    • "body_amp": "string",
    • "language": "fr",
    • "type": "email",
    • "from": "sentFrom@example.com",
    • "from_id": 1,
    • "reply_to": "replyto@example.com",
    • "reply_to_id": 38,
    • "preprocessor": "premailer",
    • "recipient": "{{customer.email}}",
    • "subject": "Did you get that thing I sent you?",
    • "bcc": "string",
    • "fake_bcc": true,
    • "preheader_text": "string",
    • "headers": [
      ]
    }
}

Get metrics for a variant

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.

Authorization:
path Parameters
newsletter_id
required
integer

The identifier of a newsletter.

content_id
required
integer

The identifier of a message in a newsletter. If your newsletter is an A/B test or has multiple languages, you may have multiple content_id values for your newsletter. You can get a newsletter to find your newsletter's content IDs.

query Parameters
period
string
Default: "days"
Enum: "hours" "days" "weeks" "months"

The unit of time for your report.

steps
integer

The number of periods you want to return. Defaults to the maximum available, or 12 if the period is in months. Maximums are 24 hours, 45 days, 12 weeks, or 120 months.

type
string
Enum: "email" "webhook" "twilio" "slack" "push" "in_app"

The type of item you want to return metrics for. When empty, the response contains metrics for all possible types.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/newsletters/{newsletter_id}/contents/{content_id}/metrics

Response samples

Content type
application/json
{
  • "metric": {
    • "series": {
      }
    }
}

Objects

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.

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.

Authorization:

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/object_types

Response samples

Content type
application/json
{
  • "types": [
    • {
      }
    ]
}

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.

Authorization:
query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer

The maximum number of results you want to retrieve per page.

Request Body: application/json

The object_type_id you want to search in, and the filter you want to apply to find objects. Both are required. The object called object_attribute requires type_id, as well, which should match the object_type_id.

object_type_id
required
string

The type of object you want to search in. Object type IDs are integers passed as strings.

required
object

When filtering for objects, you can use and and or arrays to determine the logic for a group of filter conditions. not reverses the filter condition and matches when the condition is false. object_attribute represents the individual conditions you can filter objects by.

The top level of this object can only contain a single property, but you can nest and and or properties to produce complex filters.

Responses

Request samples

Content type
application/json
{
  • "object_type_id": "1",
  • "filter": {
    • "and": [
      ]
    }
}

Response samples

Content type
application/json
{
  • "identifiers": [
    • {
      }
    ],
  • "ids": [
    • "ae3000"
    ],
  • "next": "string"
}

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.

Authorization:
path Parameters
object_type_id
required
integer
Example: 1

The object type an object belongs to—like "Companies" or "Accounts". Object type IDs begin at 1 and increment for each new type.

object_id
required
string
Example: abc123

The object_id or cio_object_id of an object, depending on the id_type specified in query params. id_type defaults to object_id.

query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer

The maximum number of results you want to retrieve per page.

id_type
string
Default: "object_id"
Enum: "object_id" "cio_object_id"

Responses

Request samples

curl --request GET \
  --url 'https://api.customer.io/v1/objects/{object_type_id}/{object_id}/relationships?start=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE&id_type=SOME_STRING_VALUE'

Response samples

Content type
application/json
{
  • "cio_relationships": [
    • {
      }
    ],
  • "next": "string"
}

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.

Authorization:
path Parameters
object_type_id
required
integer
Example: 1

The object type an object belongs to—like "Companies" or "Accounts". Object type IDs begin at 1 and increment for each new type.

object_id
required
string
Example: abc123

The object_id or cio_object_id of an object, depending on the id_type specified in query params. id_type defaults to object_id.

query Parameters
id_type
string
Default: "object_id"
Enum: "object_id" "cio_object_id"

Responses

Request samples

curl --request GET \
  --url 'https://api.customer.io/v1/objects/{object_type_id}/{object_id}/attributes?id_type=SOME_STRING_VALUE'

Response samples

Content type
application/json
{
  • "object": {
    • "attributes": {
      },
    • "timestamps": {
      },
    • "identifiers": {
      },
    • "object_type_id": "1"
    }
}

Reporting Webhooks

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.

Create a reporting webhook

Create a new webhook configuration.

Authorization:
Request Body: application/json
name
required
string

The name of your webhook.

endpoint
required
string <url>

The webhook URL.

events
required
Array of strings non-empty
Items Enum: "customer_subscribed" "customer_unsubscribed" "cio_subscription_preferences_changed" "email_drafted" "email_attempted" "email_sent" … 44 more

Specifies the types of events you want to report to your webhook. See our reporting webhooks reference for more information about event types and the information they return.

disabled
boolean

Set to true to quit sending events to the webhook URL. Set to false to enable the webhook.

full_resolution
boolean
Default: false

Set to false to send unique open and click events to the webhook. Set to true to send all events.

with_content
boolean

Set to true to include the message body in _sent events.

Responses

Request samples

Content type
application/json
{
  • "name": "my cool webhook",
  • "disabled": false,
  • "full_resolution": true,
  • "with_content": false,
  • "events": [
    • "email_failed",
    • "webhook_failed"
    ]
}

Response samples

Content type
application/json
{
  • "name": "my cool webhook",
  • "id": 4,
  • "disabled": false,
  • "full_resolution": true,
  • "with_content": false,
  • "events": [
    • "email_failed",
    • "webhook_failed"
    ]
}

List reporting webhooks

Return a list of all of your reporting webhooks

Authorization:

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/reporting_webhooks

Response samples

Content type
application/json
{
  • "reporting_webhooks": [
    • {
      }
    ]
}

Get a reporting webhook

Returns information about a specific reporting webhook.

Authorization:
path Parameters
webhook_id
required
integer

The identifier of a webhook.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/reporting_webhooks/{webhook_id}

Response samples

Content type
application/json
{
  • "name": "my cool webhook",
  • "id": 4,
  • "disabled": false,
  • "full_resolution": true,
  • "with_content": false,
  • "events": [
    • "email_failed",
    • "webhook_failed"
    ]
}

Update a webhook configuration

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

Authorization:
path Parameters
webhook_id
required
integer

The identifier of a webhook.

Request Body: application/json
name
required
string

The name of your webhook.

endpoint
required
string <url>

The webhook URL.

events
required
Array of strings non-empty
Items Enum: "customer_subscribed" "customer_unsubscribed" "cio_subscription_preferences_changed" "email_drafted" "email_attempted" "email_sent" … 44 more

Specifies the types of events you want to report to your webhook. See our reporting webhooks reference for more information about event types and the information they return.

disabled
boolean

Set to true to quit sending events to the webhook URL. Set to false to enable the webhook.

full_resolution
boolean
Default: false

Set to false to send unique open and click events to the webhook. Set to true to send all events.

with_content
boolean

Set to true to include the message body in _sent events.

Responses

Request samples

Content type
application/json
{
  • "name": "my cool webhook",
  • "disabled": false,
  • "full_resolution": true,
  • "with_content": false,
  • "events": [
    • "email_failed",
    • "webhook_failed"
    ]
}

Response samples

Content type
application/json
{
  • "name": "my cool webhook",
  • "id": 4,
  • "disabled": false,
  • "full_resolution": true,
  • "with_content": false,
  • "events": [
    • "email_failed",
    • "webhook_failed"
    ]
}

Delete a reporting webhook

Delete a reporting webhook's configuration.

Authorization:
path Parameters
webhook_id
required
integer

The identifier of a webhook.

Responses

Request samples

curl --request DELETE \
  --url https://api.customer.io/v1/reporting_webhooks/{webhook_id}

Reporting webhook format Webhook

Customer.io sends events to your webhook URL in the following format. Events are generally organized by object_type—representing the message or Customer.io action (i.e. email, sms, etc)—and the specific metric pertaining to the type (i.e. sent, bounced, etc).

header Parameters
x-cio-timestamp
required
integer <unix timestamp>

The timestamp when the request was sent.

x-cio-signature
required
string

A string combining your webhook signing key with the body of webhook request using an HMAC-SHA256 hash, used to help you securely verify requests.

Request Body: application/json
One of
One of
metric
required
string
Value: "subscribed"

The metric recorded by the event. For customer events, this is whether the customer explicitly subscribed or unsubscribed.

event_id
required
string

The unique ID of the reporting webhook event being sent.

object_type
required
string
Value: "customer"

The event represents a customer subscribing, unsubscribing, or changing their subscription preferences.

timestamp
required
integer <unix timestamp>

The unix timestamp when the event occurred.

required
object

Contains information about the event, specific to the object_type and metric.

Request samples

Content type
application/json
Example
{
  • "metric": "subscribed",
  • "event_id": "01E4C4CT6YDC7Y5M7FE1GWWPQJ",
  • "object_type": "customer",
  • "timestamp": 1613063089,
  • "data": {
    • "customer_id": "42",
    • "email_address": "test@example.com",
    • "identifiers": {
      }
    }
}

Segments

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.

Create a manual segment

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

Authorization:
Request Body: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "segment": {
    • "name": "Manual Segment 1",
    • "description": "My first manual segment"
    }
}

Response samples

Content type
application/json
{
  • "segment": {
    • "id": 7,
    • "deduplicate_id": "15:1492548073",
    • "name": "Manual Segment 1",
    • "description": "My first manual segment",
    • "state": "events",
    • "progress": null,
    • "type": "manual",
    • "tags": null
    }
}

List segments

Retrieve a list of all of your segments.

Authorization:

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/segments

Response samples

Content type
application/json
{
  • "segments": [
    • {
      }
    ]
}

Get a segment

Return information about a segment.

Authorization:
path Parameters
segment_id
required
integer <int32>

The identifier for a segment. You can find your segment's ID on its page in the dashboard—go to Segments, select your segment, and find the ID under Usage. Or you can find your segment using the App API.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/segments/{segment_id}

Response samples

Content type
application/json
{
  • "segment": {
    • "id": 7,
    • "deduplicate_id": "15:1492548073",
    • "name": "Manual Segment 1",
    • "description": "My first manual segment",
    • "state": "events",
    • "progress": null,
    • "type": "manual",
    • "tags": null
    }
}

Delete a segment

Delete a manual segment.

Authorization:
path Parameters
segment_id
required
integer <int32>

The identifier for a segment. You can find your segment's ID on its page in the dashboard—go to Segments, select your segment, and find the ID under Usage. Or you can find your segment using the App API.

Responses

Request samples

curl --request DELETE \
  --url https://api.customer.io/v1/segments/{segment_id}

Get a segment's dependencies

Use this endpoint to find out which campaigns and newsletters use a segment.

Authorization:
path Parameters
segment_id
required
integer <int32>

The identifier for a segment. You can find your segment's ID on its page in the dashboard—go to Segments, select your segment, and find the ID under Usage. Or you can find your segment using the App API.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/segments/{segment_id}/used_by

Response samples

Content type
application/json
{
  • "used_by": {
    • "campaigns": [
      ],
    • "sent_newsletters": [
      ],
    • "draft_newsletters": [
      ]
    }
}

Get a segment customer count

Returns the membership count for a segment.

Authorization:
path Parameters
segment_id
required
integer <int32>

The identifier for a segment. You can find your segment's ID on its page in the dashboard—go to Segments, select your segment, and find the ID under Usage. Or you can find your segment using the App API.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/segments/{segment_id}/customer_count

Response samples

Content type
application/json
{
  • "count": 0
}

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

Authorization:
path Parameters
segment_id
required
integer <int32>

The identifier for a segment. You can find your segment's ID on its page in the dashboard—go to Segments, select your segment, and find the ID under Usage. Or you can find your segment using the App API.

query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer <= 30000
Default: 1000

The maximum number of results you want to retrieve per page.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/segments/{segment_id}/membership

Response samples

Content type
application/json
Example
{
  • "ids": [
    • "string"
    ],
  • "identifiers": [
    • {
      }
    ],
  • "next": "string"
}

Sender Identities

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

List sender identities

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

Authorization:
query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer

The maximum number of results you want to retrieve per page.

sort
string
Enum: "asc" "desc"

Determine how you want to sort results, asc for chronological order and desc for reverse chronological order.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/sender_identities

Response samples

Content type
application/json
{
  • "sender_identities": [
    • {
      }
    ]
}

Get a sender

Returns information about a specific sender.

Authorization:
path Parameters
sender_id
required
integer

The identifier of a sender.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/sender_identities/{sender_id}

Response samples

Content type
application/json
{
  • "sender_identity": {
    • "id": 4534,
    • "deduplicate_id": "4534:1478035647",
    • "name": "Cher Ami",
    • "email": "test@example.com",
    • "address": "Cher Ami <test@example.com>",
    • "template_type": "email",
    • "auto_generated": false
    }
}

Get sender usage data

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

Authorization:
path Parameters
sender_id
required
integer

The identifier of a sender.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/sender_identities/{sender_id}/used_by

Response samples

Content type
application/json
{
  • "campaigns": [
    • 0
    ],
  • "sent_newsletters": [
    • 0
    ],
  • "draft_newsletters": [
    • 0
    ]
}

Snippets

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.

List snippets

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

Authorization:

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/snippets

Response samples

Content type
application/json
{
  • "snippets": [
    • {
      }
    ]
}

Create or 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.

Authorization:
Request Body: application/json
name
required
string

The name of the snippet, must be unique.

value
required
string

The contents of the snippet.

Responses

Request samples

Content type
application/json
{
  • "name": "address",
  • "value": "<strong>My Company</strong></br>1234 Fake St<br/>Fake,NY<br/>10111",
  • "updated_at": 1582500000
}

Response samples

Content type
application/json
{
  • "snippet": {
    • "name": "address",
    • "value": "<strong>My Company</strong></br>1234 Fake St<br/>Fake,NY<br/>10111",
    • "updated_at": 1582500000
    }
}

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.

Authorization:
path Parameters
snippet_name
required
string

The name of a snippet.

Responses

Request samples

curl --request DELETE \
  --url https://api.customer.io/v1/snippets/{snippet_name}

Response samples

Content type
application/json
{
  • "errors": [
    • {
      }
    ]
}

Subscription Center

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.

List subscription topics

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

Authorization:

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/subscription_topics

Response samples

Content type
application/json
{
  • "topics": [
    • {
      }
    ]
}

Transactional Messages

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

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.

Authorization:

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/transactional

Response samples

Content type
application/json
{
  • "messages": [
    • {
      }
    ]
}

Get a transactional message

Returns information about an individual transactional message.

Authorization:
path Parameters
transactional_id
required
integer

The identifier of your transactional message. You'll find this in the UI or URL of your transactional message. For example, if this is the path of a transactional message URL - /transactional/3/templates/139 - the transactional_id is 3.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/transactional/{transactional_id}

Response samples

Content type
application/json
{
  • "message": {
    • "id": 2,
    • "name": "password reset",
    • "description": "sends a temporary password and lets the customer reset their password.",
    • "send_to_unsubscribed": true,
    • "link_tracking": true,
    • "open_tracking": true,
    • "hide_message_body": true,
    • "queue_drafts": true,
    • "created_at": 1552341937,
    • "updated_at": 1552341937
    }
}

List all variants of a transactional message

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

Authorization:
path Parameters
transactional_id
required
integer

The identifier of your transactional message. You'll find this in the UI or URL of your transactional message. For example, if this is the path of a transactional message URL - /transactional/3/templates/139 - the transactional_id is 3.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/transactional/{transactional_id}/contents

Response samples

Content type
application/json
{
  • "contents": [
    • {
      }
    ]
}

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.

Authorization:
path Parameters
transactional_id
required
integer

The identifier of your transactional message. You'll find this in the UI or URL of your transactional message. For example, if this is the path of a transactional message URL - /transactional/3/templates/139 - the transactional_id is 3.

content_id
required
integer

The content variant of your transactional message. You'll find the id in the URL of your transactional message. For example, if this is the path of a transactional message URL - /transactional/3/templates/139 - the content_id is 139.

Request Body: application/json
body
string

The body of the transactional message. You cannot modify the body if you created it with our drag-and-drop editor.

from_id
integer

The identifier of the from address, commonly known as the "sender". You can list your sender identities to match the ID to a specific address.

reply_to_id
integer Nullable

The identifier for the reply_to address, if applicable. You can list your sender identities to match the ID to a specific address.

subject
string

The subject line for an email action.

preheader_text
string

Also known as "preview text", this specifies the small block of text shown in an end-user's email inbox, next to, or underneath, the subject line.

Array of objects

Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten.

body_amp
string

If your message is an email, this is the AMP-enabled body of your message. If your recipient's email client doesn't support AMP, the body represents your fallback message.

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "from_id": 1,
  • "reply_to_id": 38,
  • "subject": "Did you get that thing I sent you?",
  • "preheader_text": "string",
  • "headers": [
    • {
      }
    ],
  • "body_amp": "string"
}

Response samples

Content type
application/json
{
  • "content": [
    • {
      }
    ]
}

Get a translation of a transactional message

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

Authorization:
path Parameters
transactional_id
required
integer

The identifier of your transactional message. You'll find this in the UI or URL of your transactional message. For example, if this is the path of a transactional message URL - /transactional/3/templates/139 - the transactional_id is 3.

language
string

A language tag of a language variant. If you don't provide a language, we target your default template. If the language variant does not exist, we throw an error.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/transactional/{transactional_id}/language/{language}

Response samples

Content type
application/json
{
  • "content": [
    • {
      }
    ]
}

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.

Authorization:
path Parameters
transactional_id
required
integer

The identifier of your transactional message. You'll find this in the UI or URL of your transactional message. For example, if this is the path of a transactional message URL - /transactional/3/templates/139 - the transactional_id is 3.

language
string

A language tag of a language variant. If you don't provide a language, we target your default template. If the language variant does not exist, we throw an error.

Request Body: application/json
body
string

The body of the transactional message. You cannot modify the body if you created it with our drag-and-drop editor.

from_id
integer

The identifier of the from address, commonly known as the "sender". You can list your sender identities to match the ID to a specific address.

reply_to_id
integer Nullable

The identifier for the reply_to address, if applicable. You can list your sender identities to match the ID to a specific address.

subject
string

The subject line for an email action.

preheader_text
string

Also known as "preview text", this specifies the small block of text shown in an end-user's email inbox, next to, or underneath, the subject line.

Array of objects

Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten.

body_amp
string

If your message is an email, this is the AMP-enabled body of your message. If your recipient's email client doesn't support AMP, the body represents your fallback message.

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "from_id": 1,
  • "reply_to_id": 38,
  • "subject": "Did you get that thing I sent you?",
  • "preheader_text": "string",
  • "headers": [
    • {
      }
    ],
  • "body_amp": "string"
}

Response samples

Content type
application/json
{
  • "content": [
    • {
      }
    ]
}

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.

Authorization:
path Parameters
transactional_id
required
integer

The identifier of your transactional message. You'll find this in the UI or URL of your transactional message. For example, if this is the path of a transactional message URL - /transactional/3/templates/139 - the transactional_id is 3.

query Parameters
period
string
Default: "days"
Enum: "hours" "days" "weeks" "months"

The unit of time for your report.

steps
integer

The number of periods you want to return. Defaults to the maximum available, or 12 if the period is in months. Maximums are 24 hours, 45 days, 12 weeks, or 120 months.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/transactional/{transactional_id}/metrics

Response samples

Content type
application/json
{
  • "metric": {
    • "series": {
      }
    }
}

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.

Authorization:
path Parameters
transactional_id
required
integer

The identifier of your transactional message. You'll find this in the UI or URL of your transactional message. For example, if this is the path of a transactional message URL - /transactional/3/templates/139 - the transactional_id is 3.

query Parameters
start
string

The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

limit
integer

The maximum number of results you want to retrieve per page.

metric
string
Enum: "attempted" "sent" "delivered" "opened" "clicked" "converted" … 6 more

Determines the metric(s) you want to return.

state
string
Enum: "failed" "sent" "drafted" "attempted"

The state of a broadcast.

start_ts
integer <unix timestamp>

The beginning timestamp for your query.

end_ts
integer <unix timestamp>

The ending timestamp for your query.

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/transactional/{transactional_id}/messages

Response samples

Content type
application/json
{
  • "messages": [
    • {
      }
    ]
}

Workspaces

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.

List workspaces

Returns a list of workspaces in your account.

Authorization:

Responses

Request samples

curl --request GET \
  --url https://api.customer.io/v1/workspaces

Response samples

Content type
application/json
{
  • "workspaces": [
    • {
      }
    ]
}