Customer.io Sender Identities API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io Journeys API Reference Sender Identities API
  description: Customer.io provides REST APIs to send real-time customer data, retrieve data from your account, and trigger messages.
servers:
- url: https://track.customer.io
  description: The base URL for the Track API. Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://track-eu.customer.io
  description: The base URL for the Track API (EU region). Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://api.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
tags:
- name: Sender Identities
  description: Return information about your senders—the addresses that you send messages from—including usage information for your different senders.
paths:
  /v1/sender_identities:
    servers:
    - url: https://api.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    - url: https://api-eu.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    parameters:
    - $ref: '#/components/parameters/start'
    - $ref: '#/components/parameters/limit'
    - $ref: '#/components/parameters/sort'
    - name: hidden
      in: query
      required: false
      description: If true, include hidden senders in the results.
      schema:
        type: boolean
    get:
      summary: List sender identities
      operationId: listSenders
      security:
      - Bearer-Auth: []
      description: Returns a list of senders in your workspace. Senders are who your messages are "from".
      tags:
      - Sender Identities
      responses:
        '200':
          description: Returns an array of `sender_identities`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sender_identities:
                    type: array
                    items:
                      $ref: '#/components/schemas/senderIdentityObject'
                  next:
                    $ref: '#/components/schemas/next'
        '429':
          $ref: '#/components/responses/429'
  /v1/sender_identities/{sender_id}:
    servers:
    - url: https://api.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    - url: https://api-eu.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    parameters:
    - $ref: '#/components/parameters/sender_id'
    get:
      summary: Get a sender
      operationId: getSender
      security:
      - Bearer-Auth: []
      description: Returns information about a specific sender.
      tags:
      - Sender Identities
      responses:
        '200':
          description: Returns the `sender_identity` you requested.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sender_identity:
                    $ref: '#/components/schemas/senderIdentityObject'
        '404':
          description: The sender does not exist.
        '429':
          $ref: '#/components/responses/429'
  /v1/sender_identities/{sender_id}/used_by:
    servers:
    - url: https://api.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    - url: https://api-eu.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    parameters:
    - $ref: '#/components/parameters/sender_id'
    get:
      summary: Get sender usage data
      operationId: getSenderUsage
      security:
      - Bearer-Auth: []
      description: Returns lists of the automations and one-time sends that use a sender.
      tags:
      - Sender Identities
      responses:
        '200':
          description: Returns arrays of automations and one-time sends.
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    type: array
                    description: The automations that use the sender.
                    items:
                      type: integer
                  sent_newsletters:
                    type: array
                    description: The one-time sends you've sent that used the sender.
                    items:
                      type: integer
                  draft_newsletters:
                    type: array
                    description: The one-time send drafts that are set up using the sender.
                    items:
                      type: integer
        '404':
          description: The sender does not exist.
        '429':
          $ref: '#/components/responses/429'
components:
  schemas:
    appApiError:
      x-scalar-ignore: true
      type: object
      description: An array/list of failures where each entry is a separate failure reason.
      required:
      - errors
      properties:
        errors:
          type: array
          description: One entry for each reason the request failed.
          items:
            type: object
            required:
            - detail
            - status
            properties:
              detail:
                type: string
                description: What went wrong, in plain text. Most messages end with a support reference you can use if you need to contact support.
                example: bad request (reference a1b2c3)
              status:
                type: string
                description: The HTTP status code as a string.
                example: '400'
              code:
                type: string
                description: A stable identifier for the failure, on the errors that carry one. Use this rather than the text in `detail` if you need to identify the error programmatically.
                example: invalid_credentials
              source:
                type: object
                description: The part of the request that the error refers to.
                properties:
                  pointer:
                    type: string
                    description: A JSON pointer to the part of the request body that the error refers to.
                    example: /data/attributes/email
              meta:
                type: object
                additionalProperties: true
                description: Extra context (if available).
    next:
      x-scalar-ignore: true
      type: string
      description: Indicates the next page of results. Add `?start=<next_value>` to the request to get the next page of results.
    senderIdentityObject:
      x-scalar-ignore: true
      type: object
      description: Information about a sender.
      properties:
        id:
          type: integer
          description: The identifier of a sender.
        deduplicate_id:
          $ref: '#/components/schemas/deduplicate_id'
        name:
          type: string
          description: The name of the sender.
        email:
          type: string
          description: The email address of the sender.
        address:
          type: string
          description: The sender name and email address in the format `name <name@example.com>`.
        template_type:
          type: string
          enum:
          - email
          - phone
          description: The type of sender.
        auto_generated:
          type: boolean
          description: If true, the sender is automatically generated by Customer.io.
        phone:
          type: string
          description: The phone number of the sender, used for SMS senders.
        hidden:
          type: boolean
          description: If true, the sender is hidden in the Customer.io UI.
      example:
        id: 4534
        deduplicate_id: 4534:1478035647
        name: Cher Ami
        email: test@example.com
        address: Cher Ami <test@example.com>
        template_type: email
        auto_generated: false
    deduplicate_id:
      x-scalar-ignore: true
      type: string
      readOnly: true
      description: An identifier in the format `id:timestamp` where the id is for the object you're working with (Automations, Deliveries, Exports, Identities, One-time sends, Segments, and Templates), and the timestamp is the last time the object was updated.
      example: 15:1492548073
  parameters:
    sender_id:
      name: sender_id
      in: path
      required: true
      description: The identifier of a sender.
      schema:
        type: integer
    sort:
      name: sort
      in: query
      description: Determine how you want to sort results, `asc` for chronological order and `desc` for reverse chronological order.
      required: false
      schema:
        type: string
        enum:
        - asc
        - desc
    limit:
      name: limit
      in: query
      required: false
      description: The maximum number of results you want to retrieve per page.
      schema:
        type: integer
    start:
      name: start
      in: query
      required: false
      description: The token for the page of results you want to return. Responses contain a `next` property. Use this property as the `start` value to return the next page of results.
      schema:
        type: string
  responses:
    '429':
      description: Your request is over the 10-per-second limit. `Retry-After` tells you how many seconds you must wait before you send the next request.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/appApiError'
          example:
            errors:
            - detail: rate limited to 10 requests per 1s (reference a1b2c3)
              status: '429'
  headers:
    Retry-After:
      description: How many seconds you must wait before you send another request. This header is present when you are rate limited by a per-second limit. If you hit a daily quota, this header is not set.
      schema:
        type: integer
        minimum: 1
        example: 1
  securitySchemes:
    Tracking-API-Key:
      type: http
      scheme: basic
      description: 'The Track API uses a basic authentication scheme. Your credentials are your **Site ID** and your **API key**, **Base-64 encoded** in the format `site_id:api_key`.


        You can find your Site ID and API key on the [Track API Keys page](https://fly.customer.io/settings/api_credentials).

        '
    Bearer-Auth:
      type: http
      scheme: bearer
      description: 'The App API uses a bearer authentication scheme.


        You can generate a bearer token, known as an **App API Key**, with a defined scope in [your account settings](https://fly.customer.io/settings/api_credentials?keyType=app). [Learn more about bearer authorization in Customer.io](/accounts/settings/managing-credentials).

        '
    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/whatsapp`, `/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.


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


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

        '
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token.
x-tagGroups:
- name: Track API v2
  tags:
  - track_v2
  - Object Schemas
  - Person Schemas
  - Deliveries
- name: Track API
  tags:
  - trackOverview
  - trackJsOrBackend
  - trackLimit
  - trackRegion
  - Track Customers
  - Track Events
  - Forms
  - Track Segments
  - Track v1 Overview
- name: App API
  tags:
  - appOverview
  - appLimit
  - appAuth
  - Activities
  - Automations
  - Broadcasts
  - Collections
  - Customers
  - Data Index
  - ESP Suppression
  - Exports
  - Imports
  - Info
  - Live Notifications
  - Messages
  - Newsletters
  - Opt-outs
  - Reporting Webhooks
  - Segments
  - Sender Identities
  - Snippets
  - Subscription Center
  - Transactional
  - Workspaces
  - Send Messages
  - Objects
  - Newsletter Variants
  - Newsletter Metrics
  - Assets
- name: Design Studio API
  tags:
  - Folders
  - Components
  - Emails
  - Email link and publish
  - Email testing
  - SMS
  - SMS link and publish
x-provenance:
  method: harvested
  publisher: Customer.io
  source: https://docs.customer.io/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)