Customer.io Newsletters API

openapi: 3.1.0
info:
  title: Customer.io App Activities Newsletters API
  description: The Customer.io App API enables developers to manage workspace resources and send messages programmatically. It provides endpoints for sending transactional messages, triggering broadcasts, managing customers and segments, retrieving campaign and newsletter data, and exporting customer information. The API uses bearer token authentication with an App API key and is designed for operations that go beyond data ingestion, such as retrieving metrics, managing message templates, and automating outbound communications from Customer.io.
  version: 1.0.0
  contact:
    name: Customer.io Support
    url: https://customer.io/contact
  termsOfService: https://customer.io/legal/terms-of-service
servers:
- url: https://api.customer.io/v1
  description: US Production Server
- url: https://api-eu.customer.io/v1
  description: EU Production Server
security:
- bearerAuth: []
tags:
- name: Newsletters
  description: Retrieve information about newsletters and newsletter variants.
paths:
  /newsletters:
    get:
      operationId: listNewsletters
      summary: List newsletters
      description: Returns a list of newsletters in your workspace.
      tags:
      - Newsletters
      responses:
        '200':
          description: A list of newsletters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  newsletters:
                    type: array
                    items:
                      $ref: '#/components/schemas/Newsletter'
        '401':
          description: Unauthorized. Invalid App API key.
  /newsletters/{newsletter_id}:
    get:
      operationId: getNewsletter
      summary: Get a newsletter
      description: Returns detailed information about a specific newsletter.
      tags:
      - Newsletters
      parameters:
      - $ref: '#/components/parameters/NewsletterId'
      responses:
        '200':
          description: Newsletter details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  newsletter:
                    $ref: '#/components/schemas/Newsletter'
        '401':
          description: Unauthorized. Invalid App API key.
        '404':
          description: Newsletter not found.
  /newsletters/{newsletter_id}/metrics:
    get:
      operationId: getNewsletterMetrics
      summary: Get newsletter metrics
      description: Returns metrics for a specific newsletter including delivery statistics and engagement data.
      tags:
      - Newsletters
      parameters:
      - $ref: '#/components/parameters/NewsletterId'
      responses:
        '200':
          description: Newsletter metrics.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized. Invalid App API key.
        '404':
          description: Newsletter not found.
components:
  schemas:
    Newsletter:
      type: object
      description: A newsletter in Customer.io.
      properties:
        id:
          type: integer
          description: The unique newsletter identifier.
        name:
          type: string
          description: The newsletter name.
        created:
          type: integer
          description: UNIX timestamp of when the newsletter was created.
        updated:
          type: integer
          description: UNIX timestamp of when the newsletter was last updated.
        sent_at:
          type: integer
          description: UNIX timestamp of when the newsletter was sent.
        num_recipients:
          type: integer
          description: The number of recipients.
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the newsletter.
  parameters:
    NewsletterId:
      name: newsletter_id
      in: path
      required: true
      description: The unique identifier for the newsletter.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your App API key. Pass the key in the Authorization header as Bearer {app_api_key}.
externalDocs:
  description: App API Documentation
  url: https://docs.customer.io/integrations/api/app/