Query structured spec data via REST or MCP. Get exactly what your agent needs.
https://api.customer.io
/v1/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| type | query | optional | string | The type of activity you want to search for. Types with |
| name | query | optional | string | The name of the event or attribute you want to return. |
| deleted | query | optional | boolean | If true, return results for deleted people. |
| customer_id | query | optional | string | The If you use a person’s |
| id_type | query | optional | string | The type of |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
Returns an array of activities.
Your request is over the 10-per-second limit.
GET /v1/activities
/v1/broadcasts
Returns a list of your broadcasts and associated metadata.
Returns an array of broadcasts.
Your request is over the 10-per-second limit.
GET /v1/broadcasts
/v1/broadcasts/{broadcast_id}
Returns metadata for an individual broadcast.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The identifier of a broadcast. |
Returns metadata for the broadcast.
The broadcast you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/broadcasts/{broadcast_id}
/v1/broadcasts/{broadcast_id}/actions
Returns the actions that occur as a part of a broadcast.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The identifier of a broadcast. |
Returns broadcast actions. Each object represents an individual variant for this broadcast.
The broadcast you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/broadcasts/{broadcast_id}/actions
/v1/broadcasts/{broadcast_id}/actions/{action_id}
Returns information about a specific action within a broadcast.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The identifier of a broadcast. |
| action_id | path | required | integer | The action you want to lookup or act on. |
Returns the requested broadcast action.
The language does not exist for this action.
The broadcast or action does not exist.
Your request is over the 10-per-second limit.
GET /v1/broadcasts/{broadcast_id}/actions/{action_id}
/v1/broadcasts/{broadcast_id}/actions/{action_id}/language/{language}
Returns information about a translation of message in a broadcast. The message is identified by the action_id.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The identifier of a broadcast. |
| action_id | path | required | integer | The action you want to lookup or act on. |
| language | path | optional | 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. |
Returns information for the requested language variant for a broadcast action.
The language does not exist for this action.
The broadcast or action does not exist.
Your request is over the 10-per-second limit.
GET /v1/broadcasts/{broadcast_id}/actions/{action_id}/language/{language}
/v1/broadcasts/{broadcast_id}/actions/{action_id}/metrics/links
Returns link click metrics for an individual broadcast action. Unless you specify otherwise, the response contains data for the maximum period by days (45 days).
You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, ?period=days&steps=1 means two days - the 48 hours before the API request was made. ?period=days&steps=0 returns the same as the maximum of the period - ?period=days&steps=45. See the steps parameter below for the maximum count of each period.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The identifier of a broadcast. |
| action_id | path | required | integer | The action you want to lookup or act on. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
Returns broadcast variant metrics by series (with increments are based on the period and step in your request) for the broadcast.
The broadcast and/or variant does not exist.
Your request is over the 10-per-second limit.
GET /v1/broadcasts/{broadcast_id}/actions/{action_id}/metrics/links
/v1/broadcasts/{broadcast_id}/messages
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The identifier of a broadcast. |
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
| metric | query | optional | string | Determines the metric(s) you want to return. |
| state | query | optional | string | The state of a broadcast. |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
| start_ts | query | optional | integer | The beginning timestamp for your query. |
| end_ts | query | optional | integer | The ending timestamp for your query. |
Returns an array of messages. Each object represents a different message in your broadcast.
The broadcast you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/broadcasts/{broadcast_id}/messages
/v1/broadcasts/{broadcast_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The identifier of a broadcast. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
Returns broadcast metrics by series (with increments are based on the period and step in your request) for the broadcast.
The broadcast you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/broadcasts/{broadcast_id}/metrics
/v1/broadcasts/{broadcast_id}/metrics/links
Returns metrics for link clicks within a broadcast, both in total and in series periods (days, weeks, etc). series metrics are ordered oldest to newest (i.e. the 0-index for any result is the oldest step/period).
You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, ?period=days&steps=1 means two days - the 48 hours before the API request was made. ?period=days&steps=0 returns the same as the maximum of the period - ?period=days&steps=45. See the steps parameter below for the maximum count of each period.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The identifier of a broadcast. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| unique | query | optional | boolean | 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. |
Returns an array of link objects. Each object represents a different link in your broadcast and contains independent metrics.
The broadcast you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/broadcasts/{broadcast_id}/metrics/links
/v1/broadcasts/{broadcast_id}/triggers
Returns a list of the triggers for a broadcast.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The identifier of a broadcast. |
Returns an array of triggers.
The broadcast does not exist.
Your request is over the 10-per-second limit.
GET /v1/broadcasts/{broadcast_id}/triggers
/v1/broadcast/{broadcast_id}/actions/{action_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The identifier of a broadcast. |
| action_id | path | required | integer | The action you want to lookup or act on. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
Returns action metrics by series (with increments are based on the period and step in your request) for the broadcast.
The broadcast and/or action does not exist.
Your request is over the 10-per-second limit.
GET /v1/broadcast/{broadcast_id}/actions/{action_id}/metrics
/v1/campaigns/{broadcast_id}/triggers/{trigger_id}
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The ID of the broadcast that you want to return information about. |
| trigger_id | path | required | integer | The ID of the campaign trigger that you want to return information for. |
Returns the status of your broadcast.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{broadcast_id}/triggers/{trigger_id}
/v1/campaigns/{broadcast_id}/triggers/{trigger_id}/errors
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| broadcast_id | path | required | integer | The ID of the broadcast that you want to return information about. |
| trigger_id | path | required | integer | The ID of the campaign trigger that you want to return information for. |
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
Returns an array of errors.
Unauthorized request. Make sure that you provided the right credentials.
The campaign ID or trigger ID from your request do not exist.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{broadcast_id}/triggers/{trigger_id}/errors
/v1/campaigns
Returns a list of your campaigns and associated metadata.
Returns an array of campaign objects.
Your request is over the 10-per-second limit.
GET /v1/campaigns
/v1/campaigns/{campaign_id}
Returns metadata for an individual campaign.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| campaign_id | path | required | integer | The ID of the campaign that you want to trigger or return information about. |
Returns metadata for the campaign.
The campaign you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{campaign_id}
/v1/campaigns/{campaign_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| campaign_id | path | required | integer | The ID of the campaign that you want to trigger or return information about. |
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
Returns campaign actions. Each object represents an individual action.
The campaign you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{campaign_id}/actions
/v1/campaigns/{campaign_id}/actions/{action_id}
Returns information about a specific action in a campaign.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| campaign_id | path | required | integer | The ID of the campaign that you want to trigger or return information about. |
| action_id | path | required | integer | The action you want to lookup or act on. |
Returns the requested campaign action.
The language does not exist for this action.
The campaign or action does not exist.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{campaign_id}/actions/{action_id}
/v1/campaigns/{campaign_id}/actions/{action_id}/language/{language}
Returns a translated version of a message in a campaign. The message is identified by the action_id.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| campaign_id | path | required | integer | The ID of the campaign that you want to trigger or return information about. |
| action_id | path | required | integer | The action you want to lookup or act on. |
| language | path | optional | 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. |
Returns information for the requested campaign action language variant.
The language does not exist for this action.
The campaign or action does not exist.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{campaign_id}/actions/{action_id}/language/{language}
/v1/campaigns/{campaign_id}/actions/{action_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| campaign_id | path | required | integer | The ID of the campaign that you want to trigger or return information about. |
| action_id | path | required | integer | The action you want to lookup or act on. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
Returns action metrics by series (with increments are based on the period and step in your request) for the campaign.
The campaign and/or action does not exist.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{campaign_id}/actions/{action_id}/metrics
/v1/campaigns/{campaign_id}/actions/{action_id}/metrics/links
Returns link click metrics for an individual action. Unless you specify otherwise, the response contains data for the maximum period by days (45 days).
You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, ?period=days&steps=1 means two days - the 48 hours before the API request was made. ?period=days&steps=0 returns the same as the maximum of the period - ?period=days&steps=45. See the steps parameter below for the maximum count of each period.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| campaign_id | path | required | integer | The ID of the campaign that you want to trigger or return information about. |
| action_id | path | required | integer | The action you want to lookup or act on. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
Returns action metrics by series (with increments are based on the period and step in your request) for the campaign.
The campaign and/or action does not exist.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{campaign_id}/actions/{action_id}/metrics/links
/v1/campaigns/{campaign_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| campaign_id | path | required | integer | The ID of the campaign that you want to trigger or return information about. |
| start | query | required | integer | The unix timestamp for the beginning of your journey metrics report. |
| end | query | required | integer | The unix timestamp for the end of your journey metrics report. |
| resolution | query | required | string | Determines increment for journey metrics—hourly, daily, weekly, or monthly. |
Each journey_metric item in the response is an array. Each item in a metric array represents the number of journeys that started within the time increment (“resolution”—day or month) and eventually achieved that metric.
You may have omitted query parameters or the start time occurred after the end time.
The campaign and/or action does not exist.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{campaign_id}/journey_metrics
/v1/campaigns/{campaign_id}/messages
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| campaign_id | path | required | integer | The ID of the campaign that you want to trigger or return information about. |
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
| metric | query | optional | string | Determines the metric(s) you want to return. |
| drafts | query | optional | boolean | If true, your request returns drafts rather than active/sent messages. |
| start_ts | query | optional | integer | The beginning timestamp for your query. |
| end_ts | query | optional | integer | The ending timestamp for your query. |
Returns an array of messages. Each object represents a different message in your campaign.
The campaign you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{campaign_id}/messages
/v1/campaigns/{campaign_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| campaign_id | path | required | integer | The ID of the campaign that you want to trigger or return information about. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
Returns campaign metrics by series (using the period and step in the request) for the campaign.
The campaign you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{campaign_id}/metrics
/v1/campaigns/{campaign_id}/metrics/links
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| campaign_id | path | required | integer | The ID of the campaign that you want to trigger or return information about. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| unique | query | optional | boolean | 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. |
Returns an array of link objects. Each object represents a different link in your campaign and contains independent metrics.
The campaign you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/campaigns/{campaign_id}/metrics/links
/v1/collections
Returns a list of all of your collections, including the name and schema for each collection.
Returns metadata about your collection.
Your request is over the 10-per-second limit.
GET /v1/collections
/v1/collections/{collection_id}
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).
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| collection_id | path | required | integer | The identifier for a collection. |
Returns metadata about your collection.
The collection id does not exist.
Your request is over the 10-per-second limit.
GET /v1/collections/{collection_id}
/v1/collections/{collection_id}/content
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| collection_id | path | required | integer | The identifier for a collection. |
Returns your collection’s contents—the data (or url contents) from your POST or PUT call.
The collection id does not exist.
Your request is over the 10-per-second limit.
GET /v1/collections/{collection_id}/content
/v1/customers
Return a list of people in your workspace matching an email address.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| query | required | string | The email address you want to search for. |
Returns an array of results; each result represents a person.
Unauthorized request. Make sure that you provided the right credentials.
Your request is over the 10-per-second limit.
GET /v1/customers
/v1/customers/{customer_id}/activities
Return a list of activities performed by, or for, a customer. Activities are things like attribute changes and message sends.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| customer_id | path | required | string | The ID of the customer you want to perform an operation against. |
| id_type | query | optional | string | The type of |
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
| type | query | optional | string | The type of activity you want to search for. Types with |
| name | query | optional | string | For |
Returns an array of activity objects. Each object represents an activity that the customer performed, or that you performed on behalf of the customer.
The request parameters are malformed.
The customer_id does not exist.
Your request is over the 10-per-second limit.
GET /v1/customers/{customer_id}/activities
/v1/customers/{customer_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| customer_id | path | required | string | The ID of the customer you want to perform an operation against. |
| id_type | query | optional | string | The type of |
Returns the customer and associated attributes.
The customer_id does not exist.
Your request is over the 10-per-second limit.
GET /v1/customers/{customer_id}/attributes
/v1/customers/{customer_id}/messages
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| customer_id | path | required | string | The ID of the customer you want to perform an operation against. |
| id_type | query | optional | string | The type of |
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
| start_ts | query | optional | integer | The beginning timestamp for your query. |
| end_ts | query | optional | integer | The ending timestamp for your query. |
Returns an array of message objects. Each object represents a message that you sent a customer.
The customer_id does not exist.
Your request is over the 10-per-second limit.
GET /v1/customers/{customer_id}/messages
/v1/customers/{customer_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| customer_id | path | required | string | The ID of the customer you want to perform an operation against. |
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
Returns an array of cio_relationships.
The customer_id does not exist.
Your request is over the 10-per-second limit.
GET /v1/customers/{customer_id}/relationships
/v1/customers/{customer_id}/segments
Returns a list of segments that a customer profile belongs to.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| customer_id | path | required | string | The ID of the customer you want to perform an operation against. |
| id_type | query | optional | string | The type of |
Returns an array of segments that the customer belongs to.
The customer_id does not exist.
Your request is over the 10-per-second limit.
GET /v1/customers/{customer_id}/segments
/v1/customers/{customer_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| customer_id | path | required | string | The ID of the customer you want to perform an operation against. |
| id_type | query | optional | string | The type of |
| language | query | optional | 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. |
| Accept-Language | header | optional | string | — |
Returns the customer’s associated subscription preferences.
Invalid or malformed request.
The customer_id does not exist.
Your request is over the 10-per-second limit.
GET /v1/customers/{customer_id}/subscription_preferences
/v1/esp/search_suppression/{email_address}
Look up an email address to learn if, and why, it was suppressed by the email service provider (ESP).
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| email_address | path | required | string | The email address of the person you want to look up. |
Returns an array of suppressed email addresses.
Your request is over the 10-per-second limit.
GET /v1/esp/search_suppression/{email_address}
/v1/esp/suppression/{suppression_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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| suppression_type | path | required | string | The reason a person’s email address was suppressed by the email service provider (ESP). |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
| offset | query | optional | integer | The number of records to skip before retrieving results. |
Returns an array of suppressed email addresses.
Your request is over the 10-per-second limit.
GET /v1/esp/suppression/{suppression_type}
/v1/exports
Return a list of your exports. Exports are point-in-time people or campaign metrics.
Returns an array of exports.
Your request is over the 10-per-second limit.
GET /v1/exports
/v1/exports/{export_id}
Return information about a specific export.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| export_id | path | required | integer | The export_id you want to access. |
Returns an export.
The export ID does not exist.
Your request is over the 10-per-second limit.
GET /v1/exports/{export_id}
/v1/exports/{export_id}/download
This endpoint returns a signed link to download an export. The link expires after 15 minutes.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| export_id | path | required | integer | The export_id you want to access. |
Returns a link to an export.
The export ID does not exist.
Your request is over the 10-per-second limit.
GET /v1/exports/{export_id}/download
/v1/imports/{import_id}
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| import_id | path | required | integer | The |
Returns an import payload.
Your request is over the 10-per-second limit.
GET /v1/imports/{import_id}
/v1/info/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.
Returns an array of IP addresses.
Your request is over the 10-per-second limit.
GET /v1/info/ip_addresses
/v1/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
| metric | query | optional | string | Determines the metric(s) you want to return. |
| drafts | query | optional | boolean | If true, your request returns drafts rather than active/sent messages. |
| campaign_id | query | optional | integer | The campaign you want to filter for. |
| newsletter_id | query | optional | integer | The newsletter you want to filter for. |
| action_id | query | optional | integer | The action you want to filter for. |
| start_ts | query | optional | integer | The beginning timestamp for your query. |
| end_ts | query | optional | integer | The ending timestamp for your query. |
Returns an array of message objects.
The request was malformed.
Your request is over the 10-per-second limit.
GET /v1/messages
/v1/messages/{message_id}
Return a information about, and metrics for, a delivery—the instance of a message intended for an individual recipient person.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| message_id | path | required | string | The identifier of a message. |
Returns a message object.
The message does not exist.
Your request is over the 10-per-second limit.
GET /v1/messages/{message_id}
/v1/messages/{message_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| message_id | path | required | string | The identifier of a message. |
Returns the archived message object.
The message does not exist.
Your request is over the 10-per-second limit.
GET /v1/messages/{message_id}/archived_message
/v1/newsletters
Returns a list of your newsletters and associated metadata.
Returns an array of newsletter objects.
GET /v1/newsletters
/v1/newsletters/{newsletter_id}
Returns metadata for an individual newsletter.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| newsletter_id | path | required | integer | The identifier of a newsletter. |
Returns metadata for the newsletter.
The newsletter you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/newsletters/{newsletter_id}
/v1/newsletters/{newsletter_id}/contents
Returns the content variants of a newsletter—these are either different languages in a multi-language newsletter or A/B tests.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| newsletter_id | path | required | integer | The identifier of a newsletter. |
Returns newsletter content_ids. Each object represents an individual variant of this newsletter.
The newsletter you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/newsletters/{newsletter_id}/contents
/v1/newsletters/{newsletter_id}/contents/{content_id}
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| newsletter_id | path | required | integer | The identifier of a newsletter. |
| content_id | path | required | integer | The identifier of a newsletter variant—a language in a multi-language message or an individual test in an A/B test. You can list your newsletter’s variants to find your newsletter’s variants. |
Returns newsletter content.
The newsletter or variant does not exist.
Your request is over the 10-per-second limit.
GET /v1/newsletters/{newsletter_id}/contents/{content_id}
/v1/newsletters/{newsletter_id}/contents/{content_id}/metrics
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| newsletter_id | path | required | integer | The identifier of a newsletter. |
| content_id | path | required | integer | The identifier of a newsletter variant—a language in a multi-language message or an individual test in an A/B test. You can list your newsletter’s variants to find your newsletter’s variants. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
Returns newsletter variant metrics by series (with increments are based on the period and step in your request) for the newsletter.
The newsletter and/or variant does not exist.
Your request is over the 10-per-second limit.
GET /v1/newsletters/{newsletter_id}/contents/{content_id}/metrics
/v1/newsletters/{newsletter_id}/contents/{content_id}/metrics/links
Returns link click metrics for an individual newsletter variant—an individual language in a multi-language newsletter or a message in an A/B test. Unless you specify otherwise, the response contains data for the maximum period by days (45 days).
You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, ?period=days&steps=1 means two days - the 48 hours before the API request was made. ?period=days&steps=0 returns the same as the maximum of the period - ?period=days&steps=45. See the steps parameter below for the maximum count of each period.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| newsletter_id | path | required | integer | The identifier of a newsletter. |
| content_id | path | required | integer | The identifier of a newsletter variant—a language in a multi-language message or an individual test in an A/B test. You can list your newsletter’s variants to find your newsletter’s variants. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
Returns newsletter variant metrics by series (with increments are based on the period and step in your request) for the newsletter.
The newsletter and/or variant does not exist.
Your request is over the 10-per-second limit.
GET /v1/newsletters/{newsletter_id}/contents/{content_id}/metrics/links
/v1/newsletters/{newsletter_id}/language/{language}
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| newsletter_id | path | required | integer | The identifier of a newsletter. |
| language | path | optional | 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. |
Returns newsletter content for a language variant.
The language does not exist.
The newsletter or variant does not exist.
Your request is over the 10-per-second limit.
GET /v1/newsletters/{newsletter_id}/language/{language}
/v1/newsletters/{newsletter_id}/messages
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| newsletter_id | path | required | integer | The identifier of a newsletter. |
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
| metric | query | optional | string | Determines the metric(s) you want to return. |
| start_ts | query | optional | integer | The beginning timestamp for your query. |
| end_ts | query | optional | integer | The ending timestamp for your query. |
Returns an array of messages. Each object represents a different message in your newsletter.
The newsletter you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/newsletters/{newsletter_id}/messages
/v1/newsletters/{newsletter_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| newsletter_id | path | required | integer | The identifier of a newsletter. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| type | query | optional | string | The type of item you want to return metrics for. When empty, the response contains metrics for all possible types. |
Returns newsletter metrics by series (with increments are based on the period and step in your request) for the newsletter.
The newsletter you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/newsletters/{newsletter_id}/metrics
/v1/newsletters/{newsletter_id}/metrics/links
Returns metrics for link clicks within a newsletter, both in total and in series periods (days, weeks, etc). series metrics are ordered oldest to newest (i.e. the 0-index for any result is the oldest step/period).
You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, ?period=days&steps=1 means two days - the 48 hours before the API request was made. ?period=days&steps=0 returns the same as the maximum of the period - ?period=days&steps=45. See the steps parameter below for the maximum count of each period.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| newsletter_id | path | required | integer | The identifier of a newsletter. |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| unique | query | optional | boolean | 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. |
Returns an array of link objects. Each object represents a different link in your newsletter and contains independent metrics.
The newsletter you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/newsletters/{newsletter_id}/metrics/links
/v1/newsletters/{newsletter_id}/test_group/{test_group_id}/language/{language}
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| newsletter_id | path | required | integer | The identifier of a newsletter. |
| test_group_id | path | required | string | The ID of the A/B test group. |
| language | path | optional | 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. |
Returns newsletter content for a language variant in a test group.
The language does not exist.
The newsletter or variant does not exist.
Your request is over the 10-per-second limit.
GET /v1/newsletters/{newsletter_id}/test_group/{test_group_id}/language/{language}
/v1/newsletters/{newsletter_id}/test_groups
Returns information about each test group in a newsletter, including content ids for each group.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| newsletter_id | path | required | integer | The identifier of a newsletter. |
Returns metadata for each test group in a newsletter.
The newsletter or variant does not exist.
Your request is over the 10-per-second limit.
GET /v1/newsletters/{newsletter_id}/test_groups
/v1/objects/{object_type_id}/{object_id}/attributes
Get a list of attributes for an object. Attributes are things you know about an object—like an account name, billing date, etc.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| object_type_id | path | required | integer | The object type an object belongs to—like “Companies” or “Accounts”. Object type IDs begin at |
| object_id | path | required | string | The |
| id_type | query | optional | string | — |
Returns information about the attributes for the object specified in the endpoint path.
Unauthorized request. Make sure that you provided the right credentials.
Your request is over the 10-per-second limit.
GET /v1/objects/{object_type_id}/{object_id}/attributes
/v1/objects/{object_type_id}/{object_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| object_type_id | path | required | integer | The object type an object belongs to—like “Companies” or “Accounts”. Object type IDs begin at |
| object_id | path | required | string | The |
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
| id_type | query | optional | string | — |
Returns an array of cio_relationships. Each object in the array represents a person related to the object specified in the endpoint path.
Your request is over the 10-per-second limit.
GET /v1/objects/{object_type_id}/{object_id}/relationships
/v1/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.
Returns an array of types.
Unauthorized request. Make sure that you provided the right credentials.
Your request is over the 10-per-second limit.
GET /v1/object_types
/v1/reporting_webhooks
Return a list of all of your reporting webhooks
Returns an array of your reporting_webhooks.
Your request is over the 10-per-second limit.
GET /v1/reporting_webhooks
/v1/reporting_webhooks/{webhook_id}
Returns information about a specific reporting webhook.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| webhook_id | path | required | integer | The identifier of a webhook. |
Returns an individual webhook configuration.
The webhook ID does not exist.
Your request is over the 10-per-second limit.
GET /v1/reporting_webhooks/{webhook_id}
/v1/segments
Retrieve a list of all of your segments.
Returns an array of segments. Each object in the response represents an individual segment.
Your request is over the 10-per-second limit.
GET /v1/segments
/v1/segments/{segment_id}
Return information about a segment.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| segment_id | path | required | integer | 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. |
Returns the information about the segment.
The segment_id does not exist.
Your request is over the 10-per-second limit.
GET /v1/segments/{segment_id}
/v1/segments/{segment_id}/customer_count
Returns the membership count for a segment.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| segment_id | path | required | integer | 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. |
Returns the customer count for a segment.
The segment_id does not exist.
Your request is over the 10-per-second limit.
GET /v1/segments/{segment_id}/customer_count
/v1/segments/{segment_id}/membership
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| segment_id | path | required | integer | 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. |
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
Returns an array of customers for a segment.
The segment_id does not exist.
Your request is over the 10-per-second limit.
GET /v1/segments/{segment_id}/membership
/v1/segments/{segment_id}/used_by
Use this endpoint to find out which campaigns and newsletters use a segment.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| segment_id | path | required | integer | 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. |
Returns the IDs of items that reference the segment.
The segment_id does not exist.
Your request is over the 10-per-second limit.
GET /v1/segments/{segment_id}/used_by
/v1/sender_identities
Returns a list of senders in your workspace. Senders are who your messages are “from”.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
| sort | query | optional | string | Determine how you want to sort results, |
Returns an array of sender_identities.
Your request is over the 10-per-second limit.
GET /v1/sender_identities
/v1/sender_identities/{sender_id}
Returns information about a specific sender.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| sender_id | path | required | integer | The identifier of a sender. |
Returns the sender_identity you requested.
The sender does not exist.
Your request is over the 10-per-second limit.
GET /v1/sender_identities/{sender_id}
/v1/sender_identities/{sender_id}/used_by
Returns lists of the campaigns and newsletters that use a sender.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| sender_id | path | required | integer | The identifier of a sender. |
Returns arrays of campaigns and newsletters.
The sender does not exist.
Your request is over the 10-per-second limit.
GET /v1/sender_identities/{sender_id}/used_by
/v1/snippets
Returns a list of snippets in your workspace. Snippets are pieces of reusable content, like a common footer for your emails.
Returns an array of snippets.
GET /v1/snippets
/v1/subscription_topics
Returns a list of subscription topics in your workspace. If there are no topics, it returns an empty array.
Returns an array of topics.
Your request is over the 10-per-second limit.
GET /v1/subscription_topics
/v1/transactional
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.
Returns an array of transactional messages.
Your request is over the 10-per-second limit.
GET /v1/transactional
/v1/transactional/{transactional_id}
Returns information about an individual transactional message.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| transactional_id | path | 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 - |
Returns metadata for the transactional message ID in the path.
The transactional message does not exist.
Your request is over the 10-per-second limit.
GET /v1/transactional/{transactional_id}
/v1/transactional/{transactional_id}/contents
Returns the content variants of a transactional message, where each variant represents a different language.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| transactional_id | path | 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 - |
Returns each variant of the transactional message.
The request was malformed.
The transactional_id or content_id in your request do not exist.
GET /v1/transactional/{transactional_id}/contents
/v1/transactional/{transactional_id}/language/{language}
Returns information about a translation of an individual transactional message, including the message content.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| transactional_id | path | 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 - |
| language | path | optional | 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. |
Returns the specified variant of the transactional message.
The language in your request does not exist.
The transactional message does not exist.
Your request is over the 10-per-second limit.
GET /v1/transactional/{transactional_id}/language/{language}
/v1/transactional/{transactional_id}/messages
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| transactional_id | path | 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 - |
| start | query | optional | string | The token for the page of results you want to return. Responses contain a |
| limit | query | optional | integer | The maximum number of results you want to retrieve per page. |
| metric | query | optional | string | Determines the metric(s) you want to return. |
| state | query | optional | string | The state of a broadcast. |
| start_ts | query | optional | integer | The beginning timestamp for your query. |
| end_ts | query | optional | integer | The ending timestamp for your query. |
Returns an array of messages. Each object represents a different delivery originating from the transactional ID.
For transactional messages, the action, newsletter, campaign, content, and broadcast IDs are all null. All deliveries originate from the transactional ID in the path of your request.
The transactional message you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/transactional/{transactional_id}/messages
/v1/transactional/{transactional_id}/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| transactional_id | path | 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 - |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
Returns transactional message metrics by series (with increments are based on the period and step in your request) for transactional message.
The transactional message you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/transactional/{transactional_id}/metrics
/v1/transactional/{transactional_id}/metrics/links
Returns metrics for clicked links from a transactional message, both in total and in series periods (days, weeks, etc). series metrics are ordered oldest to newest (i.e. the 0-index for any result is the oldest step/period).
You cannot request fewer than 2 steps of any period (2 hours, 2 days, 2 weeks, or 2 months). For instance, ?period=days&steps=1 means two days - the 48 hours before the API request was made. ?period=days&steps=0 returns the same as the maximum of the period - ?period=days&steps=45. See the steps parameter below for the maximum count of each period.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| transactional_id | path | 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 - |
| period | query | optional | string | The unit of time for your report. |
| steps | query | optional | integer | The number of periods you want to return. Defaults to the maximum available, or |
| unique | query | optional | boolean | 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. |
Returns an array of link objects. Each object represents a different link in your transactional message and contains independent metrics.
The transactional message you requested does not exist.
Your request is over the 10-per-second limit.
GET /v1/transactional/{transactional_id}/metrics/links
/v1/workspaces
Returns a list of workspaces in your account.
Returns an array of workspaces.
GET /v1/workspaces
ActivitiesListResponse
{
"type": "object",
"properties": {
"next": {
"type": "string",
"description": "Indicates the next page of results. Add `?start=<next_value>` to the request to get the next page of results."
},
"activities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "01AK4N8V8G8KVA4HN8Y50CCZ59",
"description": "The identifier for the action."
},
"data": {
"oneOf": [
{
"type": "object",
"title": "Message delivery",
"example": {
"opened": null,
"delivered": null,
"delivery_id": "ZAIAAVTJVG0QcCok0-0ZKj6yiQ=="
},
"properties": {
"opened": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether or not a customer opened a message, if the message was delivered."
},
"delivered": {
"type": "integer",
"format": "unix timestamp",
"nullable": true,
"description": "The date-time when the message was delivered, if applicable."
},
"delivery_id": {
"type": "string",
"description": "The message ID."
}
}
},
{
"type": "object",
"title": "Attribute change",
"example": {
"email": {
"to": "newPerson@customer.io",
"from": "newPerson@example.com"
}
},
"description": "The name of the object is the attribute that changed.",
"additionalProperties": {
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "The new attribute value."
},
"from": {
"type": "string",
"description": "The old attribute value. If empty, the customer probably didn't bear the attribute before this action."
}
},
"x-additionalPropertyName": "Attribute Name"
}
}
]
},
"type": {
"enum": [
"attempted_action",
"attribute_change",
"failed_attribute_change",
"failed_batch_update",
"skipped_update",
"failed_query_collection",
"event",
"failed_event",
"page",
"drafted_email",
"attempted_email",
"sent_email",
"delivered_email",
"opened_email",
"clicked_email",
"converted_email",
"bounced_email",
"failed_email",
"unsubscribed_email",
"topic_unsubscribed_email",
"spammed_email",
"dropped_email",
"undeliverable_email",
"drafted_action",
"delivered_action",
"bounced_action",
"sent_action",
"opened_action",
"clicked_action",
"failed_action",
"converted_action",
"device_change",
"deferred_email",
"unsubscribed_action",
"dropped_action",
"undeliverable_action",
"deferred_action",
"profile_create",
"profile_delete",
"profile_merge",
"anon_merge",
"screen",
"webhook_event",
"add_relationship",
"delete_relationship",
"_o:<object_type_id>:create",
"_o:<object_type_id>:attribute_change",
"_o:<object_type_id>:failed_attribute_change",
"_o:<object_type_id>:delete",
"_o:<object_type_id>:add_relationship",
"_o:<object_type_id>:delete_relationship",
"_r:<object_type_id>:attribute_change",
"_r:<object_type_id>:failed_attribute_change",
"failed_object_journeys"
],
"type": "string",
"example": "sent_email",
"description": "The type of activity. Types with `_o:<object_type_id>` are for objects and types with `_r:<object_type_id>` are for relationships."
},
"timestamp": {
"type": "integer",
"format": "unix timestamp",
"example": 1397566226,
"description": "The date and time when the action occurred."
},
"customer_id": {
"type": "string",
"example": "42",
"nullable": true,
"description": "The ID of a customer profile, analogous to a \"person\" in the UI. If your workspace supports multiple identifiers (email and ID), this value can be null."
},
"delivery_id": {
"type": "string",
"example": "ZAIAAVTJVG0QcCok0-0ZKj6yiQ==",
"description": "The message ID."
},
"delivery_type": {
"enum": [
"ios",
"android",
"email",
"phone"
],
"type": "string",
"example": "email",
"description": "The recipient device, if applicable."
},
"customer_identifiers": {
"type": "object",
"required": [
"email",
"id",
"cio_id"
],
"properties": {
"id": {
"type": "string",
"example": 2,
"nullable": true,
"description": "A person's unique ID, if set. This is the same as the `customer_id` if present."
},
"email": {
"type": "string",
"format": "email",
"example": "test@example.com",
"nullable": true,
"description": "A person's email address, if set."
},
"cio_id": {
"type": "string",
"example": "a3000001",
"description": "A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers."
}
},
"description": "Contains identifiers for the person represented in a response—`id`, `cio_id`, and `email` (if your workspace uses the *Email or ID* setting). If the person's `id` or `email` is not set, the value will be null.\n\nWe recommend that you use this object rather than the less descriptive `customer_id`.\n"
}
}
}
}
}
}
BroadcastsGetActionDetailsResponse
{
"type": "object",
"properties": {
"action": {
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"readOnly": true,
"description": "The identifier for a broadcast."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"description": "The identifier for a broadcast."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
}
}
}
]
}
}
}
BroadcastsGetActionLinkMetricsResponse
{
"type": "object",
"properties": {
"links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"link": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1234,
"description": "The ID of the link."
},
"href": {
"type": "string",
"example": "https://customer.io/docs",
"description": "The link destination—a URL, mailto, etc."
}
}
},
"metric": {
"type": "object",
"properties": {
"series": {
"type": "object",
"properties": {
"clicked": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
3,
5,
7
],
"description": "An array of results from oldest to newest, where each result indicates a period."
}
}
}
},
"description": "Contains metrics for the link."
}
}
},
"description": "Each object in the array represents a link in your broadcast variant."
}
}
}
BroadcastsGetActionMetricsResponse
{
"type": "object",
"properties": {
"metric": {
"type": "object",
"properties": {
"series": {
"allOf": [
{
"type": "object",
"properties": {
"2xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "2xx responses by period, representative of webhook performance."
},
"3xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "3xx responses by period, representative of webhook performance."
},
"4xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "4xx responses by period, representative of webhook performance."
},
"5xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "5xx responses by period, representative of webhook performance."
}
},
"description": "Returns metrics in accordance with the `period` you requested. Each property in this object is an array and each entry in the array represents a metric period, i.e. if your `period` is days `[0, 1]` would represent 0 metrics for the first day, 1 for the second, etc."
},
{
"type": "object",
"properties": {
"sent": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of sent messages."
},
"failed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `failed` messages."
},
"opened": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `opened` messages."
},
"bounced": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `bounced` messages."
},
"clicked": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `clicked` messages."
},
"created": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `created` messages."
},
"drafted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `drafted` messages."
},
"spammed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of spam complaints."
},
"deferred": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `deferred` messages."
},
"attempted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `attempted` messages."
},
"converted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `converted` messages."
},
"delivered": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `delivered` messages."
},
"suppressed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `suppressed` messages."
},
"unsubscribed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of unsubscribes attributed to the campaign or message."
},
"undeliverable": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `undeliverable` messages."
},
"topic_unsubscribed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of topic unsubscribes in a given period."
}
},
"description": "Returns metrics in accordance with the `period` you requested. Each property in this object is an array and each entry in the array represents a metric period, i.e. if your `period` is days `[0, 1]` would represent 0 metrics for the first day, 1 for the second, etc."
}
]
}
}
}
}
}
BroadcastsGetActionsResponse
{
"type": "object",
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"readOnly": true,
"description": "The identifier for a broadcast."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"description": "The identifier for a broadcast."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
}
}
}
]
}
}
}
}
BroadcastsGetBroadcastErrorsResponse
{
"type": "object",
"properties": {
"next": {
"type": "string",
"description": "Indicates the next page of results. Add `?start=<next_value>` to the request to get the next page of results."
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of errors in the format `line <x>: <error text>` to help you troubleshoot errors associated with your audience or data file."
}
}
}
BroadcastsGetLinkMetricsResponse
{
"type": "object",
"properties": {
"links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"link": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1234,
"description": "The ID of the link."
},
"href": {
"type": "string",
"example": "https://customer.io/docs",
"description": "The link destination—a URL, mailto, etc."
}
}
},
"metric": {
"type": "object",
"properties": {
"series": {
"type": "object",
"properties": {
"clicked": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
3,
5,
7
],
"description": "An array of results from oldest to newest, where each result indicates a period."
}
}
}
},
"description": "Contains metrics for the link."
}
}
}
}
}
}
BroadcastsGetMessagesResponse
{
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"type": "object",
"example": {
"id": "ag1q6QWq6QUBAAF4_CGoeVX7mFkDbRFu7ek=X",
"type": "email",
"created": 1619137767,
"metrics": {
"sent": 1619137768,
"delivered": 1619137768
},
"subject": "Did you get that thing I sent you?",
"action_id": 215,
"forgotten": false,
"recipient": "person@example.com",
"content_id": null,
"campaign_id": 23,
"customer_id": null,
"broadcast_id": null,
"newsletter_id": null,
"deduplicate_id": "ag1q6QWq6QUBAAF4_CGoeVX7mFkDbRFu7ek=:1619137768",
"failure_message": null,
"msg_template_id": 43,
"parent_action_id": null,
"trigger_event_id": null
},
"properties": {
"id": {
"type": "string",
"example": "dgOq6QWq6QUBAAF4_CGoeVX7mFkDbRFu7ek=",
"readOnly": true,
"description": "The identifier for a delivery—the instance of a message intended for an individual recipient."
},
"type": {
"enum": [
"email",
"webhook",
"twilio",
"slack",
"push"
],
"type": "string",
"example": "email",
"readOnly": true,
"description": "The type of message/action."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"metrics": {
"type": "object",
"properties": {
"sent": {
"type": "integer",
"description": "The timestamp when the message was `sent`."
},
"failed": {
"type": "integer",
"description": "The timestamp when the message `failed`."
},
"opened": {
"type": "integer",
"description": "The timestamp when the message was `opened`."
},
"bounced": {
"type": "integer",
"description": "The timestamp when the message `bounced`."
},
"clicked": {
"type": "integer",
"description": "The timestamp when the message was `clicked`."
},
"created": {
"type": "integer",
"description": "The timestamp when the message was `created`."
},
"drafted": {
"type": "integer",
"description": "The timestamp when the message was `drafted`."
},
"dropped": {
"type": "integer",
"description": "The timestamp when the message was `dropped`."
},
"spammed": {
"type": "integer",
"description": "The timestamp when the message was marked as spam."
},
"converted": {
"type": "integer",
"description": "The timestamp when the message was `converted`."
},
"delivered": {
"type": "integer",
"description": "The timestamp when the message was `delivered`."
},
"unsubscribed": {
"type": "integer",
"description": "The timestamp when a person unsubscribed based on this message."
},
"undeliverable": {
"type": "integer",
"description": "The timestamp when the message became `undeliverable`."
}
},
"description": "Metrics for an individual instance of a message; each item in the object represents the timestamp when a message achieved a particular metric. This object only contains metrics that have been recorded."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"action_id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"forgotten": {
"type": "boolean",
"description": "If true message contents are not retained by Customer.io."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"content_id": {
"type": "integer",
"example": 1,
"nullable": true,
"readOnly": true,
"description": "The identifier for a newsletter variant."
},
"campaign_id": {
"type": "integer",
"example": 5,
"nullable": true,
"description": "The identifier for a campaign."
},
"customer_id": {
"type": "string",
"example": "42",
"nullable": true,
"description": "The ID of a customer profile, analogous to a \"person\" in the UI. If your workspace supports multiple identifiers (email and ID), this value can be null."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"nullable": true,
"description": "The identifier for a broadcast."
},
"newsletter_id": {
"type": "integer",
"example": 10,
"nullable": true,
"description": "The identifier for a newsletter."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"failure_message": {
"type": "string",
"nullable": true,
"description": "Explains why a message failed, if applicable."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
},
"trigger_event_id": {
"type": "string",
"example": "21E4C3CT6YDC7Y4N7FE1GWWABC",
"nullable": true,
"description": "The id of the event that triggered an event-triggered campaign (not an API-triggered broadcast)."
},
"message_template_id": {
"type": "integer",
"readOnly": true,
"deprecated": true,
"description": "The identifier of the message template used to create a message."
},
"customer_identifiers": {
"type": "object",
"required": [
"email",
"id",
"cio_id"
],
"properties": {
"id": {
"type": "string",
"example": 2,
"nullable": true,
"description": "A person's unique ID, if set. This is the same as the `customer_id` if present."
},
"email": {
"type": "string",
"format": "email",
"example": "test@example.com",
"nullable": true,
"description": "A person's email address, if set."
},
"cio_id": {
"type": "string",
"example": "a3000001",
"description": "A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers."
}
},
"description": "Contains identifiers for the person represented in a response—`id`, `cio_id`, and `email` (if your workspace uses the *Email or ID* setting). If the person's `id` or `email` is not set, the value will be null.\n\nWe recommend that you use this object rather than the less descriptive `customer_id`.\n"
}
},
"description": "Describes an individual message delivery. The object contains keys for all possible parents of the message (`newsletter_id`, `broadcast_id`, etc) but only the parents of the delivery are populated. Other parent IDs are null."
},
"example": [
{
"id": "dgOq6QWq6QUDAAF22PaOyFVqVxHY3rI5fsg=",
"type": "email",
"created": 1609957805,
"metrics": {
"sent": 1609957832,
"delivered": 1609957872
},
"subject": "Did you get that thing I sent you?",
"action_id": 196,
"forgotten": false,
"recipient": "person@example.com",
"content_id": null,
"campaign_id": null,
"customer_id": "1a55d8d1-b13d-4f1f-858f-a93ef21e3a7d",
"broadcast_id": 94,
"newsletter_id": null,
"deduplicate_id": "dgOq6QWq6QUDAAF22PaOyFVqVxHY3rI5fsg=:1609957872",
"failure_message": null,
"msg_template_id": 0,
"customer_identifiers": {
"id": "1a55d8d1-b13d-4f1f-858f-a93ef21e3a7d",
"email": "person@example.com",
"cio_id": 786433
}
}
]
}
}
}
BroadcastsGetMetadataResponse
{
"type": "object",
"properties": {
"broadcast": {
"type": "object",
"example": {
"id": 2,
"name": "basic",
"tags": "nil",
"type": "triggered_broadcast",
"active": true,
"actions": [
{
"id": 3,
"type": "email"
},
{
"id": 4
},
{
"type": "webhook"
}
],
"created": 1520467200,
"updated": 1520467200,
"created_by": "ExamplePerson",
"first_started": 1520467200,
"deduplicate_id": "2:1520467200"
},
"properties": {
"id": {
"type": "integer",
"example": 2,
"description": "The identifier for a broadcast."
},
"name": {
"type": "string",
"readOnly": true,
"description": "The name of the broadcast."
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "An array of tags you set on this broadcast."
},
"active": {
"type": "boolean",
"description": "If true, the broadcast is active."
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The identifier for the action."
},
"type": {
"enum": [
"email",
"webhook",
"push",
"sms",
"slack"
],
"type": "string",
"description": "The type of action."
}
}
},
"description": "A list of actions used by the broadcast."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"msg_template_ids": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The identifier for the template."
},
"type": {
"enum": [
"email",
"webhook",
"push",
"sms",
"slack"
],
"type": "string",
"description": "The type of template."
}
}
},
"deprecated": true,
"description": "Indicates the message template(s) used in this broadcast."
}
}
}
}
}
BroadcastsGetMetricsResponse
{
"type": "object",
"properties": {
"metric": {
"type": "object",
"properties": {
"series": {
"allOf": [
{
"type": "object",
"properties": {
"2xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "2xx responses by period, representative of webhook performance."
},
"3xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "3xx responses by period, representative of webhook performance."
},
"4xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "4xx responses by period, representative of webhook performance."
},
"5xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "5xx responses by period, representative of webhook performance."
}
},
"description": "Returns metrics in accordance with the `period` you requested. Each property in this object is an array and each entry in the array represents a metric period, i.e. if your `period` is days `[0, 1]` would represent 0 metrics for the first day, 1 for the second, etc."
},
{
"type": "object",
"properties": {
"sent": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of sent messages."
},
"failed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `failed` messages."
},
"opened": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `opened` messages."
},
"bounced": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `bounced` messages."
},
"clicked": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `clicked` messages."
},
"created": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `created` messages."
},
"drafted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `drafted` messages."
},
"spammed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of spam complaints."
},
"deferred": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `deferred` messages."
},
"attempted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `attempted` messages."
},
"converted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `converted` messages."
},
"delivered": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `delivered` messages."
},
"suppressed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `suppressed` messages."
},
"unsubscribed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of unsubscribes attributed to the campaign or message."
},
"undeliverable": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `undeliverable` messages."
},
"topic_unsubscribed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of topic unsubscribes in a given period."
}
},
"description": "Returns metrics in accordance with the `period` you requested. Each property in this object is an array and each entry in the array represents a metric period, i.e. if your `period` is days `[0, 1]` would represent 0 metrics for the first day, 1 for the second, etc."
}
]
}
}
}
}
}
BroadcastsGetStatusResponse
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The identifier for a broadcast trigger."
},
"created_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"description": "The identifier for a broadcast."
},
"processed_at": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when Customer.io processed the trigger."
}
},
"description": "You can get triggers to know when you triggered a broadcast and whether or not it's been processed."
}
BroadcastsGetTranslationMessageResponse
{
"type": "object",
"properties": {
"action": {
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"readOnly": true,
"description": "The identifier for a broadcast."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"description": "The identifier for a broadcast."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
}
}
}
]
}
}
}
BroadcastsGetTriggersResponse
{
"type": "object",
"properties": {
"triggers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The identifier for a broadcast trigger."
},
"created_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"description": "The identifier for a broadcast."
},
"processed_at": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when Customer.io processed the trigger."
}
},
"description": "You can get triggers to know when you triggered a broadcast and whether or not it's been processed."
},
"description": "Each object in the array represents a time that your broadcast was triggered/sent."
}
}
}
BroadcastsListResponse
{
"type": "object",
"properties": {
"broadcasts": {
"type": "array",
"items": {
"type": "object",
"example": {
"id": 2,
"name": "basic",
"tags": "nil",
"type": "triggered_broadcast",
"active": true,
"actions": [
{
"id": 3,
"type": "email"
},
{
"id": 4
},
{
"type": "webhook"
}
],
"created": 1520467200,
"updated": 1520467200,
"created_by": "ExamplePerson",
"first_started": 1520467200,
"deduplicate_id": "2:1520467200"
},
"properties": {
"id": {
"type": "integer",
"example": 2,
"description": "The identifier for a broadcast."
},
"name": {
"type": "string",
"readOnly": true,
"description": "The name of the broadcast."
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "An array of tags you set on this broadcast."
},
"active": {
"type": "boolean",
"description": "If true, the broadcast is active."
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The identifier for the action."
},
"type": {
"enum": [
"email",
"webhook",
"push",
"sms",
"slack"
],
"type": "string",
"description": "The type of action."
}
}
},
"description": "A list of actions used by the broadcast."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"msg_template_ids": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The identifier for the template."
},
"type": {
"enum": [
"email",
"webhook",
"push",
"sms",
"slack"
],
"type": "string",
"description": "The type of template."
}
}
},
"deprecated": true,
"description": "Indicates the message template(s) used in this broadcast."
}
}
}
}
}
}
BroadcastsUpdateActionContentsRequest
{
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"readOnly": true,
"description": "The identifier for a broadcast."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"description": "The identifier for a broadcast."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
}
}
}
]
}
BroadcastsUpdateActionContentsResponse
{
"type": "object",
"properties": {
"action": {
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"readOnly": true,
"description": "The identifier for a broadcast."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"description": "The identifier for a broadcast."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
}
}
}
]
}
}
}
BroadcastsUpdateTranslationRequest
{
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"readOnly": true,
"description": "The identifier for a broadcast."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"description": "The identifier for a broadcast."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
}
}
}
]
}
BroadcastsUpdateTranslationResponse
{
"type": "object",
"properties": {
"action": {
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"readOnly": true,
"description": "The identifier for a broadcast."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"description": "The body of the action. You cannot modify the body if you created it with our drag-and-drop editor."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"description": "The identifier for a broadcast."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
}
}
}
]
}
}
}
CampaignsGetActionInfoResponse
{
"type": "object",
"properties": {
"action": {
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "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."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"campaign_id": {
"type": "integer",
"example": 5,
"readOnly": true,
"description": "The identifier for a campaign."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"example": "{\"attribute\":\"cool-webhook\"}",
"description": "The payload for your webhook."
},
"name": {
"type": "string",
"example": "Set attribute",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"campaign_id": {
"type": "integer",
"example": 5,
"description": "The identifier for a campaign."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
}
]
}
}
}
CampaignsGetActionMetricsResponse
{
"type": "object",
"properties": {
"metric": {
"type": "object",
"properties": {
"series": {
"allOf": [
{
"type": "object",
"properties": {
"2xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "2xx responses by period, representative of webhook performance."
},
"3xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "3xx responses by period, representative of webhook performance."
},
"4xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "4xx responses by period, representative of webhook performance."
},
"5xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "5xx responses by period, representative of webhook performance."
}
},
"description": "Returns metrics in accordance with the `period` you requested. Each property in this object is an array and each entry in the array represents a metric period, i.e. if your `period` is days `[0, 1]` would represent 0 metrics for the first day, 1 for the second, etc."
},
{
"type": "object",
"properties": {
"sent": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of sent messages."
},
"failed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `failed` messages."
},
"opened": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `opened` messages."
},
"bounced": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `bounced` messages."
},
"clicked": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `clicked` messages."
},
"created": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `created` messages."
},
"drafted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `drafted` messages."
},
"spammed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of spam complaints."
},
"deferred": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `deferred` messages."
},
"attempted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `attempted` messages."
},
"converted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `converted` messages."
},
"delivered": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `delivered` messages."
},
"suppressed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `suppressed` messages."
},
"unsubscribed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of unsubscribes attributed to the campaign or message."
},
"undeliverable": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `undeliverable` messages."
},
"topic_unsubscribed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of topic unsubscribes in a given period."
}
},
"description": "Returns metrics in accordance with the `period` you requested. Each property in this object is an array and each entry in the array represents a metric period, i.e. if your `period` is days `[0, 1]` would represent 0 metrics for the first day, 1 for the second, etc."
}
]
}
}
}
}
}
CampaignsGetJourneyMetricsResponse
{
"type": "object",
"properties": {
"journey_metric": {
"type": "object",
"properties": {
"started": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The total number of people who meet the trigger criteria for a journey. This count occurs before filters are applied."
},
"finished": {
"type": "array",
"items": {
"type": "integer"
},
"description": "People who finished the journey."
},
"messaged": {
"type": "array",
"items": {
"type": "integer"
},
"description": "People who experienced at least one non-delay action in the journey. This metric typically represents journeys in progress."
},
"activated": {
"type": "array",
"items": {
"type": "integer"
},
"description": "People who started a journey and were not filtered out before they experienced an action."
},
"converted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "People who met the conversion goal (entered a segment) for the campaign."
},
"exited_early": {
"type": "array",
"items": {
"type": "integer"
},
"description": "People who started a journey but stopped meeting the campaign trigger/filter criteria following a delay or grace period."
},
"never_activated": {
"type": "array",
"items": {
"type": "integer"
},
"description": "People who started a journey but were filtered out before they could experience any of the actions in the journey."
}
}
}
}
}
CampaignsGetLinkMetricsForActionResponse
{
"type": "object",
"properties": {
"links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"link": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1234,
"description": "The ID of the link."
},
"href": {
"type": "string",
"example": "https://customer.io/docs",
"description": "The link destination—a URL, mailto, etc."
}
}
},
"metric": {
"type": "object",
"properties": {
"series": {
"type": "object",
"properties": {
"clicked": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
3,
5,
7
],
"description": "An array of results from oldest to newest, where each result indicates a period."
}
}
}
},
"description": "Contains metrics for the link."
}
}
},
"description": "Each object in the array represents a link in your action."
}
}
}
CampaignsGetLinkMetricsResponse
{
"type": "object",
"properties": {
"links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"link": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1234,
"description": "The ID of the link."
},
"href": {
"type": "string",
"example": "https://customer.io/docs",
"description": "The link destination—a URL, mailto, etc."
}
}
},
"metric": {
"type": "object",
"properties": {
"series": {
"type": "object",
"properties": {
"clicked": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
3,
5,
7
],
"description": "An array of results from oldest to newest, where each result indicates a period."
}
}
}
},
"description": "Contains metrics for the link."
}
}
}
}
}
}
CampaignsGetListResponse
{
"type": "object",
"properties": {
"campaigns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 5,
"description": "The identifier for a campaign."
},
"name": {
"type": "string",
"readOnly": true,
"description": "The name of the campaign."
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"new",
"welcome"
],
"description": "An array of tags you set on this campaign."
},
"type": {
"enum": [
"segment"
],
"type": "string",
"description": "The type of campaign."
},
"active": {
"type": "boolean",
"description": "If true, the campaign is active and can still send messages."
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The identifier for the action."
},
"type": {
"enum": [
"email",
"sms",
"push",
"slack",
"webhook"
],
"type": "string",
"description": "The message type actions resulting from the campaign."
}
}
},
"description": "An array of actions contained within the campaign."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"created_by": {
"type": "string",
"format": "email",
"example": "hugh.mann@example.com",
"description": "The email address of the person who created the campaign."
},
"first_started": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"description": "The date and time when you first started the campaign and it first became eligible to be triggered."
},
"msg_templates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The identifier for the template."
},
"type": {
"enum": [
"email",
"sms",
"push",
"slack"
],
"type": "string",
"description": "The message type the template represents."
}
}
},
"deprecated": true,
"description": "Indicates the message templates used in this campaign."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"filter_segment_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
21,
42
],
"description": "A list of segments used in the campaign filter, returned if the campaign audience was filtered on one or more segments."
},
"trigger_segment_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
90
],
"description": "A list of segments used in the campaign trigger, returned if the campaign trigger included one or more segment conditions."
}
}
}
}
}
}
CampaignsGetMessageMetadataResponse
{
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"type": "object",
"example": {
"id": "ag1q6QWq6QUBAAF4_CGoeVX7mFkDbRFu7ek=X",
"type": "email",
"created": 1619137767,
"metrics": {
"sent": 1619137768,
"delivered": 1619137768
},
"subject": "Did you get that thing I sent you?",
"action_id": 215,
"forgotten": false,
"recipient": "person@example.com",
"content_id": null,
"campaign_id": 23,
"customer_id": null,
"broadcast_id": null,
"newsletter_id": null,
"deduplicate_id": "ag1q6QWq6QUBAAF4_CGoeVX7mFkDbRFu7ek=:1619137768",
"failure_message": null,
"msg_template_id": 43,
"parent_action_id": null,
"trigger_event_id": null
},
"properties": {
"id": {
"type": "string",
"example": "dgOq6QWq6QUBAAF4_CGoeVX7mFkDbRFu7ek=",
"readOnly": true,
"description": "The identifier for a delivery—the instance of a message intended for an individual recipient."
},
"type": {
"enum": [
"email",
"webhook",
"twilio",
"slack",
"push"
],
"type": "string",
"example": "email",
"readOnly": true,
"description": "The type of message/action."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"metrics": {
"type": "object",
"properties": {
"sent": {
"type": "integer",
"description": "The timestamp when the message was `sent`."
},
"failed": {
"type": "integer",
"description": "The timestamp when the message `failed`."
},
"opened": {
"type": "integer",
"description": "The timestamp when the message was `opened`."
},
"bounced": {
"type": "integer",
"description": "The timestamp when the message `bounced`."
},
"clicked": {
"type": "integer",
"description": "The timestamp when the message was `clicked`."
},
"created": {
"type": "integer",
"description": "The timestamp when the message was `created`."
},
"drafted": {
"type": "integer",
"description": "The timestamp when the message was `drafted`."
},
"dropped": {
"type": "integer",
"description": "The timestamp when the message was `dropped`."
},
"spammed": {
"type": "integer",
"description": "The timestamp when the message was marked as spam."
},
"converted": {
"type": "integer",
"description": "The timestamp when the message was `converted`."
},
"delivered": {
"type": "integer",
"description": "The timestamp when the message was `delivered`."
},
"unsubscribed": {
"type": "integer",
"description": "The timestamp when a person unsubscribed based on this message."
},
"undeliverable": {
"type": "integer",
"description": "The timestamp when the message became `undeliverable`."
}
},
"description": "Metrics for an individual instance of a message; each item in the object represents the timestamp when a message achieved a particular metric. This object only contains metrics that have been recorded."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"action_id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"forgotten": {
"type": "boolean",
"description": "If true message contents are not retained by Customer.io."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"content_id": {
"type": "integer",
"example": 1,
"nullable": true,
"readOnly": true,
"description": "The identifier for a newsletter variant."
},
"campaign_id": {
"type": "integer",
"example": 5,
"nullable": true,
"description": "The identifier for a campaign."
},
"customer_id": {
"type": "string",
"example": "42",
"nullable": true,
"description": "The ID of a customer profile, analogous to a \"person\" in the UI. If your workspace supports multiple identifiers (email and ID), this value can be null."
},
"broadcast_id": {
"type": "integer",
"example": 2,
"nullable": true,
"description": "The identifier for a broadcast."
},
"newsletter_id": {
"type": "integer",
"example": 10,
"nullable": true,
"description": "The identifier for a newsletter."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"failure_message": {
"type": "string",
"nullable": true,
"description": "Explains why a message failed, if applicable."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
},
"trigger_event_id": {
"type": "string",
"example": "21E4C3CT6YDC7Y4N7FE1GWWABC",
"nullable": true,
"description": "The id of the event that triggered an event-triggered campaign (not an API-triggered broadcast)."
},
"message_template_id": {
"type": "integer",
"readOnly": true,
"deprecated": true,
"description": "The identifier of the message template used to create a message."
},
"customer_identifiers": {
"type": "object",
"required": [
"email",
"id",
"cio_id"
],
"properties": {
"id": {
"type": "string",
"example": 2,
"nullable": true,
"description": "A person's unique ID, if set. This is the same as the `customer_id` if present."
},
"email": {
"type": "string",
"format": "email",
"example": "test@example.com",
"nullable": true,
"description": "A person's email address, if set."
},
"cio_id": {
"type": "string",
"example": "a3000001",
"description": "A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers."
}
},
"description": "Contains identifiers for the person represented in a response—`id`, `cio_id`, and `email` (if your workspace uses the *Email or ID* setting). If the person's `id` or `email` is not set, the value will be null.\n\nWe recommend that you use this object rather than the less descriptive `customer_id`.\n"
}
},
"description": "Describes an individual message delivery. The object contains keys for all possible parents of the message (`newsletter_id`, `broadcast_id`, etc) but only the parents of the delivery are populated. Other parent IDs are null."
},
"example": [
{
"id": "dgOq6QWq6QUDAAF22PaOyFVqVxHY3rI5fsg=X",
"type": "email",
"created": 1609957805,
"metrics": {
"sent": 1609957832,
"delivered": 1609957872
},
"subject": "Did you get that thing I sent you?",
"action_id": 196,
"forgotten": false,
"recipient": "person@email.com",
"content_id": null,
"campaign_id": 89,
"customer_id": "1a55d8d1-b13d-4f1f-858f-a93ef21e3a7d",
"broadcast_id": null,
"newsletter_id": null,
"deduplicate_id": "dgOq6QWq6QUDAAF22PaOyFVqVxHY3rI5fsg=:1609957872",
"failure_message": null,
"msg_template_id": 0,
"customer_identifiers": {
"id": "1a55d8d1-b13d-4f1f-858f-a93ef21e3a7dX",
"email": "person@example.com",
"cio_id": 786433
}
}
]
}
}
}
CampaignsGetMessageTranslationResponse
{
"type": "object",
"properties": {
"action": {
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "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."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"campaign_id": {
"type": "integer",
"example": 5,
"readOnly": true,
"description": "The identifier for a campaign."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"example": "{\"attribute\":\"cool-webhook\"}",
"description": "The payload for your webhook."
},
"name": {
"type": "string",
"example": "Set attribute",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"campaign_id": {
"type": "integer",
"example": 5,
"description": "The identifier for a campaign."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
}
]
}
}
}
CampaignsGetMetadataResponse
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 5,
"description": "The identifier for a campaign."
},
"name": {
"type": "string",
"readOnly": true,
"description": "The name of the campaign."
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"new",
"welcome"
],
"description": "An array of tags you set on this campaign."
},
"type": {
"enum": [
"segment"
],
"type": "string",
"description": "The type of campaign."
},
"active": {
"type": "boolean",
"description": "If true, the campaign is active and can still send messages."
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The identifier for the action."
},
"type": {
"enum": [
"email",
"sms",
"push",
"slack",
"webhook"
],
"type": "string",
"description": "The message type actions resulting from the campaign."
}
}
},
"description": "An array of actions contained within the campaign."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"created_by": {
"type": "string",
"format": "email",
"example": "hugh.mann@example.com",
"description": "The email address of the person who created the campaign."
},
"first_started": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"description": "The date and time when you first started the campaign and it first became eligible to be triggered."
},
"msg_templates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The identifier for the template."
},
"type": {
"enum": [
"email",
"sms",
"push",
"slack"
],
"type": "string",
"description": "The message type the template represents."
}
}
},
"deprecated": true,
"description": "Indicates the message templates used in this campaign."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"filter_segment_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
21,
42
],
"description": "A list of segments used in the campaign filter, returned if the campaign audience was filtered on one or more segments."
},
"trigger_segment_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
90
],
"description": "A list of segments used in the campaign trigger, returned if the campaign trigger included one or more segment conditions."
}
}
}
}
}
CampaignsGetMetricsResponse
{
"type": "object",
"properties": {
"metric": {
"type": "object",
"properties": {
"series": {
"allOf": [
{
"type": "object",
"properties": {
"2xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "2xx responses by period, representative of webhook performance."
},
"3xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "3xx responses by period, representative of webhook performance."
},
"4xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "4xx responses by period, representative of webhook performance."
},
"5xx": {
"type": "array",
"items": {
"type": "integer"
},
"description": "5xx responses by period, representative of webhook performance."
}
},
"description": "Returns metrics in accordance with the `period` you requested. Each property in this object is an array and each entry in the array represents a metric period, i.e. if your `period` is days `[0, 1]` would represent 0 metrics for the first day, 1 for the second, etc."
},
{
"type": "object",
"properties": {
"sent": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of sent messages."
},
"failed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `failed` messages."
},
"opened": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `opened` messages."
},
"bounced": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `bounced` messages."
},
"clicked": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `clicked` messages."
},
"created": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `created` messages."
},
"drafted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `drafted` messages."
},
"spammed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of spam complaints."
},
"deferred": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `deferred` messages."
},
"attempted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `attempted` messages."
},
"converted": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `converted` messages."
},
"delivered": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `delivered` messages."
},
"suppressed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `suppressed` messages."
},
"unsubscribed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of unsubscribes attributed to the campaign or message."
},
"undeliverable": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of `undeliverable` messages."
},
"topic_unsubscribed": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The number of topic unsubscribes in a given period."
}
},
"description": "Returns metrics in accordance with the `period` you requested. Each property in this object is an array and each entry in the array represents a metric period, i.e. if your `period` is days `[0, 1]` would represent 0 metrics for the first day, 1 for the second, etc."
}
]
}
}
}
}
}
CampaignsListActionsResponse
{
"type": "object",
"properties": {
"next": {
"type": "string",
"description": "Indicates the next page of results. Add `?start=<next_value>` to the request to get the next page of results."
},
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "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."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"campaign_id": {
"type": "integer",
"example": 5,
"readOnly": true,
"description": "The identifier for a campaign."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"example": "{\"attribute\":\"cool-webhook\"}",
"description": "The payload for your webhook."
},
"name": {
"type": "string",
"example": "Set attribute",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"campaign_id": {
"type": "integer",
"example": 5,
"description": "The identifier for a campaign."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
}
]
},
"maxItems": 10,
"description": "Each object in the array represents an action in your campaign."
}
}
}
CampaignsUpdateActionContentsRequest
{
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "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."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"campaign_id": {
"type": "integer",
"example": 5,
"readOnly": true,
"description": "The identifier for a campaign."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"example": "{\"attribute\":\"cool-webhook\"}",
"description": "The payload for your webhook."
},
"name": {
"type": "string",
"example": "Set attribute",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"campaign_id": {
"type": "integer",
"example": 5,
"description": "The identifier for a campaign."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
}
]
}
CampaignsUpdateActionContentsResponse
{
"type": "object",
"properties": {
"action": {
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "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."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"campaign_id": {
"type": "integer",
"example": 5,
"readOnly": true,
"description": "The identifier for a campaign."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"example": "{\"attribute\":\"cool-webhook\"}",
"description": "The payload for your webhook."
},
"name": {
"type": "string",
"example": "Set attribute",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"campaign_id": {
"type": "integer",
"example": 5,
"description": "The identifier for a campaign."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
}
]
}
}
}
CampaignsUpdateTranslationRequest
{
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "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."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"campaign_id": {
"type": "integer",
"example": 5,
"readOnly": true,
"description": "The identifier for a campaign."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"example": "{\"attribute\":\"cool-webhook\"}",
"description": "The payload for your webhook."
},
"name": {
"type": "string",
"example": "Set attribute",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"campaign_id": {
"type": "integer",
"example": 5,
"description": "The identifier for a campaign."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
}
]
}
CampaignsUpdateTranslationResponse
{
"type": "object",
"properties": {
"action": {
"oneOf": [
{
"type": "object",
"title": "Email / message",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"bcc": {
"type": "string",
"readOnly": true,
"description": "The blind-copy address(es) for this action."
},
"body": {
"type": "string",
"description": "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."
},
"from": {
"type": "string",
"example": "sentFrom@example.com",
"readOnly": true,
"description": "The address that the message is from, relevant if the action `type` is `email`."
},
"name": {
"type": "string",
"example": "Opening Message",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"email",
"in_app",
"push",
"twilio",
"slack"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"from_id": {
"type": "integer",
"example": 1,
"description": "The identifier of the `from` address, commonly known as the \"sender\". You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"subject": {
"type": "string",
"example": "Did you get that thing I sent you?",
"description": "The subject line for an `email` action."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"body_amp": {
"type": "string",
"description": "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."
},
"fake_bcc": {
"type": "boolean",
"readOnly": true,
"description": "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).\n"
},
"language": {
"type": "string",
"example": "fr",
"readOnly": true,
"description": "The language variant for your message. If you don't use our [localization feature](https://customer.io/docs/api/app/), or this is the default message, this value is an empty string."
},
"reply_to": {
"type": "string",
"example": "replyto@example.com",
"readOnly": true,
"description": "The address that receives replies for the message, if applicable."
},
"recipient": {
"type": "string",
"example": "{{customer.email}}",
"description": "The recipient address for an action."
},
"campaign_id": {
"type": "integer",
"example": 5,
"readOnly": true,
"description": "The identifier for a campaign."
},
"reply_to_id": {
"type": "integer",
"example": 38,
"nullable": true,
"description": "The identifier for the `reply_to` address, if applicable. You can [list your sender identities](https://customer.io/docs/api/app/) to match the ID to a specific address."
},
"preprocessor": {
"enum": [
"premailer"
],
"type": "string",
"readOnly": true,
"description": "By default, we process CSS before emails leave Customer.io using Premailer. If your message included CSS and pre-processing is not disabled, this key indicates the pre-processor."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"preheader_text": {
"type": "string",
"description": "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."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
},
{
"type": "object",
"title": "Webhook",
"properties": {
"id": {
"type": "integer",
"example": 96,
"nullable": true,
"readOnly": true,
"description": "The identifier for an action."
},
"url": {
"type": "string",
"example": "https://my.example.com/webhook",
"description": "The URL to send a webhook to, applies to `webhook` type actions."
},
"body": {
"type": "string",
"example": "{\"attribute\":\"cool-webhook\"}",
"description": "The payload for your webhook."
},
"name": {
"type": "string",
"example": "Set attribute",
"readOnly": true,
"description": "The name of the action, if it exists."
},
"type": {
"enum": [
"webhook"
],
"type": "string",
"readOnly": true,
"description": "The type of action."
},
"layout": {
"type": "string",
"readOnly": true,
"description": "The layout used for the action, if it exists."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch"
],
"type": "string",
"example": "post",
"description": "The HTTP method for your webhook."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "X-Mailgun-Tag",
"description": "name of header"
},
"value": {
"type": "string",
"example": "tag-name-for-tracking",
"description": "value of header"
}
}
},
"description": "Headers must be strings and cannot contain any non-ASCII characters or empty spaces. Some headers are reserved and cannot be overwritten."
},
"updated": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
},
"campaign_id": {
"type": "integer",
"example": 5,
"description": "The identifier for a campaign."
},
"sending_state": {
"enum": [
"automatic",
"draft",
"off"
],
"type": "string",
"description": "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."
},
"deduplicate_id": {
"type": "string",
"example": "15:1492548073",
"readOnly": true,
"description": "An identifier in the format `id:timestamp` where the id is the id of the object you are working with (Campaigns, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated."
},
"parent_action_id": {
"type": "integer",
"example": 1,
"readOnly": true,
"description": "The ID of the parent action, if the action occurred within a campaign and has a parent (like a randomized split, etc)."
}
}
}
]
}
}
}
CollectionsCreateNewRequest
{
"oneOf": [
{
"type": "object",
"title": "Local data",
"required": [
"name",
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"x-additionalPropertiesName": "collection data"
}
},
"description": "An array of data objects that you want to reference in this collection."
},
"name": {
"type": "string",
"description": "The name of the collection. This is how you'll reference your collection in messages—`{{collection_name.data-property}}`."
}
}
},
{
"type": "object",
"title": "Data by URL",
"required": [
"name",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "url",
"description": "The URL for your CSV or JSON data. If your URL does not return a `Content-Type`, we use the file extension; otherwise, Customer.io assumes your data is JSON.\n"
},
"name": {
"type": "string",
"description": "The name of the collection. This is how you'll reference your collection in messages—`{{collection_name.data-property}}`."
}
}
}
]
}
CollectionsCreateNewResponse
{
"type": "object",
"properties": {
"collection": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1,
"description": "The identifier for the collection. This is how you'll reference the collection from the API."
},
"name": {
"type": "string",
"example": "upcoming events",
"description": "The name of the collection. This is how you'll reference the collection in liquid, e.g. `{{collection_name.data_property}}`."
},
"rows": {
"type": "integer",
"example": 2,
"description": "Represents the number of objects in the `data` array or CSV rows in your collection schema."
},
"bytes": {
"type": "integer",
"example": 296,
"description": "The size of the collection in bytes."
},
"schema": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"eventDate",
"eventName",
"presents"
],
"description": "Lists the top-level keys that you can reference within this collection. Customer.io does not enforce any of these keys as required from your `data`."
},
"created_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"updated_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
}
}
}
}
}
CollectionsGetContentsResponse
{
"type": "object",
"additionalProperties": {
"x-additionalPropertiesName": "collection data"
}
}
CollectionsGetDetailsResponse
{
"type": "object",
"properties": {
"collection": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1,
"description": "The identifier for the collection. This is how you'll reference the collection from the API."
},
"name": {
"type": "string",
"example": "upcoming events",
"description": "The name of the collection. This is how you'll reference the collection in liquid, e.g. `{{collection_name.data_property}}`."
},
"rows": {
"type": "integer",
"example": 2,
"description": "Represents the number of objects in the `data` array or CSV rows in your collection schema."
},
"bytes": {
"type": "integer",
"example": 296,
"description": "The size of the collection in bytes."
},
"schema": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"eventDate",
"eventName",
"presents"
],
"description": "Lists the top-level keys that you can reference within this collection. Customer.io does not enforce any of these keys as required from your `data`."
},
"created_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"updated_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
}
}
}
}
}
CollectionsListResponse
{
"type": "object",
"properties": {
"collections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1,
"description": "The identifier for the collection. This is how you'll reference the collection from the API."
},
"name": {
"type": "string",
"example": "upcoming events",
"description": "The name of the collection. This is how you'll reference the collection in liquid, e.g. `{{collection_name.data_property}}`."
},
"rows": {
"type": "integer",
"example": 2,
"description": "Represents the number of objects in the `data` array or CSV rows in your collection schema."
},
"bytes": {
"type": "integer",
"example": 296,
"description": "The size of the collection in bytes."
},
"schema": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"eventDate",
"eventName",
"presents"
],
"description": "Lists the top-level keys that you can reference within this collection. Customer.io does not enforce any of these keys as required from your `data`."
},
"created_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"updated_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
}
}
}
}
}
}
CollectionsUpdateCollectionRequest
{
"oneOf": [
{
"type": "object",
"title": "Local data",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"x-additionalPropertiesName": "collection data"
}
},
"description": "An array of data objects that you want to reference in this collection."
},
"name": {
"type": "string",
"description": "The name of the collection. This is how you'll reference your collection in messages—`{{collection_name.data-property}}`."
}
}
},
{
"type": "object",
"title": "Data by URL",
"properties": {
"url": {
"type": "string",
"format": "url",
"description": "The URL for your CSV or JSON data. If your URL does not return a `Content-Type`, we use the file extension; otherwise, Customer.io assumes your data is JSON.\n"
},
"name": {
"type": "string",
"description": "The name of the collection. This is how you'll reference your collection in messages—`{{collection_name.data-property}}`."
}
}
}
]
}
CollectionsUpdateCollectionResponse
{
"type": "object",
"properties": {
"collection": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1,
"description": "The identifier for the collection. This is how you'll reference the collection from the API."
},
"name": {
"type": "string",
"example": "upcoming events",
"description": "The name of the collection. This is how you'll reference the collection in liquid, e.g. `{{collection_name.data_property}}`."
},
"rows": {
"type": "integer",
"example": 2,
"description": "Represents the number of objects in the `data` array or CSV rows in your collection schema."
},
"bytes": {
"type": "integer",
"example": 296,
"description": "The size of the collection in bytes."
},
"schema": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"eventDate",
"eventName",
"presents"
],
"description": "Lists the top-level keys that you can reference within this collection. Customer.io does not enforce any of these keys as required from your `data`."
},
"created_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"updated_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
}
}
}
}
}
CollectionsUpdateContentsRequest
{
"type": "object",
"additionalProperties": {
"x-additionalPropertiesName": "collection contents"
}
}
CollectionsUpdateContentsResponse
{
"type": "object",
"properties": {
"collection": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1,
"description": "The identifier for the collection. This is how you'll reference the collection from the API."
},
"name": {
"type": "string",
"example": "upcoming events",
"description": "The name of the collection. This is how you'll reference the collection in liquid, e.g. `{{collection_name.data_property}}`."
},
"rows": {
"type": "integer",
"example": 2,
"description": "Represents the number of objects in the `data` array or CSV rows in your collection schema."
},
"bytes": {
"type": "integer",
"example": 296,
"description": "The size of the collection in bytes."
},
"schema": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"eventDate",
"eventName",
"presents"
],
"description": "Lists the top-level keys that you can reference within this collection. Customer.io does not enforce any of these keys as required from your `data`."
},
"created_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was created."
},
"updated_at": {
"type": "integer",
"format": "unix timestamp",
"example": 1552341937,
"readOnly": true,
"description": "The date time when the referenced ID was last updated."
}
}
}
}
}
CustomersFindByEmailResponse
{
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"cio_id",
"id",
"email"
],
"properties": {
"id": {
"type": "string",
"example": 2,
"nullable": true,
"description": "A person's unique ID, if set."
},
"email": {
"type": "string",
"format": "email",
"example": "hugh.mann@example.com",
"nullable": true,
"description": "A person's email address, if set."
},
"cio_id": {
"type": "string",
"example": "a3000001",
"description": "A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers."
}
}
},
"description": "A list of customers matching the email address in your query."
}
}
}
CustomersGetActivitiesResponse
{
"type": "object",
"properties": {
"activities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "01AK4N8V8G8KVA4HN8Y50CCZ59",
"description": "The identifier for the action."
},
"data": {
"oneOf": [
{
"type": "object",
"title": "Message delivery",
"example": {
"opened": null,
"delivered": null,
"delivery_id": "ZAIAAVTJVG0QcCok0-0ZKj6yiQ=="
},
"properties": {
"opened": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether or not a customer opened a message, if the message was delivered."
},
"delivered": {
"type": "integer",
"format": "unix timestamp",
"nullable": true,
"description": "The date-time when the message was delivered, if applicable."
},
"delivery_id": {
"type": "string",
"description": "The message ID."
}
}
},
{
"type": "object",
"title": "Attribute change",
"example": {
"email": {
"to": "newPerson@customer.io",
"from": "newPerson@example.com"
}
},
"description": "The name of the object is the attribute that changed.",
"additionalProperties": {
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "The new attribute value."
},
"from": {
"type": "string",
"description": "The old attribute value. If empty, the customer probably didn't bear the attribute before this action."
}
},
"x-additionalPropertyName": "Attribute Name"
}
}
]
},
"type": {
"enum": [
"attempted_action",
"attribute_change",
"failed_attribute_change",
"failed_batch_update",
"skipped_update",
"failed_query_collection",
"event",
"failed_event",
"page",
"drafted_email",
"attempted_email",
"sent_email",
"delivered_email",
"opened_email",
"clicked_email",
"converted_email",
"bounced_email",
"failed_email",
"unsubscribed_email",
"topic_unsubscribed_email",
"spammed_email",
"dropped_email",
"undeliverable_email",
"drafted_action",
"delivered_action",
"bounced_action",
"sent_action",
"opened_action",
"clicked_action",
"failed_action",
"converted_action",
"device_change",
"deferred_email",
"unsubscribed_action",
"dropped_action",
"undeliverable_action",
"deferred_action",
"profile_create",
"profile_delete",
"profile_merge",
"anon_merge",
"screen",
"webhook_event",
"add_relationship",
"delete_relationship",
"_o:<object_type_id>:create",
"_o:<object_type_id>:attribute_change",
"_o:<object_type_id>:failed_attribute_change",
"_o:<object_type_id>:delete",
"_o:<object_type_id>:add_relationship",
"_o:<object_type_id>:delete_relationship",
"_r:<object_type_id>:attribute_change",
"_r:<object_type_id>:failed_attribute_change",
"failed_object_journeys"
],
"type": "string",
"example": "sent_email",
"description": "The type of activity. Types with `_o:<object_type_id>` are for objects and types with `_r:<object_type_id>` are for relationships."
},
"timestamp": {
"type": "integer",
"format": "unix timestamp",
"example": 1397566226,
"description": "The date and time when the action occurred."
},
"customer_id": {
"type": "string",
"example": "42",
"nullable": true,
"description": "The ID of a customer profile, analogous to a \"person\" in the UI. If your workspace supports multiple identifiers (email and ID), this value can be null."
},
"delivery_id": {
"type": "string",
"example": "ZAIAAVTJVG0QcCok0-0ZKj6yiQ==",
"description": "The message ID."
},
"delivery_type": {
"enum": [
"ios",
"android",
"email",
"phone"
],
"type": "string",
"example": "email",
"description": "The recipient device, if applicable."
},
"customer_identifiers": {
"type": "object",
"required": [
"email",
"id",
"cio_id"
],
"properties": {
"id": {
"type": "string",
"example": 2,
"nullable": true,
"description": "A person's unique ID, if set. This is the same as the `customer_id` if present."
},
"email": {
"type": "string",
"format": "email",
"example": "test@example.com",
"nullable": true,
"description": "A person's email address, if set."
},
"cio_id": {
"type": "string",
"example": "a3000001",
"description": "A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers."
}
},
"description": "Contains identifiers for the person represented in a response—`id`, `cio_id`, and `email` (if your workspace uses the *Email or ID* setting). If the person's `id` or `email` is not set, the value will be null.\n\nWe recommend that you use this object rather than the less descriptive `customer_id`.\n"
}
}
}
}
}
}
CustomersGetAttributesResponse
{
"type": "object",
"example": {
"customer": {
"id": "1X",
"devices": [
{
"id": "my_android_device_idX",
"platform": "android",
"last_used": 1514764800
},
{
"id": "my_ios_device_idX",
"platform": "ios",
"last_used": 1514764800
}
],
"attributes": {
"id": "1X",
"email": "test@example.com",
"title": "tester",
"cio_id": "03000001",
"created_at": "1489014595",
"department": "qa",
"_last_emailed": "1528932553",
"cio_subscription_preferences": "{\"topics\":{\"topic_7\":false,\"topic_8\":false}}",
"_cio_subscription_preferences_computed": "{\"topics\":{\"topic_6\":false,\"topic_7\":false,\"topic_8\":false}}"
},
"timestamps": {
"id": 1489014595,
"email": 1508932553,
"title": 1508932553,
"cio_id": 1489014595,
"created_at": 1489014595,
"department": 1508932553,
"_last_emailed": 1528932553,
"cio_subscription_preferences": 1673987303,
"_cio_subscription_preferences_computed": 0
},
"unsubscribed": false
}
},
"properties": {
"customer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The customer ID referenced in the request."
},
"devices": {
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The device token."
}
}
},
{
"type": "object",
"required": [
"platform"
],
"properties": {
"platform": {
"enum": [
"ios",
"android"
],
"type": "string",
"description": "The device/messaging platform."
},
"last_used": {
"type": "integer",
"format": "unix timestamp",
"description": "The `timestamp` when you last identified this device. If you don't pass a timestamp when you add or update a device, we use the time of the request itself. Our SDKs identify a device when a person launches their app."
},
"attributes": {
"type": "object",
"properties": {
"device_os": {
"type": "string",
"description": "The operating system, including the version, on the device."
},
"app_version": {
"type": "string",
"description": "The version of your app that a customer uses. You might target app versions to let people know when they need to update, or expose them to new features when they do."
},
"_last_status": {
"enum": [
"",
"bounced",
"sent",
"suppressed"
],
"type": "string",
"readOnly": true,
"description": "The delivery status of the last message sent to the device—sent, bounced, or suppressed. An empty string indicates that that the device hasn't received a push yet."
},
"device_model": {
"type": "string",
"description": "The model of the device a person uses."
},
"push_enabled": {
"enum": [
"true",
"false"
],
"type": "string",
"description": "If `\"true\"`, the device is opted-in and can receive push notifications."
},
"device_locale": {
"type": "string",
"description": "The four-letter [IETF language code](https://customer.io/docs/api/app/) for the device. For example, `en-MX` (indicating an app in Spanish formatted for a user in Mexico) or `es-ES` (indicating an app in Spanish formatted for a user in Spain)."
},
"cio_sdk_version": {
"type": "string",
"description": "The version of the Customer.io SDK in the app."
}
},
"description": "Attributes that you can reference to segment your audience—like a person's attributes, but specific to a device. These can be either the attributes defined below or custom key-value attributes.",
"additionalProperties": {
"type": "string",
"description": "Custom properties that you want to associate with the device.",
"x-additionalPropertiesName": "Custom Device Attributes"
}
}
},
"description": "Device information common to the v1 and v2 APIs."
}
],
"description": "The properties representing an individual device. [Our SDK's](https://customer.io/docs/api/app/) gather all the properties defined below automatically, unless you disable the `autoTrackDeviceAttributes` setting. You can reference the properties outside the `attributes` object in segments or in Liquid."
},
"description": "Lists the devices associated with the customer profile."
},
"attributes": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "42",
"nullable": true,
"description": "The ID of a customer profile, analogous to a \"person\" in the UI. If your workspace supports multiple identifiers (email and ID), this value can be null."
},
"email": {
"type": "string",
"example": "test@example.com",
"nullable": true,
"description": "The email address of the customer."
},
"cio_id": {
"type": "string",
"example": "a3000001",
"description": "A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers."
},
"cio_subscription_preferences": {
"type": "string",
"description": "A person's stringified subscription preferences. These are preferences that a person set through the subscription center or attributes that you set on a person. A person who hasn't set their subscription preferences has computed preferences based on the nature of your topics (opt-in or opt-out). See the `_cio_subscription_preferences_computed` attribute for computed preferences.\n"
},
"_cio_subscription_preferences_computed": {
"type": "string",
"description": "Returns the computed subscription preferences for a person—any subscription preferences set on a person and the defaults for any subscription preferences _not_ set on a person—as stringified JSON. For example, if you have an \"opt-in\" topic that a person hasn't set a preference for, that topic would show `false`—even though a person doesn't have that attribute on their profile. [Learn more about topics](https://customer.io/docs/api/app/). \n"
}
},
"description": "Contains attributes assigned to this profile, including your workspace's people-identifiers (by default, these are `id`, `email`, and `cio_id`). Attributes are all stored as strings.",
"additionalProperties": {
"type": "string",
"description": "Non-identifier attributes assigned to this person.",
"x-additionalPropertiesName": "additional attributes"
}
},
"timestamps": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when the person's ID was generated."
},
"email": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when the person's email address was added."
},
"cio_id": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when `cio_id` was assigned."
},
"unsubscribed": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when the person unsubscribed."
},
"_last_emailed": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when you last emailed a person."
},
"additionalProperties": {
"format": "unix timestamp",
"description": "Timestamps when attributes assigned to the person were set.",
"x-additionalPropertiesName": "additional attribute timestamps"
},
"cio_subscription_preferences": {
"type": "integer",
"format": "unix timestamp",
"description": "The datetime when a person's subscription preferences were last updated."
},
"_cio_subscription_preferences_computed": {
"type": "integer",
"description": "Because this value is computed and not actually set on a person, this value is always 0"
}
},
"description": "The epoch timestamps when corresponding attributes were set on the customer profile."
},
"identifiers": {
"type": "object",
"required": [
"email",
"id",
"cio_id"
],
"properties": {
"id": {
"type": "string",
"example": 2,
"nullable": true,
"description": "A person's unique ID, if set. This is the same as the `customer_id` if present."
},
"email": {
"type": "string",
"format": "email",
"example": "test@example.com",
"nullable": true,
"description": "A person's email address, if set."
},
"cio_id": {
"type": "string",
"example": "a3000001",
"description": "A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers."
}
},
"description": "Contains identifiers for the person represented in a response—`id`, `cio_id`, and `email` (if your workspace uses the *Email or ID* setting). If the person's `id` or `email` is not set, the value will be null.\n\nWe recommend that you use this object rather than the less descriptive `customer_id`.\n"
},
"unsubscribed": {
"type": "boolean",
"description": "If true, the person is unsubscribed from messages."
}
},
"description": "The profile you referenced by ID in the request."
}
}
}
CustomersGetMessagesResponse
{
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The message identifier."
},
"type": {
"enum": [
"email",
"webhook",
"twilio",
"slack",
"push"
],
"type": "string",
"description": "The type of message."
},
"created": {
"type": "integer",
"format": "unix timestamp",
"description": "The date and time when the message was created."
},
"metrics": {
"type": "object",
"properties": {
"sent": {
"type": "integer",
"format": "unix timestamp",
"description": "The date and time when the message was sent."
},
"delivered": {
"type": "integer",
"format": "unix timestamp",
"description": "The date and time when the customer received the message."
}
},
"description": "Contains information about the send and delivery time of the message."
},
"subject": {
"type": "string",
"description": "The subject line of the message."
},
"action_id": {
"type": "integer",
"description": "The identifier for the message action within the campaign or broadcast the message belonged to."
},
"forgotten": {
"type": "boolean",
"description": "If true, the message content was forgotten."
},
"recipient": {
"type": "string",
"description": "The address of the recipient. May be an email address, MSISDN, or a device UUID."
},
"content_id": {
"type": "integer",
"nullable": true,
"description": "The newsletter variant for the message, if applicable."
},
"campaign_id": {
"type": "integer",
"description": "The campaign the message belongs to."
},
"customer_id": {
"type": "string",
"description": "The customer the message was sent to."
},
"broadcast_id": {
"type": "integer",
"nullable": true,
"description": "The broadcast the message was sent as a part of, if applicable."
},
"newsletter_id": {
"type": "integer",
"nullable": true,
"description": "The newsletter that the message was sent as a part of, if applicable."
},
"deduplicate_id": {
"type": "string",
"description": "A group identifier to deduplicate messages (useful if a customer may have received multiple messages of the same type)."
},
"failure_message": {
"type": "string",
"nullable": true,
"description": "An error, if the message did not make it to the customer."
},
"msg_template_id": {
"type": "string",
"deprecated": true,
"description": "The message template the message was created from."
}
}
}
}
}
}
CustomersGetSubscriptionPreferences400Response
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string",
"description": "Error descriptions."
},
"description": "An array of errors."
}
}
}
}
}
CustomersGetSubscriptionPreferencesResponse
{
"type": "object",
"properties": {
"customer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "42",
"nullable": true,
"description": "The ID of a customer profile, analogous to a \"person\" in the UI. If your workspace supports multiple identifiers (email and ID), this value can be null."
},
"header": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The header of the subscription preferences page."
},
"subtitle": {
"type": "string",
"description": "The subtitle or headline beneath the header of the subscription preferences page."
}
}
},
"topics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "System-generated ID of the topic."
},
"name": {
"type": "string",
"description": "The name of the subscription topic."
},
"subscribed": {
"type": "boolean",
"description": "If true, the customer is subscribed to the topic. If false, the customer is unsubscribed from the topic."
},
"description": {
"type": "string",
"description": "The (optional) description of the topic."
}
}
},
"description": "A list of all subscription preferences for the customer."
},
"identifiers": {
"type": "object",
"required": [
"email",
"id",
"cio_id"
],
"properties": {
"id": {
"type": "string",
"example": 2,
"nullable": true,
"description": "A person's unique ID, if set. This is the same as the `customer_id` if present."
},
"email": {
"type": "string",
"format": "email",
"example": "test@example.com",
"nullable": true,
"description": "A person's email address, if set."
},
"cio_id": {
"type": "string",
"example": "a3000001",
"description": "A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers."
}
},
"description": "Contains identifiers for the person represented in a response—`id`, `cio_id`, and `email` (if your workspace uses the *Email or ID* setting). If the person's `id` or `email` is not set, the value will be null.\n\nWe recommend that you use this object rather than the less descriptive `customer_id`.\n"
},
"unsubscribed": {
"type": "boolean",
"description": "If true, the customer is unsubscribed from all messaging. If false, the customer is subscribed according to their topic preferences."
}
},
"description": "The profile you referenced by ID in the request."
}
}
}
CustomersListAttributesDevicesRequest
{
"type": "object",
"required": [
"ids"
],
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"description": "An array of up to 100 customer IDs."
}
}
}
CustomersListAttributesDevicesResponse
{
"type": "object",
"properties": {
"customers": {
"type": "array",
"items": {
"type": "object",
"example": {
"customer": {
"id": "1X",
"devices": [
{
"id": "my_android_device_idX",
"platform": "android",
"last_used": 1514764800
},
{
"id": "my_ios_device_idX",
"platform": "ios",
"last_used": 1514764800
}
],
"attributes": {
"id": "1X",
"email": "test@example.com",
"title": "tester",
"cio_id": "03000001",
"created_at": "1489014595",
"department": "qa",
"_last_emailed": "1528932553",
"cio_subscription_preferences": "{\"topics\":{\"topic_7\":false,\"topic_8\":false}}",
"_cio_subscription_preferences_computed": "{\"topics\":{\"topic_6\":false,\"topic_7\":false,\"topic_8\":false}}"
},
"timestamps": {
"id": 1489014595,
"email": 1508932553,
"title": 1508932553,
"cio_id": 1489014595,
"created_at": 1489014595,
"department": 1508932553,
"_last_emailed": 1528932553,
"cio_subscription_preferences": 1673987303,
"_cio_subscription_preferences_computed": 0
},
"unsubscribed": false
}
},
"properties": {
"customer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The customer ID referenced in the request."
},
"devices": {
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The device token."
}
}
},
{
"type": "object",
"required": [
"platform"
],
"properties": {
"platform": {
"enum": [
"ios",
"android"
],
"type": "string",
"description": "The device/messaging platform."
},
"last_used": {
"type": "integer",
"format": "unix timestamp",
"description": "The `timestamp` when you last identified this device. If you don't pass a timestamp when you add or update a device, we use the time of the request itself. Our SDKs identify a device when a person launches their app."
},
"attributes": {
"type": "object",
"properties": {
"device_os": {
"type": "string",
"description": "The operating system, including the version, on the device."
},
"app_version": {
"type": "string",
"description": "The version of your app that a customer uses. You might target app versions to let people know when they need to update, or expose them to new features when they do."
},
"_last_status": {
"enum": [
"",
"bounced",
"sent",
"suppressed"
],
"type": "string",
"readOnly": true,
"description": "The delivery status of the last message sent to the device—sent, bounced, or suppressed. An empty string indicates that that the device hasn't received a push yet."
},
"device_model": {
"type": "string",
"description": "The model of the device a person uses."
},
"push_enabled": {
"enum": [
"true",
"false"
],
"type": "string",
"description": "If `\"true\"`, the device is opted-in and can receive push notifications."
},
"device_locale": {
"type": "string",
"description": "The four-letter [IETF language code](https://customer.io/docs/api/app/) for the device. For example, `en-MX` (indicating an app in Spanish formatted for a user in Mexico) or `es-ES` (indicating an app in Spanish formatted for a user in Spain)."
},
"cio_sdk_version": {
"type": "string",
"description": "The version of the Customer.io SDK in the app."
}
},
"description": "Attributes that you can reference to segment your audience—like a person's attributes, but specific to a device. These can be either the attributes defined below or custom key-value attributes.",
"additionalProperties": {
"type": "string",
"description": "Custom properties that you want to associate with the device.",
"x-additionalPropertiesName": "Custom Device Attributes"
}
}
},
"description": "Device information common to the v1 and v2 APIs."
}
],
"description": "The properties representing an individual device. [Our SDK's](https://customer.io/docs/api/app/) gather all the properties defined below automatically, unless you disable the `autoTrackDeviceAttributes` setting. You can reference the properties outside the `attributes` object in segments or in Liquid."
},
"description": "Lists the devices associated with the customer profile."
},
"attributes": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "42",
"nullable": true,
"description": "The ID of a customer profile, analogous to a \"person\" in the UI. If your workspace supports multiple identifiers (email and ID), this value can be null."
},
"email": {
"type": "string",
"example": "test@example.com",
"nullable": true,
"description": "The email address of the customer."
},
"cio_id": {
"type": "string",
"example": "a3000001",
"description": "A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers."
},
"cio_subscription_preferences": {
"type": "string",
"description": "A person's stringified subscription preferences. These are preferences that a person set through the subscription center or attributes that you set on a person. A person who hasn't set their subscription preferences has computed preferences based on the nature of your topics (opt-in or opt-out). See the `_cio_subscription_preferences_computed` attribute for computed preferences.\n"
},
"_cio_subscription_preferences_computed": {
"type": "string",
"description": "Returns the computed subscription preferences for a person—any subscription preferences set on a person and the defaults for any subscription preferences _not_ set on a person—as stringified JSON. For example, if you have an \"opt-in\" topic that a person hasn't set a preference for, that topic would show `false`—even though a person doesn't have that attribute on their profile. [Learn more about topics](https://customer.io/docs/api/app/). \n"
}
},
"description": "Contains attributes assigned to this profile, including your workspace's people-identifiers (by default, these are `id`, `email`, and `cio_id`). Attributes are all stored as strings.",
"additionalProperties": {
"type": "string",
"description": "Non-identifier attributes assigned to this person.",
"x-additionalPropertiesName": "additional attributes"
}
},
"timestamps": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when the person's ID was generated."
},
"email": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when the person's email address was added."
},
"cio_id": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when `cio_id` was assigned."
},
"unsubscribed": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when the person unsubscribed."
},
"_last_emailed": {
"type": "integer",
"format": "unix timestamp",
"description": "The date-time when you last emailed a person."
},
"additionalProperties": {
"format": "unix timestamp",
"description": "Timestamps when attributes assigned to the person were set.",
"x-additionalPropertiesName": "additional attribute timestamps"
},
"cio_subscription_preferences": {
"type": "integer",
"format": "unix timestamp",
"description": "The datetime when a person's subscription preferences were last updated."
},
"_cio_subscription_preferences_computed": {
"type": "integer",
"description": "Because this value is computed and not actually set on a person, this value is always 0"
}
},
"description": "The epoch timestamps when corresponding attributes were set on the customer profile."
},
"identifiers": {
"type": "object",
"required": [
"email",
"id",
"cio_id"
],
"properties": {
"id": {
"type": "string",
"example": 2,
"nullable": true,
"description": "A person's unique ID, if set. This is the same as the `customer_id` if present."
},
"email": {
"type": "string",
"format": "email",
"example": "test@example.com",
"nullable": true,
"description": "A person's email address, if set."
},
"cio_id": {
"type": "string",
"example": "a3000001",
"description": "A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers."
}
},
"description": "Contains identifiers for the person represented in a response—`id`, `cio_id`, and `email` (if your workspace uses the *Email or ID* setting). If the person's `id` or `email` is not set, the value will be null.\n\nWe recommend that you use this object rather than the less descriptive `customer_id`.\n"
},
"unsubscribed": {
"type": "boolean",
"description": "If true, the person is unsubscribed from messages."
}
},
"description": "The profile you referenced by ID in the request."
}
}
}
}
}
}
| Version | Endpoints | Schemas | Ingested | Status |
|---|---|---|---|---|
| 1.0.0 | 111 | 440 | 2026-05-11 | current |
| 1.0.0 | 111 | 440 | 2026-04-16 |