Customer.io App API

{
  "components": {
    "securitySchemes": {
      "Bearer-Auth": {
        "type": "http",
        "scheme": "bearer",
        "description": "The App API uses a bearer authentication scheme.\n\nYou can generate a bearer token, known as an **App API Key**, with a defined scope in [your account settings](https://fly.customer.io/settings/api_credentials?keyType=app). [Learn more about bearer authorization in Customer.io](/accounts/settings/managing-credentials).\n"
      },
      "ServiceAccount-Auth": {
        "x-scalar-ignore": true,
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sa_live_",
        "description": "Transactional send endpoints (`/v1/send/email`, `/v1/send/push`, `/v1/send/sms`, `/v1/send/in_app`, `/v1/send/inbox_message`) also accept a service-account bearer token, prefixed with `sa_live_`. Service-account tokens work across workspaces, so you must pass the target workspace as the `X-Workspace-Id` header on each request.\n\nService-account tokens are intended for testing and one-off sends—for example, using the Customer.io CLI with an AI agent like Claude to verify that a transactional message renders correctly before wiring it into your production backend. **For the production integration that triggers the message from your application, use an App API Key instead**: it's workspace-scoped, easier to rotate, and has a smaller blast radius.\n\nService-account tokens are server-side credentials. Treat them like any API key—keep them in environment variables or a secret manager, and never embed them in client-side code, mobile apps, or other untrusted contexts.\n"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key passed as a Bearer token"
      }
    },
    "schemas": {
      "createEmailNewsletter": {
        "title": "Email",
        "description": "When you create an email, include `subject` and `body`. Set either `from` or `from_id`, but not both. If you set neither, Customer.io uses your oldest verified sending address.",
        "allOf": [
          {
            "type": "object",
            "required": [
              "name",
              "type",
              "recipients"
            ],
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 190,
                "description": "The name of the newsletter."
              },
              "recipients": {
                "type": "object",
                "description": "Filter conditions that define the newsletter's recipients. Combine `segment` and `attribute` conditions with `and`, `or`, and `not` operators.\n",
                "properties": {
                  "and": {
                    "type": "array",
                    "description": "An array of conditions that must all be true.",
                    "items": {
                      "type": "object"
                    }
                  },
                  "or": {
                    "type": "array",
                    "description": "An array of conditions where at least one must be true.",
                    "items": {
                      "type": "object"
                    }
                  },
                  "not": {
                    "type": "object",
                    "description": "A condition or group of conditions to exclude."
                  },
                  "segment": {
                    "type": "object",
                    "description": "A segment condition.",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "The ID of a segment."
                      }
                    }
                  },
                  "attribute": {
                    "type": "object",
                    "description": "A customer attribute condition.",
                    "properties": {
                      "field": {
                        "type": "string",
                        "description": "The attribute name."
                      },
                      "operator": {
                        "type": "string",
                        "description": "The comparison operator.",
                        "enum": [
                          "eq",
                          "exists"
                        ]
                      },
                      "value": {
                        "type": "string",
                        "description": "The value to compare against. Required when `operator` is `eq`."
                      },
                      "inverse": {
                        "type": "boolean",
                        "description": "Set to `true` for \"is not equal\" or \"does not exist\"."
                      }
                    }
                  }
                }
              },
              "send_now": {
                "type": "boolean",
                "description": "If `true`, the newsletter is sent immediately after creation. You cannot set both `send_now` and `scheduled_at`."
              },
              "scheduled_at": {
                "type": "integer",
                "format": "unix timestamp",
                "description": "A Unix timestamp indicating when to send the newsletter. The time must be in the future. You cannot set both `send_now` and `scheduled_at`."
              },
              "subscription_topic_id": {
                "type": "integer",
                "description": "The newsletter audience's subscription topic ID. Required when [subscription center](/journeys/channels/subscriptions/center/#enable-sub-center) is enabled; otherwise sends to globally subscribed profiles."
              }
            }
          },
          {
            "type": "object",
            "example": {
              "rate_limit_email_rate": 500,
              "rate_limit_time_period": 60,
              "rate_limit_spread": true
            },
            "description": "Optional newsletter rate limiting. If you set `rate_limit_email_rate` or `rate_limit_time_period`, set both; `rate_limit_spread` can be set alone.",
            "properties": {
              "rate_limit_email_rate": {
                "type": "integer",
                "minimum": 1,
                "description": "Maximum number of messages per time period. **NOTE:** Though this states `email_rate`, you can use this for other message channels. Only fixed rate limits are supported, not [daily ramp limits](/journeys/send/broadcasts/newsletters/#daily-ramp).\n"
              },
              "rate_limit_time_period": {
                "type": "integer",
                "enum": [
                  60,
                  3600,
                  86400
                ],
                "description": "Time period in seconds for rate limiting. Must be one of 60 (minute), 3600 (hour), or 86400 (day)."
              },
              "rate_limit_spread": {
                "type": "boolean",
                "description": "When `true`, spreads messages evenly across the time period. Otherwise, it sends as fast as possible up to the limit in each period."
              }
            }
          },
          {
            "type": "object",
            "required": [
              "subject",
              "body"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "The channel type for the newsletter.",
                "enum": [
                  "email"
                ]
              },
              "subject": {
                "type": "string",
                "description": "The subject line of the email."
              },
              "preheader_text": {
                "x-scalar-ignore": true,
                "type": "string",
                "description": "[Also known as \"preview text\"](/journeys/channels/email/headers/custom-preheader-text/), this is the small block of text shown in an email inbox next to or underneath the subject line.\n"
              },
              "body": {
                "type": "string",
                "description": "The HTML body content of the email. Use standard HTML/CSS, not syntax unique to Design Studio."
              },
              "body_plain": {
                "type": "string",
                "description": "The plaintext body of the email. If provided, this overwrites the auto-generated plaintext."
              },
              "layout_id": {
                "type": "integer",
                "description": "The ID of the [layout](/journeys/channels/email/layouts/3-layouts-and-customerio/) you want to use for the email. If you don't set one, the email uses your workspace's default layout. Find a layout's ID in its URL."
              },
              "from": {
                "type": "string",
                "description": "The address to send the email from, in the format `Name <email@domain.com>`. You can set `from` or `from_id`, but not both. Use one of the `address` values from [List sender identities](#tag/sender-identities/listSenders)."
              },
              "from_id": {
                "x-scalar-ignore": true,
                "type": "integer",
                "description": "The identifier of the `from` address, commonly known as the \"sender\". Use [List sender identities](#tag/sender-identities/listSenders) to find valid IDs.",
                "example": 1
              }
            },
            "example": {
              "name": "Weekly Product Update",
              "type": "email",
              "recipients": {
                "and": [
                  {
                    "or": [
                      {
                        "segment": {
                          "id": 42
                        }
                      },
                      {
                        "segment": {
                          "id": 99
                        }
                      }
                    ]
                  },
                  {
                    "attribute": {
                      "field": "plan",
                      "operator": "eq",
                      "value": "trial",
                      "inverse": true
                    }
                  }
                ]
              },
              "subject": "What's new this week, {{ customer.first_name }}",
              "preheader_text": "Check out our latest features and improvements",
              "body": "<html><body><h1>Product Updates</h1><p>Here's what we shipped this week...</p></body></html>",
              "from": "Product Team <updates@example.com>",
              "subscription_topic_id": 5
            }
          }
        ]
      },
      "createSmsNewsletter": {
        "title": "SMS",
        "description": "When creating an SMS text, you must include `body`.",
        "allOf": [
          {
            "type": "object",
            "required": [
              "name",
              "type",
              "recipients"
            ],
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 190,
                "description": "The name of the newsletter."
              },
              "recipients": {
                "type": "object",
                "description": "Filter conditions that define the newsletter's recipients. Combine `segment` and `attribute` conditions with `and`, `or`, and `not` operators.\n",
                "properties": {
                  "and": {
                    "type": "array",
                    "description": "An array of conditions that must all be true.",
                    "items": {
                      "type": "object"
                    }
                  },
                  "or": {
                    "type": "array",
                    "description": "An array of conditions where at least one must be true.",
                    "items": {
                      "type": "object"
                    }
                  },
                  "not": {
                    "type": "object",
                    "description": "A condition or group of conditions to exclude."
                  },
                  "segment": {
                    "type": "object",
                    "description": "A segment condition.",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "The ID of a segment."
                      }
                    }
                  },
                  "attribute": {
                    "type": "object",
                    "description": "A customer attribute condition.",
                    "properties": {
                      "field": {
                        "type": "string",
                        "description": "The attribute name."
                      },
                      "operator": {
                        "type": "string",
                        "description": "The comparison operator.",
                        "enum": [
                          "eq",
                          "exists"
                        ]
                      },
                      "value": {
                        "type": "string",
                        "description": "The value to compare against. Required when `operator` is `eq`."
                      },
                      "inverse": {
                        "type": "boolean",
                        "description": "Set to `true` for \"is not equal\" or \"does not exist\"."
                      }
                    }
                  }
                }
              },
              "send_now": {
                "type": "boolean",
                "description": "If `true`, the newsletter is sent immediately after creation. You cannot set both `send_now` and `scheduled_at`."
              },
              "scheduled_at": {
                "type": "integer",
                "format": "unix timestamp",
                "description": "A Unix timestamp indicating when to send the newsletter. The time must be in the future. You cannot set both `send_now` and `scheduled_at`."
              },
              "subscription_topic_id": {
                "type": "integer",
                "description": "The newsletter audience's subscription topic ID. Required when [subscription center](/journeys/channels/subscriptions/center/#enable-sub-center) is enabled; otherwise sends to globally subscribed profiles."
              }
            }
          },
          {
            "type": "object",
            "example": {
              "rate_limit_email_rate": 500,
              "rate_limit_time_period": 60,
              "rate_limit_spread": true
            },
            "description": "Optional newsletter rate limiting. If you set `rate_limit_email_rate` or `rate_limit_time_period`, set both; `rate_limit_spread` can be set alone.",
            "properties": {
              "rate_limit_email_rate": {
                "type": "integer",
                "minimum": 1,
                "description": "Maximum number of messages per time period. **NOTE:** Though this states `email_rate`, you can use this for other message channels. Only fixed rate limits are supported, not [daily ramp limits](/journeys/send/broadcasts/newsletters/#daily-ramp).\n"
              },
              "rate_limit_time_period": {
                "type": "integer",
                "enum": [
                  60,
                  3600,
                  86400
                ],
                "description": "Time period in seconds for rate limiting. Must be one of 60 (minute), 3600 (hour), or 86400 (day)."
              },
              "rate_limit_spread": {
                "type": "boolean",
                "description": "When `true`, spreads messages evenly across the time period. Otherwise, it sends as fast as possible up to the limit in each period."
              }
            }
          },
          {
            "type": "object",
            "required": [
              "body"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "The channel type for the newsletter.",
                "enum": [
                  "twilio"
                ]
              },
              "body": {
                "type": "string",
                "description": "The body content of the SMS message.",
                "example": "Hi {{ customer.first_name }}, your order has shipped!"
              }
            }
          }
        ]
      },
      "createPushNewsletter": {
        "title": "Push",
        "description": "For push notifications, you must provide at least one of `subject` or `body`.",
        "allOf": [
          {
            "type": "object",
            "required": [
              "name",
              "type",
              "recipients"
            ],
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 190,
                "description": "The name of the newsletter."
              },
              "recipients": {
                "type": "object",
                "description": "Filter conditions that define the newsletter's recipients. Combine `segment` and `attribute` conditions with `and`, `or`, and `not` operators.\n",
                "properties": {
                  "and": {
                    "type": "array",
                    "description": "An array of conditions that must all be true.",
                    "items": {
                      "type": "object"
                    }
                  },
                  "or": {
                    "type": "array",
                    "description": "An array of conditions where at least one must be true.",
                    "items": {
                      "type": "object"
                    }
                  },
                  "not": {
                    "type": "object",
                    "description": "A condition or group of conditions to exclude."
                  },
                  "segment": {
                    "type": "object",
                    "description": "A segment condition.",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "The ID of a segment."
                      }
                    }
                  },
                  "attribute": {
                    "type": "object",
                    "description": "A customer attribute condition.",
                    "properties": {
                      "field": {
                        "type": "string",
                        "description": "The attribute name."
                      },
                      "operator": {
                        "type": "string",
                        "description": "The comparison operator.",
                        "enum": [
                          "eq",
                          "exists"
                        ]
                      },
                      "value": {
                        "type": "string",
                        "description": "The value to compare against. Required when `operator` is `eq`."
                      },
                      "inverse": {
                        "type": "boolean",
                        "description": "Set to `true` for \"is not equal\" or \"does not exist\"."
                      }
                    }
                  }
                }
              },
              "send_now": {
                "type": "boolean",
                "description": "If `true`, the newsletter is sent immediately after creation. You cannot set both `send_now` and `scheduled_at`."
              },
              "scheduled_at": {
                "type": "integer",
                "format": "unix timestamp",
                "description": "A Unix timestamp indicating when to send the newsletter. The time must be in the future. You cannot set both `send_now` and `scheduled_at`."
              },
              "subscription_topic_id": {
                "type": "integer",
                "description": "The newsletter audience's subscription topic ID. Required when [subscription center](/journeys/channels/subscriptions/center/#enable-sub-center) is enabled; otherwise sends to globally subscribed profiles."
              }
            }
          },
          {
            "type": "object",
            "example": {
              "rate_limit_email_rate": 500,
              "rate_limit_time_period": 60,
              "rate_limit_spread": true
            },
            "description": "Optional newsletter rate limiting. If you set `rate_limit_email_rate` or `rate_limit_time_period`, set both; `rate_limit_spread` can be set alone.",
            "properties": {
              "rate_limit_email_rate": {
                "type": "integer",
                "minimum": 1,
                "description": "Maximum number of messages per time period. **NOTE:** Though this states `email_rate`, you can use this for other message channels. Only fixed rate limits are supported, not [daily ramp limits](/journeys/send/broadcasts/newsletters/#daily-ramp).\n"
              },
              "rate_limit_time_period": {
                "type": "integer",
                "enum": [
                  60,
                  3600,
                  86400
                ],
                "description": "Time period in seconds for rate limiting. Must be one of 60 (minute), 3600 (hour), or 86400 (day)."
              },
              "rate_limit_spread": {
                "type": "boolean",
                "description": "When `true`, spreads messages evenly across the time period. Otherwise, it sends as fast as possible up to the limit in each period."
              }
            }
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "description": "The channel type for the newsletter.",
                "enum": [
                  "push"
                ]
              },
              "subject": {
                "type": "string",
                "description": "The title of the push notification. You must provide `subject`, `body`, or both.",
                "example": "24-hour flash sale!"
              },
              "body": {
                "type": "string",
                "description": "The body content of the push notification. You must provide `subject`, `body`, or both.",
                "example": "Get 30% off everything. Tap to shop now."
              }
            }
          }
        ]
      },
      "createInAppNewsletter": {
        "title": "In-App",
        "description": "For in-app messages, you must include `body_json`.",
        "allOf": [
          {
            "type": "object",
            "required": [
              "name",
              "type",
              "recipients"
            ],
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 190,
                "description": "The name of the newsletter."
              },
              "recipients": {
                "type": "object",
                "description": "Filter conditions that define the newsletter's recipients. Combine `segment` and `attribute` conditions with `and`, `or`, and `not` operators.\n",
                "properties": {
                  "and": {
                    "type": "array",
                    "description": "An array of conditions that must all be true.",
                    "items": {
                      "type": "object"
                    }
                  },
                  "or": {
                    "type": "array",
                    "description": "An array of conditions where at least one must be true.",
                    "items": {
                      "type": "object"
                    }
                  },
                  "not": {
                    "type": "object",
                    "description": "A condition or group of conditions to exclude."
                  },
                  "segment": {
                    "type": "object",
                    "description": "A segment condition.",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "The ID of a segment."
                      }
                    }
                  },
                  "attribute": {
                    "type": "object",
                    "description": "A customer attribute condition.",
                    "properties": {
                      "field": {
                        "type": "string",
                        "description": "The attribute name."
                      },
                      "operator": {
                        "type": "string",
                        "description": "The comparison operator.",
                        "enum": [
                          "eq",
                          "exists"
                        ]
                      },
                      "value": {
                        "type": "string",
                        "description": "The value to compare against. Required when `operator` is `eq`."
                      },
                      "inverse": {
                        "type": "boolean",
                        "description": "Set to `true` for \"is not equal\" or \"does not exist\"."
                      }
                    }
                  }
                }
              },
              "send_now": {
                "type": "boolean",
                "description": "If `true`, the newsletter is sent immediately after creation. You cannot set both `send_now` and `scheduled_at`."
              },
              "scheduled_at": {
                "type": "integer",
                "format": "unix timestamp",
                "description": "A Unix timestamp indicating when to send the newsletter. The time must be in the future. You cannot set both `send_now` and `scheduled_at`."
              },
              "subscription_topic_id": {
                "type": "integer",
                "description": "The newsletter audience's subscription topic ID. Required when [subscription center](/journeys/channels/subscriptions/center/#enable-sub-center) is enabled; otherwise sends to globally subscribed profiles."
              }
            }
          },
          {
            "type": "object",
            "example": {
              "rate_limit_email_rate": 500,
              "rate_limit_time_period": 60,
              "rate_limit_spread": true
            },
            "description": "Optional newsletter rate limiting. If you set `rate_limit_email_rate` or `rate_limit_time_period`, set both; `rate_limit_spread` can be set alone.",
            "properties": {
              "rate_limit_email_rate": {
                "type": "integer",
                "minimum": 1,
                "description": "Maximum number of messages per time period. **NOTE:** Though this states `email_rate`, you can use this for other message channels. Only fixed rate limits are supported, not [daily ramp limits](/journeys/send/broadcasts/newsletters/#daily-ramp).\n"
              },
              "rate_limit_time_period": {
                "type": "integer",
                "enum": [
                  60,
                  3600,
                  86400
                ],
                "description": "Time period in seconds for rate limiting. Must be one of 60 (minute), 3600 (hour), or 86400 (day)."
              },
              "rate_limit_spread": {
                "type": "boolean",
                "description": "When `true`, spreads messages evenly across the time period. Otherwise, it sends as fast as possible up to the limit in each period."
              }
            }
          },
          {
            "type": "object",
            "required": [
              "body_json"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "The channel type for the newsletter.",
                "enum": [
                  "in_app"
                ]
              },
              "body_json": {
                "type": "string",
                "description": "JSON body content for the in-app message. This defines the structure and content of the in-app message.",
                "example": "{\"message_id\":\"welcome\",\"display\":{\"mode\":\"modal\",\"value\":\"center\"},\"carta_content\":\"<x-base><x-message>Hello {{customer.first_name}}!</x-message></x-base>\"}"
              }
            }
          }
        ]
      },
      "createWebhookNewsletter": {
        "title": "Webhook",
        "description": "For webhooks, you must include `body`, `request_method`, and `url`.",
        "allOf": [
          {
            "type": "object",
            "required": [
              "name",
              "type",
              "recipients"
            ],
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 190,
                "description": "The name of the newsletter."
              },
              "recipients": {
                "type": "object",
                "description": "Filter conditions that define the newsletter's recipients. Combine `segment` and `attribute` conditions with `and`, `or`, and `not` operators.\n",
                "properties": {
                  "and": {
                    "type": "array",
                    "description": "An array of conditions that must all be true.",
                    "items": {
                      "type": "object"
                    }
                  },
                  "or": {
                    "type": "array",
                    "description": "An array of conditions where at least one must be true.",
                    "items": {
                      "type": "object"
                    }
                  },
                  "not": {
                    "type": "object",
                    "description": "A condition or group of conditions to exclude."
                  },
                  "segment": {
                    "type": "object",
                    "description": "A segment condition.",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "The ID of a segment."
                      }
                    }
                  },
                  "attribute": {
                    "type": "object",
                    "description": "A customer attribute condition.",
                    "properties": {
                      "field": {
                        "type": "string",
                        "description": "The attribute name."
                      },
                      "operator": {
                        "type": "string",
                        "description": "The comparison operator.",
                        "enum": [
                          "eq",
                          "exists"
                        ]
                      },
                      "value": {
                        "type": "string",
                        "description": "The value to compare against. Required when `operator` is `eq`."
                      },
                      "inverse": {
                        "type": "boolean",
                        "description": "Set to `true` for \"is not equal\" or \"does not exist\"."
                      }
                    }
                  }
                }
              },
              "send_now": {
                "type": "boolean",
                "description": "If `true`, the newsletter is sent immediately after creation. You cannot set both `send_now` and `scheduled_at`."
              },
              "scheduled_at": {
                "type": "integer",
                "format": "unix timestamp",
                "description": "A Unix timestamp indicating when to send the newsletter. The time must be in the future. You cannot set both `send_now` and `scheduled_at`."
              },
              "subscription_topic_id": {
                "type": "integer",
                "description": "The newsletter audience's subscription topic ID. Required when [subscription center](/journeys/channels/subscriptions/center/#enable-sub-center) is enabled; otherwise sends to globally subscrib

# --- truncated at 32 KB (4545 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/customer-io/refs/heads/main/openapi/_original/customer-io-app-api-openapi.json