openapi: 3.0.1
info:
  title: Beehiiv API
  version: ''
paths:
  /publications/{publicationId}/advertisement_opportunities:
    get:
      description: >-
        Retrieve a list of accepted advertisement opportunities for the
        publication.
      operationId: advertisementOpportunities_index
      tags:
        - AdvertisementOpportunities
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvertisementOpportunitiesGetResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: 00000000-0000-0000-0000-000000000000
                        advertiser_name: beehiiv
                        payout_rate: $3.00/click
                        advertisement_kind: without logo
                        send_by_window_start_at: 1772562345
                        send_by_window_end_at: 1772994359
                      - id: 11111111-1111-1111-1111-111111111111
                        advertiser_name: Google
                        payout_rate: $2.00/1k opens
                        advertisement_kind: with logo
                        send_by_window_start_at: 1772562345
                        send_by_window_end_at: 1772994359
                    total_results: 2
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get advertisement opportunities <Badge intent="info" minimal
        outlined>OAuth Scope: posts:read</Badge>
      security: &ref_0
        - BearerAuth: []
  /publications/{publicationId}/authors:
    get:
      description: Retrieve a list of authors available for the publication.
      operationId: authors_index
      tags:
        - Authors
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).<br>If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: name
          in: query
          description: >-
            Optionally filter authors by full name or first name
            (case-insensitive).
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorsListResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: 00000000-0000-0000-0000-000000000000
                        type: user
                        name: Jane Doe
                        bio: Author biography.
                        bio_image_url: https://assets.beehiiv.com/example.png
                        social_media_links:
                          twitter_handle: jane_doe
                          instagram_url: https://instagram.com/janedoe
                          linkedin_url: https://linkedin.com/in/janedoe
                    limit: 10
                    page: 1
                    total_results: 1
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: List authors
      security: *ref_0
  /publications/{publicationId}/authors/{authorId}:
    get:
      description: Retrieve a single author from a publication.
      operationId: authors_show
      tags:
        - Authors
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: authorId
          in: path
          description: >-
            The author identifier. This accepts author UUID, full name, or first
            name.
          required: true
          schema:
            type: string
          example: Jane Doe
          examples:
            Example1:
              value: Jane Doe
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorsGetResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: 00000000-0000-0000-0000-000000000000
                      type: user
                      name: Jane Doe
                      bio: Author biography.
                      bio_image_url: https://assets.beehiiv.com/example.png
                      social_media_links:
                        twitter_handle: jane_doe
                        instagram_url: https://instagram.com/janedoe
                        linkedin_url: https://linkedin.com/in/janedoe
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get author
      security: *ref_0
  /publications/{publicationId}/automations/{automationId}/journeys:
    post:
      description: >-
        Add an existing subscription to an automation flow. Requires the
        automation to have an active *Add by API* trigger. The specified `email`
        or `subscription_id` will be matched against your existing subscribers.
        If an existing subscriber is found, they will be enrolled immediately.

        Looking to enroll new subscribers? Use the **[Create
        Subscription](/api-reference/subscriptions/create)** endpoint instead
        and specify the `automation_ids` param.
      operationId: automationJourneys_create
      tags:
        - AutomationJourneys
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: automationId
          in: path
          description: The prefixed ID of the automation object
          required: true
          schema:
            $ref: '#/components/schemas/AutomationId'
          example: aut_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: aut_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationJourneysResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: aj_00000000-0000-0000-0000-000000000000
                      automation_id: aut_00000000-0000-0000-0000-000000000000
                      subscription_id: sub_00000000-0000-0000-0000-000000000000
                      email: test@example.com
                      status: in_progress
                      started_at: 1714857600
                      completed_at: 1714861200
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Add subscription to an automation <Badge intent="info" minimal
        outlined>OAuth Scope: automations:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  nullable: true
                  description: The email address associated with the subscription.
                subscription_id:
                  $ref: '#/components/schemas/SubscriptionId'
                  nullable: true
                double_opt_override:
                  $ref: '#/components/schemas/DoubleOptOverride'
                  nullable: true
                  description: >-
                    Override the publication's default double opt-in settings
                    for this subscription. Possible values are:

                    - "on" — The subscriber will receive a double opt-in
                    confirmation email and will need to confirm their
                    subscription prior to being marked as active.

                    - "off" — The subscriber will be marked as active
                    immediately and will not receive a double opt-in
                    confirmation email.

                    - "not_set" — The publication's default double opt-in
                    settings will be applied to this subscription.
            examples:
              Example1:
                value:
                  email: test@example.com
                  double_opt_override: 'on'
    get:
      description: >-
        Retrieve a list of automation journeys that have occurred within a
        specific automation.
      operationId: automationJourneys_index
      tags:
        - AutomationJourneys
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: automationId
          in: path
          description: The prefixed ID of the automation object
          required: true
          schema:
            $ref: '#/components/schemas/AutomationId'
          example: aut_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: aut_00000000-0000-0000-0000-000000000000
        - name: status
          in: query
          description: Optionally filter the results by the automation journey's status.
          required: false
          schema:
            $ref: '#/components/schemas/AutomationJourneysGetRequestStatus'
            nullable: true
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationJourneysIndexResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: aj_00000000-0000-0000-0000-000000000000
                        automation_id: aut_00000000-0000-0000-0000-000000000000
                        subscription_id: sub_00000000-0000-0000-0000-000000000000
                        email: test@example.com
                        status: in_progress
                        started_at: 1714857600
                        completed_at: 1714861200
                      - id: aj_00000000-0000-0000-0000-000000000000
                        automation_id: aut_00000000-0000-0000-0000-000000000000
                        subscription_id: sub_00000000-0000-0000-0000-000000000000
                        email: test@example.com
                        status: in_progress
                        started_at: 1714857600
                        completed_at: 1714861200
                    limit: 10
                    page: 1
                    total_results: 2
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List automation journeys <Badge intent="info" minimal outlined>OAuth
        Scope: automations:read</Badge>
      security: *ref_0
  /publications/{publicationId}/automations/{automationId}/journeys/{automationJourneyId}:
    get:
      description: Retrieve a single automation journey by ID.
      operationId: automationJourneys_show
      tags:
        - AutomationJourneys
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: automationId
          in: path
          description: The prefixed ID of the automation object
          required: true
          schema:
            $ref: '#/components/schemas/AutomationId'
          example: aut_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: aut_00000000-0000-0000-0000-000000000000
        - name: automationJourneyId
          in: path
          description: The prefixed automation journey id
          required: true
          schema:
            $ref: '#/components/schemas/AutomationJourneyId'
          example: aj_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: aj_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationJourneysResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: aj_00000000-0000-0000-0000-000000000000
                      automation_id: aut_00000000-0000-0000-0000-000000000000
                      subscription_id: sub_00000000-0000-0000-0000-000000000000
                      email: test@example.com
                      status: in_progress
                      started_at: 1714857600
                      completed_at: 1714861200
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get automation journey <Badge intent="info" minimal outlined>OAuth
        Scope: automations:read</Badge>
      security: *ref_0
  /publications/{publicationId}/automations:
    get:
      description: Retrieve automations for a publication.
      operationId: automations_index
      tags:
        - Automations
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: Optional list of expandable objects.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AutomationsListRequestExpandItem'
              nullable: true
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).<br>If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationsListResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: aut_00000000-0000-0000-0000-000000000000
                        status: running
                        name: Custom welcome series
                        trigger_events:
                          - api
                        description: Sends 2 days after signing up
                    limit: 1
                    page: 1
                    total_results: 1
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List automations <Badge intent="info" minimal outlined>OAuth Scope:
        automations:read</Badge>
      security: *ref_0
  /publications/{publicationId}/automations/{automationId}:
    get:
      description: Retrieve a single automation for a publication.
      operationId: automations_show
      tags:
        - Automations
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: automationId
          in: path
          description: The prefixed ID of the automation object
          required: true
          schema:
            $ref: '#/components/schemas/AutomationId'
          example: aut_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: aut_00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: Optional list of expandable objects.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AutomationsGetRequestExpandItem'
              nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationsGetResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: aut_00000000-0000-0000-0000-000000000000
                      status: running
                      name: Custom welcome series
                      trigger_events:
                        - api
                      description: Sends 2 days after signing up
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get automation <Badge intent="info" minimal outlined>OAuth Scope:
        automations:read</Badge>
      security: *ref_0
  /publications/{publicationId}/automations/{automationId}/emails:
    get:
      description: >-
        Retrieve all emails belonging to a specific automation, including
        engagement statistics for each email.
      operationId: automations_listEmails
      tags:
        - Automations
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: automationId
          in: path
          description: The prefixed ID of the automation object
          required: true
          schema:
            $ref: '#/components/schemas/AutomationId'
          example: aut_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: aut_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: cursor
          in: query
          description: >-
            **Cursor-based pagination (recommended)**: Use this opaque cursor
            token to fetch the next page of results. Obtain it from the
            `next_cursor` field of a previous response.
          required: false
          schema:
            type: string
            nullable: true
        - name: page
          in: query
          description: >-
            **Deprecated**: Use `cursor` instead. Pagination returns the results
            in pages. Limited to 100 pages maximum.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationEmailsListResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: 00000000-0000-0000-0000-000000000000
                        automation_step_id: 00000000-0000-0000-0000-000000000000
                        subject_line: Welcome to our newsletter!
                        preview_text: Here's what to expect...
                        status: active
                        first_sent_at: 1700000000
                        last_sent_at: 1700100000
                        created_at: 1699900000
                        stats:
                          email:
                            recipients: 500
                            delivered: 490
                            opens: 250
                            unique_opens: 200
                            open_rate: 40.82
                            clicks: 100
                            unique_clicks: 75
                            click_rate: 37.5
                            unsubscribes: 2
                            spam_reports: 1
                          clicks:
                            - url: https://example.com/link
                              total_clicks: 80
                              total_unique_clicks: 60
                              total_click_through_rate: 30
                    limit: 10
                    has_more: false
                    next_cursor: null
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: List automation emails
      security: *ref_0
  /publications/{publicationId}/bulk_subscriptions:
    post:
      description: Create new subscriptions for a publication.
      operationId: bulkSubscriptions_create
      tags:
        - BulkSubscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Subscriptions created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubscriptionCreateResponse'
              examples:
                Example1:
                  value:
                    message: Bulk Subscription Create Request Sent.
                    import_id: 00000000-0000-0000-0000-000000000000
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Bulk create subscription <Badge intent="info" minimal outlined>OAuth
        Scope: subscriptions:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subscriptions:
                  type: array
                  items:
                    $ref: '#/components/schemas/SubscriptionRequest'
              required:
                - subscriptions
            examples:
              Example1:
                value:
                  subscriptions:
                    - email: bruce.wayne@wayneenterprise.com
                      reactivate_existing: false
                      send_welcome_email: false
                      custom_fields:
                        - name: Favorite Color
                          value: Red
                    - email: lucius.fox@wayneenterprise.com
                      reactivate_existing: false
                      send_welcome_email: false
                      custom_fields:
                        - name: Favorite Color
                          value: Blue
  /publications/{publicationId}/bulk_subscription_updates:
    get:
      description: Returns a list of Subscription Update objects for a publication.
      operationId: bulkSubscriptionUpdates_index
      tags:
        - BulkSubscriptionUpdates
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubscriptionUpdatesListResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: id
                        type: status
                        params: params
                        status: pending
                        publication_id: publication_id
                        failure_reason: failure_reason
                        completed: 1
                        created: 1
                        updated: 1
                        error_log:
                          - error_log
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List subscription updates <Badge intent="info" minimal outlined>OAuth
        Scope: subscriptions:read</Badge>
      security: *ref_0
  /publications/{publicationId}/bulk_subscription_updates/{id}:
    get:
      description: Returns a single Subscription Update object for a publication.
      operationId: bulkSubscriptionUpdates_show
      tags:
        - BulkSubscriptionUpdates
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
        - name: id
          in: path
          description: The ID of the Subscription Update object
          required: true
          schema:
            type: string
          example: id
          examples:
            Example1:
              value: id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubscriptionUpdatesGetResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: id
                      type: bulk
                      params: params
                      status: pending
                      publication_id: publication_id
                      failure_reason: failure_reason
                      completed: 1
                      created: 1
                      updated: 1
                      error_log:
                        - error_log
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get subscription update <Badge intent="info" minimal outlined>OAuth
        Scope: subscriptions:read</Badge>
      security: *ref_0
  /publications/{publicationId}/subscriptions/bulk_actions:
    put:
      description: >-
        Bulk update multiple subscriptions fields, including status, custom
        fields, and tiers.
      operationId: bulkSubscriptionUpdates_put
      tags:
        - BulkSubscriptionUpdates
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsPatchResponse'
              examples:
                Example1:
                  value:
                    data:
                      subscription_update_id: subscription_update_id
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update subscriptions <Badge intent="info" minimal outlined>OAuth Scope:
        subscriptions:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subscriptions:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/SubscriptionsPatchRequestSubscriptionsItem
                  nullable: true
                  description: >-
                    An array of objects representing the subscriptions to be
                    updated (max 1000).
            examples:
              Example1:
                value:
                  subscriptions:
                    - subscription_id: sub_1234-5678-9012-3456-7890
                      tier: premium
                      stripe_customer_id: cus_1234567890
                      unsubscribe: false
                      custom_fields:
                        - name: custom_field_name
                          value: custom_field_value
                        - name: custom_field_name_2
                          value: custom_field_value_2
                    - subscription_id: sub_9876-5432-1098-7654-3210
                      tier: free
                      stripe_customer_id: cus_1234567890
                      unsubscribe: true
                      custom_fields:
                        - name: custom_field_name_3
                          value: custom_field_value_3
                        - name: custom_field_name_4
                          value: custom_field_value_4
    patch:
      description: >-
        Bulk update multiple subscriptions fields, including status, custom
        fields, and tiers.
      operationId: bulkSubscriptionUpdates_patch
      tags:
        - BulkSubscriptionUpdates
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsPatchResponse'
              examples:
                Example1:
                  value:
                    data:
                      subscription_update_id: subscription_update_id
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update subscriptions <Badge intent="info" minimal outlined>OAuth Scope:
        subscriptions:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subscriptions:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/SubscriptionsPatchRequestSubscriptionsItem
                  nullable: true
                  description: >-
                    An array of objects representing the subscriptions to be
                    updated (max 1000).
            examples:
              Example1:
                value:
                  subscriptions:
                    - subscription_id: sub_1234-5678-9012-3456-7890
                      tier: premium
                      stripe_customer_id: cus_1234567890
                      unsubscribe: false
                      custom_fields:
                        - name: custom_field_name
                          value: custom_field_value
                        - name: custom_field_name_2
                          value: custom_field_value_2
                    - subscription_id: sub_9876-5432-1098-7654-3210
                      tier: free
                      stripe_customer_id: cus_1234567890
                      unsubscribe: true
                      custom_fields:
                        - name: custom_field_name_3
                          value: custom_field_value_3
                        - name: custom_field_name_4
                          value: custom_field_value_4
  /publications/{publicationId}/subscriptions:
    put:
      description: Bulk update subscriptions' status.
      operationId: bulkSubscriptionUpdates_put-status
      tags:
        - BulkSubscriptionUpdates
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
      responses:
        '204':
          description: ''
      summary: >-
        Update subscriptions' status <Badge intent="info" minimal outlined>OAuth
        Scope: subscriptions:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subscription_ids:
                  type: array
                  items:
                    type: string
                  description: An array of subscription IDs to be updated
                  example:
                    - sub_1234-5678-9012-3456-7890
                    - sub_9876-5432-1098-7654-3210
                new_status:
                  type: string
                  description: The new status to set for the subscriptions
                  example: active
              required:
                - subscription_ids
                - new_status
            examples:
              Example1:
                value:
                  subscription_ids:
                    - sub_1234-5678-9012-3456-7890
                    - sub_9876-5432-1098-7654-3210
                  new_status: active
    patch:
      description: Bulk update subscriptions' status.
      operationId: bulkSubscriptionUpdates_patch-status
      tags:
        - BulkSubscriptionUpdates
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
      responses:
        '204':
          description: ''
      summary: >-
        Update subscriptions' status <Badge intent="info" minimal outlined>OAuth
        Scope: subscriptions:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subscription_ids:
                  type: array
                  items:
                    type: string
                  description: An array of subscription IDs to be updated
                  example:
                    - sub_1234-5678-9012-3456-7890
                    - sub_9876-5432-1098-7654-3210
                new_status:
                  type: string
                  description: The new status to set for the subscriptions
                  example: active
              required:
                - subscription_ids
                - new_status
            examples:
              Example1:
                value:
                  subscription_ids:
                    - sub_1234-5678-9012-3456-7890
                    - sub_9876-5432-1098-7654-3210
                  new_status: active
    post:
      description: Create new subscriptions for a publication.
      operationId: subscriptions_create
      tags:
        - Subscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: sub_00000000-0000-0000-0000-000000000000
                      email: example@example.com
                      status: validating
                      created: 1666800076
                      subscription_tier: free
                      subscription_premium_tier_names:
                        - Premium
                        - Gold
                      utm_source: Twitter
                      utm_medium: organic
                      utm_channel: website
                      utm_campaign: utm_campaign
                      utm_term: ''
                      utm_content: ''
                      referring_site: https://www.blog.com
                      referral_code: referral_code
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Create subscription <Badge intent="info" minimal outlined>OAuth Scope:
        subscriptions:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
            examples:
              Example1:
                value:
                  email: bruce.wayne@wayneenterprise.com
                  reactivate_existing: false
                  send_welcome_email: false
                  utm_source: WayneEnterprise
                  utm_medium: organic
                  utm_campaign: fall_2022_promotion
                  referring_site: www.wayneenterprise.com/blog
                  custom_fields:
                    - name: First Name
                      value: Bruce
                    - name: Last Name
                      value: Wayne
                  stripe_customer_id: cus_12345abcde
                  newsletter_list_ids:
                    - nl_list_00000000-0000-0000-0000-000000000000
    get:
      description: >-
        Retrieve all subscriptions belonging to a specific publication.


        <Info> **New**: This endpoint now supports cursor-based pagination for
        better performance and consistency. Use the `cursor` parameter instead
        of `page` for new integrations. </Info>

        <Warning> **Deprecation Notice**: Offset-based pagination (using `page`
        parameter) is deprecated and limited to 100 pages maximum. Please
        migrate to cursor-based pagination. See our [Pagination
        Guide](/welcome/pagination) for details. </Warning>
      operationId: subscriptions_index
      tags:
        - Subscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Cursor-based pagination (recommended):
              value: pub_00000000-0000-0000-0000-000000000000
            Cursor-based pagination (next page):
              value: pub_00000000-0000-0000-0000-000000000000
            Offset-based pagination (deprecated):
              value: pub_00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: >-
            Optional list of expandable objects.<br>`subscription_premium_tiers
            ` - Returns an array of tiers the subscription is associated
            with.<br>`referrals` - Returns an array of subscriptions with
            limited data - `id`, `email`, and `status`. These are the
            subscriptions that were referred by this subscription.<br>`stats` -
            Returns statistics about the subscription(s).<br>`custom_fields` -
            Returns an array of custom field values that have been set on the
            subscription. <br>`newsletter_lists` - Returns an array of
            newsletter list prefixed IDs the subscription is actively subscribed
            to.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SubscriptionsListRequestExpandItem'
              nullable: true
        - name: status
          in: query
          description: Optionally filter the results by a status
          required: false
          schema:
            $ref: '#/components/schemas/SubscriptionsListRequestStatus'
            nullable: true
        - name: tier
          in: query
          description: Optionally filter the results by a their tier
          required: false
          schema:
            $ref: '#/components/schemas/SubscriptionsListRequestTier'
            nullable: true
        - name: premium_tiers[]
          in: query
          description: Optionally filter the results by one or multiple premium tiers
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: premium_tier_ids[]
          in: query
          description: Optionally filter the results by one or multiple premium tier ids
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
          example: 10
          examples:
            Cursor-based pagination (recommended):
              value: 10
            Cursor-based pagination (next page):
              value: 10
            Offset-based pagination (deprecated):
              value: 10
        - name: cursor
          in: query
          description: >-
            **Cursor-based pagination (recommended)**: Use this opaque cursor
            token to fetch the next page of results. When provided, pagination
            will use cursor-based method which is more efficient and consistent
            than offset-based pagination. See the [Pagination
            Guide](/welcome/pagination) for more details.
          required: false
          schema:
            type: string
            nullable: true
          example: eyJ0aW1lc3RhbXAiOiIyMDI0LTA3LTAyVDE3OjMwOjAwLjAwMDAwMFoifQ==
          examples:
            Cursor-based pagination (next page):
              value: eyJ0aW1lc3RhbXAiOiIyMDI0LTA3LTAyVDE3OjMwOjAwLjAwMDAwMFoifQ==
        - name: page
          in: query
          description: >-
            **Offset-based pagination (deprecated)**: Page number for
            offset-based pagination. This method is deprecated and limited to
            100 pages maximum. Please migrate to cursor-based pagination using
            the `cursor` parameter. If not specified, results 1-10 from page 1
            will be returned. See the [Pagination Guide](/welcome/pagination)
            for migration guidance.
          required: false
          schema:
            type: integer
            nullable: true
          example: 1
          examples:
            Offset-based pagination (deprecated):
              value: 1
        - name: email
          in: query
          description: >-
            Optional email address to find a subscription.<br>This param must be
            an exact match and is case insensitive.
          required: false
          schema:
            type: string
            nullable: true
          example: clark@dailyplanet.com
          examples:
            Offset-based pagination (deprecated):
              value: clark@dailyplanet.com
        - name: order_by
          in: query
          description: >-
            The field that the results are sorted by. Defaults to created<br>
            `created` - The time in which the subscription was first
            created.<br>
          required: false
          schema:
            $ref: '#/components/schemas/SubscriptionsListRequestOrderBy'
            nullable: true
        - name: direction
          in: query
          description: >-
            The direction that the results are sorted in. Defaults to asc<br>
            `asc` - Ascending, sorts from smallest to largest.<br> `desc` -
            Descending, sorts from largest to smallest.
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
        - name: creation_date
          in: query
          description: >-
            Optional date entry (in the format YYYY/MM/DD) that filters returned
            subscriptions by their creation date.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsListResponse'
              examples:
                Cursor-based pagination (recommended):
                  value:
                    data:
                      - id: sub_00000000-0000-0000-0000-000000000000
                        email: example@example.com
                        status: validating
                        created: 1666800076
                        subscription_tier: free
                        subscription_premium_tier_names:
                          - Premium
                          - Gold
                        utm_source: Twitter
                        utm_medium: organic
                        utm_channel: website
                        utm_campaign: utm_campaign
                        utm_term: ''
                        utm_content: ''
                        referring_site: https://www.blog.com
                        referral_code: referral_code
                        subscription_premium_tiers:
                          - id: tier_00000000-0000-0000-0000-000000000000
                            name: name
                            status: active
                        custom_fields:
                          - {}
                        tags:
                          - Premium
                          - Basic
                          - Active
                          - Engaged
                        stats:
                          emails_received: 25
                          open_rate: 60.1
                          click_through_rate: 25
                    limit: 10
                    has_more: true
                    next_cursor: >-
                      eyJ0aW1lc3RhbXAiOiIyMDI0LTA3LTAyVDE3OjMwOjAwLjAwMDAwMFoifQ==
                Cursor-based pagination (next page):
                  value:
                    data:
                      - id: sub_11111111-1111-1111-1111-111111111111
                        email: next@example.com
                        status: active
                        created: 1666800000
                        subscription_tier: premium
                        subscription_premium_tier_names:
                          - Premium
                        utm_source: Direct
                        utm_medium: email
                        utm_channel: website
                        utm_campaign: welcome_series
                        utm_term: ''
                        utm_content: ''
                        referring_site: https://www.example.com
                        referral_code: WELCOME2024
                        subscription_premium_tiers:
                          - id: tier_11111111-1111-1111-1111-111111111111
                            name: Premium
                            status: active
                        custom_fields:
                          - {}
                        tags:
                          - Premium
                          - New
                        stats:
                          emails_received: 15
                          open_rate: 45.2
                          click_through_rate: 18.5
                    limit: 10
                    has_more: false
                    next_cursor: null
                Offset-based pagination (deprecated):
                  value:
                    data:
                      - id: sub_00000000-0000-0000-0000-000000000000
                        email: example@example.com
                        status: validating
                        created: 1666800076
                        subscription_tier: free
                        subscription_premium_tier_names:
                          - Premium
                          - Gold
                        utm_source: Twitter
                        utm_medium: organic
                        utm_channel: website
                        utm_campaign: utm_campaign
                        utm_term: ''
                        utm_content: ''
                        referring_site: https://www.blog.com
                        referral_code: referral_code
                        subscription_premium_tiers:
                          - id: tier_00000000-0000-0000-0000-000000000000
                            name: name
                            status: active
                        custom_fields:
                          - {}
                        tags:
                          - Premium
                          - Basic
                          - Active
                          - Engaged
                        stats:
                          emails_received: 25
                          open_rate: 60.1
                          click_through_rate: 25
                    limit: 10
                    page: 1
                    total_results: 1500
                    total_pages: 150
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List subscriptions <Badge intent="info" minimal outlined>OAuth Scope:
        subscriptions:read</Badge>
      security: *ref_0
  /publications/{publicationId}/condition_sets:
    get:
      description: >-
        Retrieve all active condition sets for a publication. Condition sets
        define reusable audience segments for targeting content to specific
        subscribers. Use the `purpose` parameter to filter by a specific use
        case.
      operationId: conditionSets_index
      tags:
        - ConditionSets
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Default:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
          example: 10
          examples:
            Default:
              value: 10
        - name: cursor
          in: query
          description: >-
            **Cursor-based pagination (recommended)**: Use this opaque cursor
            token to fetch the next page of results. When provided, pagination
            will use cursor-based method which is more efficient and consistent
            than offset-based pagination.
          required: false
          schema:
            type: string
            nullable: true
        - name: page
          in: query
          description: >-
            **Offset-based pagination (deprecated)**: Page number for
            offset-based pagination. Please migrate to cursor-based pagination
            using the `cursor` parameter. If not specified, results 1-10 from
            page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: purpose
          in: query
          description: >-
            Filter condition sets by purpose. When not specified, all active
            condition sets are returned.
          required: false
          schema:
            $ref: '#/components/schemas/ConditionSetPurpose'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConditionSetsListResponse'
              examples:
                Default:
                  value:
                    data:
                      - id: 00000000-0000-0000-0000-000000000000
                        name: Premium subscribers only
                        status: active
                        created: 1700000000
                        updated: 1700000000
                        purpose: dynamic_content
                      - id: 11111111-1111-1111-1111-111111111111
                        name: Free subscribers in US
                        status: active
                        created: 1700000001
                        updated: 1700000001
                        purpose: dynamic_content
                    limit: 10
                    has_more: false
                    next_cursor: null
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List condition sets <Badge intent="info" minimal outlined>OAuth Scope:
        condition_sets:read</Badge>
      security: *ref_0
  /publications/{publicationId}/condition_sets/{conditionSetId}:
    get:
      description: >-
        Retrieve a single active dynamic content condition set for a
        publication. Use `expand[]=stats` to calculate and return the active
        subscriber count synchronously.
      operationId: conditionSets_show
      tags:
        - ConditionSets
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
            With stats expansion:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: conditionSetId
          in: path
          description: The UUID of the condition set object
          required: true
          schema:
            type: string
          example: 00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: 00000000-0000-0000-0000-000000000000
            With stats expansion:
              value: 00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: >-
            Optionally expand the response to include additional data.<br>
            `stats` - Calculates and returns the active subscriber count for
            this condition set synchronously.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ConditionSetShowExpandItems'
            nullable: true
          example: &ref_1
            - stats
          examples:
            With stats expansion:
              value: *ref_1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConditionSetShowResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: 00000000-0000-0000-0000-000000000000
                      name: Premium subscribers only
                      status: active
                      created: 1700000000
                      updated: 1700000000
                      purpose: dynamic_content
                With stats expansion:
                  value:
                    data:
                      id: 00000000-0000-0000-0000-000000000000
                      name: Premium subscribers only
                      status: active
                      created: 1700000000
                      updated: 1700000000
                      purpose: dynamic_content
                      stats:
                        active_subscriber_count: 4200
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get condition set <Badge intent="info" minimal outlined>OAuth Scope:
        condition_sets:read</Badge>
      security: *ref_0
  /publications/{publicationId}/custom_fields:
    post:
      description: Create a custom field on a publication, for use in subscriptions.
      operationId: customFields_create
      tags:
        - CustomFields
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: 00000000-0000-0000-0000-000000000000
                      kind: string
                      display: Display
                      created: 1672531200
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Create custom field <Badge intent="info" minimal outlined>OAuth Scope:
        custom_fields:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                kind:
                  $ref: '#/components/schemas/CustomFieldType'
                display:
                  type: string
                  example: Display
              required:
                - kind
                - display
            examples:
              Example1:
                value:
                  kind: string
                  display: Display
    get:
      description: List all custom fields on a publication.
      operationId: customFields_index
      tags:
        - CustomFields
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldIndexResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: 00000000-0000-0000-0000-000000000000
                        kind: string
                        display: Display
                        created: 1672531200
                      - id: 00000000-0000-0000-0000-000000000000
                        kind: list
                        display: Dropdown Field
                        created: 1672531200
                        options:
                          - Option 1
                          - Option 2
                          - Option 3
                    limit: 10
                    page: 1
                    total_results: 20
                    total_pages: 2
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List custom fields <Badge intent="info" minimal outlined>OAuth Scope:
        custom_fields:read</Badge>
      security: *ref_0
  /publications/{publicationId}/custom_fields/{id}:
    get:
      description: View a specific custom field on a publication.
      operationId: customFields_show
      tags:
        - CustomFields
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
        - name: id
          in: path
          description: The ID of the Custom Fields object
          required: true
          schema:
            type: string
          example: id
          examples:
            Example1:
              value: id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: 00000000-0000-0000-0000-000000000000
                      kind: string
                      display: Display
                      created: 1672531200
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get custom field <Badge intent="info" minimal outlined>OAuth Scope:
        custom_fields:read</Badge>
      security: *ref_0
    put:
      description: Update a custom field on a publication.
      operationId: customFields_put
      tags:
        - CustomFields
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
        - name: id
          in: path
          description: The ID of the Custom Fields object
          required: true
          schema:
            type: string
          example: id
          examples:
            Example1:
              value: id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: id
                      display: display
                      kind: string
                      created: 1672531200
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update custom field <Badge intent="info" minimal outlined>OAuth Scope:
        custom_fields:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                display:
                  type: string
                  nullable: true
            examples:
              Example1:
                value:
                  display: New Display
    patch:
      description: Update a custom field on a publication.
      operationId: customFields_patch
      tags:
        - CustomFields
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
        - name: id
          in: path
          description: The ID of the Custom Fields object
          required: true
          schema:
            type: string
          example: id
          examples:
            Example1:
              value: id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldsPatchResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: id
                      display: display
                      kind: string
                      created: 1672531200
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update custom field <Badge intent="info" minimal outlined>OAuth Scope:
        custom_fields:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                display:
                  type: string
                  nullable: true
            examples:
              Example1:
                value:
                  display: New Display
    delete:
      description: Delete a custom field from a publication.
      operationId: customFields_delete
      tags:
        - CustomFields
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
        - name: id
          in: path
          description: The ID of the Custom Fields object
          required: true
          schema:
            type: string
          example: id
          examples:
            Example1:
              value: id
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldsDeleteResponse'
              examples:
                Example1:
                  value: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Delete custom field <Badge intent="info" minimal outlined>OAuth Scope:
        custom_fields:write</Badge>
      security: *ref_0
  /publications/{publicationId}/email_blasts:
    get:
      description: Retrieve all email blasts belonging to a specific publication.
      operationId: emailBlasts_index
      tags:
        - EmailBlasts
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: Optional list of expandable objects.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/EmailBlastsListRequestExpandItem'
              nullable: true
        - name: status
          in: query
          description: >-
            Optionally filter the results by the status of the email blast.
            Defaults to active.
          required: false
          schema:
            $ref: '#/components/schemas/EmailBlastsListRequestStatus'
            nullable: true
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10). If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: order_by
          in: query
          description: The field that the results are sorted by. Defaults to created.
          required: false
          schema:
            $ref: '#/components/schemas/EmailBlastsListRequestOrderBy'
            nullable: true
        - name: direction
          in: query
          description: The direction that the results are sorted in. Defaults to desc.
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailBlastsListResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: blast_00000000-0000-0000-0000-000000000000
                        subject_line: Check out our latest news!
                        preview_text: Exciting updates inside
                        created: 1666800076
                        last_sent: 1666800076
                        status: active
                    limit: 1
                    page: 1
                    total_results: 1
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List email blasts <Badge intent="info" minimal outlined>OAuth Scope:
        posts:read</Badge>
      security: *ref_0
  /publications/{publicationId}/email_blasts/{emailBlastId}:
    get:
      description: Retrieve a single email blast belonging to a specific publication.
      operationId: emailBlasts_show
      tags:
        - EmailBlasts
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: emailBlastId
          in: path
          description: The prefixed ID of the email blast object
          required: true
          schema:
            $ref: '#/components/schemas/EmailBlastId'
          example: blast_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: blast_00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: Optional list of expandable objects.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/EmailBlastsGetRequestExpandItem'
              nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailBlastsGetResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: blast_00000000-0000-0000-0000-000000000000
                      subject_line: Check out our latest news!
                      preview_text: Exciting updates inside
                      created: 1666800076
                      last_sent: 1666800076
                      status: active
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get email blast <Badge intent="info" minimal outlined>OAuth Scope:
        posts:read</Badge>
      security: *ref_0
  /publications/{publicationId}/engagements:
    get:
      description: >-
        Retrieve email engagement metrics for a specific publication over a
        defined date range and granularity.<br><br> By default, the endpoint
        returns metrics for the past day, aggregated daily. The max number of
        days allowed is 31. All dates and times are in UTC.
      operationId: engagements_index
      tags:
        - Engagements
      parameters:
        - name: publicationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_ad76629e-4a39-43ad-8055-0ee89dc6db15
          examples:
            Example1:
              value: pub_ad76629e-4a39-43ad-8055-0ee89dc6db15
        - name: start_date
          in: query
          description: >-
            The starting date for the engagement metrics in `YYYY-MM-DD` format.
            Defaults to 1 day ago if not provided.
          required: false
          schema:
            type: string
            format: date
            nullable: true
        - name: number_of_days
          in: query
          description: >-
            The number of days to return engagement metrics for, starting from
            `start_date`. Must be between 1 and 31. Defaults to `1` if not
            provided.
          required: false
          schema:
            $ref: '#/components/schemas/NumberOfDays'
            nullable: true
        - name: granularity
          in: query
          description: >-
            The granularity at which to report the engagement metrics. Defaults
            to `day` if not provided.
          required: false
          schema:
            $ref: '#/components/schemas/PublicationEngagementGranularity'
            nullable: true
        - name: email_type
          in: query
          description: >-
            Filter engagement metrics by email type. If omitted, all email
            engagement is included.<br> `post`: Only post emails.<br> `message`:
            Only automated and system-generated emails.
          required: false
          schema:
            $ref: '#/components/schemas/PublicationEngagementEmailType'
            nullable: true
        - name: direction
          in: query
          description: >-
            The direction that the results are sorted in. Defaults to `asc`.<br>
            `asc`: Oldest to newest<br> `desc`: Newest to oldest
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicationEngagementsResponse'
              examples:
                Example1:
                  value:
                    data:
                      - date: '2025-01-01'
                        total_opens: 150
                        unique_opens: 120
                        total_clicks: 75
                        total_verified_clicks: 70
                        unique_clicks: 60
                        unique_verified_clicks: 55
                    publication_id: pub_ad76629e-4a39-43ad-8055-0ee89dc6db15
                    granularity: day
                    email_type: all
                    start_date: '2025-01-01'
                    number_of_days: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get publication engagements <Badge intent="info" minimal outlined>OAuth
        Scope: publications:read</Badge>
      security: *ref_0
  /publications/{publicationId}/newsletter_lists:
    get:
      description: |-
        <Note title="Currently in beta" icon="b">
          Newsletter Lists is currently in beta, the API is subject to change.
        </Note>
        List all newsletter lists for a publication.
      operationId: newsletterLists_index
      tags:
        - NewsletterLists
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).<br>If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: direction
          in: query
          description: >-
            The direction that the results are sorted in. Defaults to asc<br>
            `asc` - Ascending, sorts from smallest to largest.<br> `desc` -
            Descending, sorts from largest to smallest.
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterListIndexResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: nl_list_00000000-0000-0000-0000-000000000000
                        name: Weekly Digest
                        slug: weekly-digest
                        description: A weekly digest of the best content.
                        status: active
                        auto_subscribe: false
                        subscriber_count: 100
                        created_at: 1672531200
                        updated_at: 1672531200
                    limit: 10
                    page: 1
                    total_results: 1
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List newsletter lists <Badge intent="warning" minimal
        outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope:
        newsletter_lists:read</Badge>
      security: *ref_0
  /publications/{publicationId}/newsletter_lists/{newsletterListId}:
    get:
      description: |-
        <Note title="Currently in beta" icon="b">
          Newsletter Lists is currently in beta, the API is subject to change.
        </Note>
        Retrieve a single newsletter list belonging to a specific publication.
      operationId: newsletterLists_show
      tags:
        - NewsletterLists
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: newsletterListId
          in: path
          description: The prefixed ID of the newsletter list object
          required: true
          schema:
            $ref: '#/components/schemas/NewsletterListId'
          example: nl_list_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: nl_list_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterListResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: nl_list_00000000-0000-0000-0000-000000000000
                      name: Weekly Digest
                      slug: weekly-digest
                      description: A weekly digest of the best content.
                      status: active
                      auto_subscribe: false
                      subscriber_count: 100
                      created_at: 1672531200
                      updated_at: 1672531200
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get newsletter list <Badge intent="warning" minimal
        outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope:
        newsletter_lists:read</Badge>
      security: *ref_0
  /publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions:
    post:
      description: >-
        <Note title="Currently in beta" icon="b">
          Newsletter Lists is currently in beta, the API is subject to change.
        </Note>

        Subscribe a subscription to a newsletter list. Accepts either a
        subscription_id or email to identify the subscription.
      operationId: newsletterListSubscriptions_create
      tags:
        - NewsletterListSubscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: newsletterListId
          in: path
          description: The prefixed ID of the newsletter list object
          required: true
          schema:
            $ref: '#/components/schemas/NewsletterListId'
          example: nl_list_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: nl_list_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterListSubscriptionResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: nl_list_sub_00000000-0000-0000-0000-000000000000
                      newsletter_list_id: nl_list_00000000-0000-0000-0000-000000000000
                      subscription_id: sub_00000000-0000-0000-0000-000000000000
                      status: active
                      subscribed_at: 1672531200
                      unsubscribed_at: null
                      created_at: 1672531200
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Create newsletter list subscription <Badge intent="warning" minimal
        outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope:
        newsletter_lists:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subscription_id:
                  $ref: '#/components/schemas/SubscriptionId'
                  nullable: true
                  description: >-
                    The prefixed ID of the subscription to subscribe. Either
                    subscription_id or email must be provided.
                email:
                  type: string
                  nullable: true
                  description: >-
                    The email address of the subscription to subscribe. Either
                    subscription_id or email must be provided.
            examples:
              Example1:
                value:
                  subscription_id: sub_00000000-0000-0000-0000-000000000000
    get:
      description: |-
        <Note title="Currently in beta" icon="b">
          Newsletter Lists is currently in beta, the API is subject to change.
        </Note>
        List all subscriptions for a newsletter list.
      operationId: newsletterListSubscriptions_index
      tags:
        - NewsletterListSubscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: newsletterListId
          in: path
          description: The prefixed ID of the newsletter list object
          required: true
          schema:
            $ref: '#/components/schemas/NewsletterListId'
          example: nl_list_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: nl_list_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: cursor
          in: query
          description: >-
            **Cursor-based pagination (recommended)**: Use this opaque cursor
            token to fetch the next page of results. When provided, pagination
            will use cursor-based method which is more efficient and consistent
            than offset-based pagination.
          required: false
          schema:
            type: string
            nullable: true
        - name: page
          in: query
          description: >-
            **Offset-based pagination (deprecated)**: Page number for
            offset-based pagination. Please migrate to cursor-based pagination
            using the `cursor` parameter. If not specified, results 1-10 from
            page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: direction
          in: query
          description: >-
            The direction that the results are sorted in. Defaults to asc<br>
            `asc` - Ascending, sorts from smallest to largest.<br> `desc` -
            Descending, sorts from largest to smallest.
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterListSubscriptionIndexResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: nl_list_sub_00000000-0000-0000-0000-000000000000
                        newsletter_list_id: nl_list_00000000-0000-0000-0000-000000000000
                        subscription_id: sub_00000000-0000-0000-0000-000000000000
                        status: active
                        subscribed_at: 1672531200
                        unsubscribed_at: null
                        created_at: 1672531200
                    limit: 10
                    has_more: false
                    next_cursor: null
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List newsletter list subscriptions <Badge intent="warning" minimal
        outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope:
        newsletter_lists:read</Badge>
      security: *ref_0
  /publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions/{newsletterListSubscriptionId}:
    get:
      description: |-
        <Note title="Currently in beta" icon="b">
          Newsletter Lists is currently in beta, the API is subject to change.
        </Note>
        Retrieve a single newsletter list subscription.
      operationId: newsletterListSubscriptions_show
      tags:
        - NewsletterListSubscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: newsletterListId
          in: path
          description: The prefixed ID of the newsletter list object
          required: true
          schema:
            $ref: '#/components/schemas/NewsletterListId'
          example: nl_list_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: nl_list_00000000-0000-0000-0000-000000000000
        - name: newsletterListSubscriptionId
          in: path
          description: The prefixed ID of the newsletter list subscription object
          required: true
          schema:
            $ref: '#/components/schemas/NewsletterListSubscriptionId'
          example: nl_list_sub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: nl_list_sub_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterListSubscriptionResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: nl_list_sub_00000000-0000-0000-0000-000000000000
                      newsletter_list_id: nl_list_00000000-0000-0000-0000-000000000000
                      subscription_id: sub_00000000-0000-0000-0000-000000000000
                      status: active
                      subscribed_at: 1672531200
                      unsubscribed_at: null
                      created_at: 1672531200
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get newsletter list subscription <Badge intent="warning" minimal
        outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope:
        newsletter_lists:read</Badge>
      security: *ref_0
    patch:
      description: >-
        <Note title="Currently in beta" icon="b">
          Newsletter Lists is currently in beta, the API is subject to change.
        </Note>

        Update a newsletter list subscription. Currently supports unsubscribing
        a subscription from a newsletter list.
      operationId: newsletterListSubscriptions_update
      tags:
        - NewsletterListSubscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: newsletterListId
          in: path
          description: The prefixed ID of the newsletter list object
          required: true
          schema:
            $ref: '#/components/schemas/NewsletterListId'
          example: nl_list_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: nl_list_00000000-0000-0000-0000-000000000000
        - name: newsletterListSubscriptionId
          in: path
          description: The prefixed ID of the newsletter list subscription object
          required: true
          schema:
            $ref: '#/components/schemas/NewsletterListSubscriptionId'
          example: nl_list_sub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: nl_list_sub_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterListSubscriptionResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: nl_list_sub_00000000-0000-0000-0000-000000000000
                      newsletter_list_id: nl_list_00000000-0000-0000-0000-000000000000
                      subscription_id: sub_00000000-0000-0000-0000-000000000000
                      status: active
                      subscribed_at: 1672531200
                      unsubscribed_at: null
                      created_at: 1672531200
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update newsletter list subscription <Badge intent="warning" minimal
        outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope:
        newsletter_lists:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                unsubscribe:
                  type: boolean
                  nullable: true
                  description: >-
                    Set to true to unsubscribe the subscription from this
                    newsletter list.
            examples:
              Example1:
                value:
                  unsubscribe: true
  /publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions/by_subscription_id/{subscriptionId}:
    patch:
      description: >-
        <Note title="Currently in beta" icon="b">
          Newsletter Lists is currently in beta, the API is subject to change.
        </Note>

        Update a newsletter list subscription by subscription ID. An alternative
        to the update endpoint when you don't have the newsletter list
        subscription ID. Accepts either a subscription_id or email to identify
        the subscription. Currently supports unsubscribing a subscription from a
        newsletter list.
      operationId: newsletterListSubscriptions_update_by_subscription_id
      tags:
        - NewsletterListSubscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: newsletterListId
          in: path
          description: The prefixed ID of the newsletter list object
          required: true
          schema:
            $ref: '#/components/schemas/NewsletterListId'
          example: nl_list_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: nl_list_00000000-0000-0000-0000-000000000000
        - name: subscriptionId
          in: path
          description: The prefixed ID of the subscription
          required: true
          schema:
            $ref: '#/components/schemas/SubscriptionId'
          example: sub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: sub_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterListSubscriptionResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: nl_list_sub_00000000-0000-0000-0000-000000000000
                      newsletter_list_id: nl_list_00000000-0000-0000-0000-000000000000
                      subscription_id: sub_00000000-0000-0000-0000-000000000000
                      status: active
                      subscribed_at: 1672531200
                      unsubscribed_at: null
                      created_at: 1672531200
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update newsletter list subscription by subscription ID <Badge
        intent="warning" minimal outlined>Beta</Badge> <Badge intent="info"
        minimal outlined>OAuth Scope: newsletter_lists:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                unsubscribe:
                  type: boolean
                  nullable: true
                  description: >-
                    Set to true to unsubscribe the subscription from this
                    newsletter list.
            examples:
              Example1:
                value:
                  unsubscribe: true
  /publications/{publicationId}/polls:
    get:
      description: >-
        Retrieve all polls belonging to a specific publication. Poll choices are
        always included. Use `expand[]=stats` to include aggregate vote counts
        per choice.
      operationId: polls_index
      tags:
        - Polls
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Cursor-based pagination:
              value: pub_00000000-0000-0000-0000-000000000000
            With stats expansion:
              value: pub_00000000-0000-0000-0000-000000000000
            Filtered by post:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
          example: 10
          examples:
            Cursor-based pagination:
              value: 10
            With stats expansion:
              value: 10
        - name: cursor
          in: query
          description: >-
            **Cursor-based pagination (recommended)**: Use this opaque cursor
            token to fetch the next page of results. When provided, pagination
            will use cursor-based method which is more efficient and consistent
            than offset-based pagination.
          required: false
          schema:
            type: string
            nullable: true
        - name: page
          in: query
          description: >-
            **Offset-based pagination (deprecated)**: Page number for
            offset-based pagination. Please migrate to cursor-based pagination
            using the `cursor` parameter. If not specified, results 1-10 from
            page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: order_by
          in: query
          description: >-
            The field that the results are sorted by. Defaults to created.<br>
            `created` - The time the poll was created.<br> `name` - The name of
            the poll.
          required: false
          schema:
            $ref: '#/components/schemas/PollOrderBy'
            nullable: true
        - name: direction
          in: query
          description: >-
            The direction that the results are sorted in. Defaults to asc.<br>
            `asc` - Ascending, sorts from smallest to largest.<br> `desc` -
            Descending, sorts from largest to smallest.
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
        - name: expand[]
          in: query
          description: >-
            Optionally expand the response to include additional data.<br>
            `stats` - Returns aggregate vote counts per choice and total
            completions.<br> `poll_responses` - Returns up to 10 most recent
            subscriber responses. Use /polls/{pollId}/responses for paginated
            access to all responses.<br> `trivia_answer` - Returns the correct
            answer for trivia-type polls.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PollsExpandItems'
            nullable: true
          example: &ref_2
            - stats
          examples:
            With stats expansion:
              value: *ref_2
        - name: post_id
          in: query
          description: >-
            Filter to only return polls that were embedded in the specified
            post. Accepts a prefixed post ID (e.g. `post_abc123`).
          required: false
          schema:
            type: string
            nullable: true
          example: post_00000000-0000-0000-0000-000000000000
          examples:
            Filtered by post:
              value: post_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollsListResponse'
              examples:
                Cursor-based pagination:
                  value:
                    data:
                      - id: poll_00000000-0000-0000-0000-000000000000
                        name: Favorite Color
                        question: What is your favorite color?
                        description: Choose an answer from the list below.
                        poll_type: voting
                        status: published
                        created_at: 1666800076
                        poll_choices:
                          - id: 00000000-0000-0000-0000-000000000001
                            label: Red
                          - id: 00000000-0000-0000-0000-000000000002
                            label: Blue
                          - id: 00000000-0000-0000-0000-000000000003
                            label: Green
                    limit: 10
                    has_more: false
                    next_cursor: null
                With stats expansion:
                  value:
                    data:
                      - id: poll_00000000-0000-0000-0000-000000000000
                        name: Favorite Color
                        question: What is your favorite color?
                        description: Choose an answer from the list below.
                        poll_type: voting
                        status: published
                        created_at: 1666800076
                        poll_choices:
                          - id: 00000000-0000-0000-0000-000000000001
                            label: Red
                          - id: 00000000-0000-0000-0000-000000000002
                            label: Blue
                          - id: 00000000-0000-0000-0000-000000000003
                            label: Green
                        stats:
                          completions: 150
                          vote_counts:
                            Red: 75
                            Blue: 50
                            Green: 25
                    limit: 10
                    has_more: false
                    next_cursor: null
                Filtered by post:
                  value:
                    data:
                      - id: poll_00000000-0000-0000-0000-000000000000
                        name: Favorite Color
                        question: What is your favorite color?
                        description: Choose an answer from the list below.
                        poll_type: voting
                        status: published
                        created_at: 1666800076
                        poll_choices:
                          - id: 00000000-0000-0000-0000-000000000001
                            label: Red
                          - id: 00000000-0000-0000-0000-000000000002
                            label: Blue
                          - id: 00000000-0000-0000-0000-000000000003
                            label: Green
                    limit: 10
                    has_more: false
                    next_cursor: null
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List polls <Badge intent="info" minimal outlined>OAuth Scope:
        polls:read</Badge>
      security: *ref_0
  /publications/{publicationId}/polls/{pollId}:
    get:
      description: >-
        Retrieve detailed information about a specific poll belonging to a
        publication. Use `expand[]=stats` for aggregate vote counts, or
        `expand[]=poll_responses` for individual subscriber responses.
      operationId: polls_show
      tags:
        - Polls
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
            With stats and responses:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: pollId
          in: path
          description: The prefixed ID of the poll object
          required: true
          schema:
            $ref: '#/components/schemas/PollId'
          example: poll_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: poll_00000000-0000-0000-0000-000000000000
            With stats and responses:
              value: poll_00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: >-
            Optionally expand the response to include additional data.<br>
            `stats` - Returns aggregate vote counts per choice and total
            completions.<br> `poll_responses` - Returns up to 10 most recent
            subscriber responses. Use /polls/{pollId}/responses for paginated
            access to all responses.<br> `trivia_answer` - Returns the correct
            answer for trivia-type polls.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PollsExpandItems'
            nullable: true
          example: &ref_3
            - stats
            - poll_responses
          examples:
            With stats and responses:
              value: *ref_3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollShowResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: poll_00000000-0000-0000-0000-000000000000
                      name: Favorite Color
                      question: What is your favorite color?
                      description: Choose an answer from the list below.
                      poll_type: voting
                      status: published
                      created_at: 1666800076
                      poll_choices:
                        - id: 00000000-0000-0000-0000-000000000001
                          label: Red
                        - id: 00000000-0000-0000-0000-000000000002
                          label: Blue
                        - id: 00000000-0000-0000-0000-000000000003
                          label: Green
                With stats and responses:
                  value:
                    data:
                      id: poll_00000000-0000-0000-0000-000000000000
                      name: Favorite Color
                      question: What is your favorite color?
                      description: Choose an answer from the list below.
                      poll_type: voting
                      status: published
                      created_at: 1666800076
                      poll_choices:
                        - id: 00000000-0000-0000-0000-000000000001
                          label: Red
                        - id: 00000000-0000-0000-0000-000000000002
                          label: Blue
                        - id: 00000000-0000-0000-0000-000000000003
                          label: Green
                      stats:
                        completions: 150
                        vote_counts:
                          Red: 75
                          Blue: 50
                          Green: 25
                      total_responses: 150
                      poll_responses:
                        - id: 00000000-0000-0000-0000-000000000010
                          subscription_id: sub_00000000-0000-0000-0000-000000000001
                          poll_choice_id: 00000000-0000-0000-0000-000000000001
                          poll_choice_label: Red
                          created_at: 1666800100
                          extended_feedback: I love red!
                        - id: 00000000-0000-0000-0000-000000000011
                          subscription_id: sub_00000000-0000-0000-0000-000000000002
                          poll_choice_id: 00000000-0000-0000-0000-000000000002
                          poll_choice_label: Blue
                          created_at: 1666800200
                          extended_feedback: null
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get poll <Badge intent="info" minimal outlined>OAuth Scope:
        polls:read</Badge>
      security: *ref_0
  /publications/{publicationId}/polls/{pollId}/responses:
    get:
      description: >-
        Retrieve all individual subscriber responses for a specific poll with
        cursor-based pagination. Use this endpoint for large datasets instead of
        the `expand[]=poll_responses` parameter on the poll show endpoint.
      operationId: polls_list_responses
      tags:
        - Polls
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
            With post context expansion:
              value: pub_00000000-0000-0000-0000-000000000000
            Filtered by post:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: pollId
          in: path
          description: The prefixed ID of the poll object
          required: true
          schema:
            $ref: '#/components/schemas/PollId'
          example: poll_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: poll_00000000-0000-0000-0000-000000000000
            With post context expansion:
              value: poll_00000000-0000-0000-0000-000000000000
            Filtered by post:
              value: poll_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
          example: 10
          examples:
            Example1:
              value: 10
        - name: cursor
          in: query
          description: >-
            **Cursor-based pagination (recommended)**: Use this opaque cursor
            token to fetch the next page of results.
          required: false
          schema:
            type: string
            nullable: true
        - name: page
          in: query
          description: >-
            **Offset-based pagination (deprecated)**: Page number for
            offset-based pagination.
          required: false
          schema:
            type: integer
            nullable: true
        - name: order_by
          in: query
          description: The field that the results are sorted by. Defaults to created.
          required: false
          schema:
            $ref: '#/components/schemas/PollResponsesOrderBy'
            nullable: true
        - name: direction
          in: query
          description: >-
            The direction that the results are sorted in. Defaults to asc.<br>
            `asc` - Ascending, sorts from smallest to largest.<br> `desc` -
            Descending, sorts from largest to smallest.
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
        - name: expand[]
          in: query
          description: >-
            Optionally expand the response to include additional data.<br>
            `post` - Returns the post title and publication date for the post
            where each response was collected.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PollResponsesExpandItems'
            nullable: true
          example: &ref_4
            - post
          examples:
            With post context expansion:
              value: *ref_4
        - name: post_id
          in: query
          description: >-
            Filter to only return responses collected via the specified post.
            Accepts a prefixed post ID (e.g. `post_abc123`).
          required: false
          schema:
            type: string
            nullable: true
          example: post_00000000-0000-0000-0000-000000000000
          examples:
            Filtered by post:
              value: post_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollResponsesListResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: 00000000-0000-0000-0000-000000000010
                        subscription_id: sub_00000000-0000-0000-0000-000000000001
                        poll_choice_id: 00000000-0000-0000-0000-000000000001
                        poll_choice_label: Red
                        created_at: 1666800100
                        extended_feedback: I love red!
                      - id: 00000000-0000-0000-0000-000000000011
                        subscription_id: sub_00000000-0000-0000-0000-000000000002
                        poll_choice_id: 00000000-0000-0000-0000-000000000002
                        poll_choice_label: Blue
                        created_at: 1666800200
                        extended_feedback: null
                    limit: 10
                    has_more: true
                    next_cursor: >-
                      eyJ0aW1lc3RhbXAiOiIyMDI0LTA3LTAyVDE3OjMwOjAwLjAwMDAwMFoifQ==
                With post context expansion:
                  value:
                    data:
                      - id: 00000000-0000-0000-0000-000000000010
                        subscription_id: sub_00000000-0000-0000-0000-000000000001
                        poll_choice_id: 00000000-0000-0000-0000-000000000001
                        poll_choice_label: Red
                        created_at: 1666800100
                        extended_feedback: I love red!
                        post_id: post_00000000-0000-0000-0000-000000000000
                        post_title: July 4th Edition
                        post_publish_date: 1666800000
                    limit: 10
                    has_more: false
                    next_cursor: null
                Filtered by post:
                  value:
                    data:
                      - id: 00000000-0000-0000-0000-000000000010
                        subscription_id: sub_00000000-0000-0000-0000-000000000001
                        poll_choice_id: 00000000-0000-0000-0000-000000000001
                        poll_choice_label: Red
                        created_at: 1666800100
                        extended_feedback: I love red!
                    limit: 10
                    has_more: false
                    next_cursor: null
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List poll responses <Badge intent="info" minimal outlined>OAuth Scope:
        polls:read</Badge>
      security: *ref_0
  /publications/{publicationId}/posts:
    post:
      description: >-
        <Note title="Currently in beta" icon="b">
          This feature is currently in beta, the API is subject to change, and available only to Enterprise users.<br/><br/>To inquire about Enterprise pricing,
          please visit our <a href="https://www.beehiiv.com/enterprise">Enterprise page</a>.
        </Note>

        Create a post for a specific publication. For a detailed walkthrough
        including setup, testing workflows, and working with custom HTML and
        templates, see the <a
        href="https://www.beehiiv.com/support/article/36759164012439-using-the-send-api-and-create-post-endpoint">Using
        the Send API and Create Post Endpoint</a> guide.


        ## Content methods


        There are three ways to provide content for a post. You must provide
        either `blocks` or `body_content`, but not both.


        ### 1. Blocks


        Use the `blocks` field to build your post with structured content blocks
        such as paragraphs, images, headings, buttons, tables, and more. Each
        block has a `type` and its own set of properties. This method gives you
        fine-grained control over individual content elements and supports
        features like visual settings, visibility settings, and dynamic content
        targeting.


        ### 2. Raw HTML (`body_content`)


        Use the `body_content` field to provide a single string of raw HTML. The
        HTML is wrapped in an `htmlSnippet` block internally. This is useful
        when you have pre-built HTML content or are migrating from another
        platform.


        ### 3. HTML blocks within blocks


        Use `type: html` blocks inside the `blocks` array to embed raw HTML
        snippets alongside other structured blocks. This lets you mix structured
        content (paragraphs, images, etc.) with custom HTML where needed.


        ## CSS and styling guardrails


        beehiiv processes all HTML content through a sanitization pipeline. When
        using `body_content` or `html` blocks, be aware of the following:


        - **`<style>` tags are removed.** All `<style>` block elements are
        stripped during sanitization. Do not rely on embedded stylesheets.

        - **`<link>` tags are removed.** External stylesheet references are not
        allowed.

        - **Inline styles are preserved.** Styles applied directly to elements
        via the `style` attribute (e.g., `<div style="color: red;">`) are kept
        intact.

        - **CSS classes have no effect.** While class attributes are not
        stripped, no corresponding stylesheets are loaded to apply them.

        - **beehiiv's email template wraps your content.** Your HTML is rendered
        inside beehiiv's email table structure, which applies its own layout and
        spacing. This may affect the appearance of your content.

        - **Use inline styles for all visual styling.** Since `<style>` and
        `<link>` tags are removed, inline styles on individual elements are the
        only reliable way to control appearance.
      operationId: posts_create
      tags:
        - Posts
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostsCreateResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: post_00000000-0000-0000-0000-000000000000
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Create post <Badge intent="info" minimal outlined>OAuth Scope:
        posts:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                blocks:
                  type: array
                  items:
                    $ref: '#/components/schemas/Block'
                  nullable: true
                  description: >-
                    The structured content blocks that make up the post.
                    Supports block types such as paragraph, image, heading,
                    button, html, table, list, columns, and more. You can embed
                    raw HTML snippets within blocks using the `html` block type.
                    Either this field OR the `body_content` field must be
                    provided.
                body_content:
                  type: string
                  nullable: true
                  description: >-
                    The content of the post as a single raw HTML string. The
                    HTML is wrapped in an `htmlSnippet` block internally. Note
                    that `<style>` and `<link>` tags are removed during
                    sanitization — use inline styles for all visual styling.
                    Either this field OR the `blocks` field must be provided.
                title:
                  type: string
                  description: The title of the post.
                  example: The Kitchen Sink Post (refactored version)
                subtitle:
                  type: string
                  nullable: true
                  description: The subtitle of the post.
                post_template_id:
                  $ref: '#/components/schemas/PostTemplateId'
                  nullable: true
                  description: >-
                    The ID of the template to use for the post. If not provided,
                    the default template will be used.
                status:
                  $ref: '#/components/schemas/PostPublishStatus'
                  nullable: true
                  description: >-
                    The status of the post. If not provided, the default
                    (`confirmed`) value will be used and the post will either
                    publish immediately (if no `scheduled_at` is provided) or at
                    the `scheduled_at` time.
                scheduled_at:
                  type: string
                  format: date-time
                  nullable: true
                  description: >-
                    The time in which the post will be published. If not
                    provided, the post will be published immediately unless
                    `status` is set to `draft`. A draft post cannot be
                    scheduled.
                custom_link_tracking_enabled:
                  type: boolean
                  nullable: true
                  description: >-
                    If true, custom link tracking will be enabled for this post.
                    If not provided, the default value will be used.
                email_capture_type_override:
                  $ref: '#/components/schemas/PostEmailCaptureTypeOverride'
                  nullable: true
                  description: >-
                    The email capture type to use for this post. If not
                    provided, the default value will be used.
                override_scheduled_at:
                  type: string
                  format: date-time
                  nullable: true
                  description: >-
                    If you wish to display a date other than the scheduled_at
                    date in the email, you can provide a date here. This will
                    not affect the actual publish date of the post.
                social_share:
                  $ref: '#/components/schemas/PostSocialShare'
                  nullable: true
                  description: >-
                    The social share type to use for this post. If not provided,
                    the default value will be used.
                thumbnail_image_url:
                  type: string
                  nullable: true
                  description: >-
                    The URL of the thumbnail image to use for the post. If not
                    provided, the default value will be used.
                recipients:
                  $ref: '#/components/schemas/PostRecipients'
                  nullable: true
                  description: >-
                    The recipients to use for this post. If not provided, the
                    default value will be used.
                email_settings:
                  $ref: '#/components/schemas/PostEmailSettings'
                  nullable: true
                  description: >-
                    The email settings to use for this post. If not provided,
                    the default value will be used.
                web_settings:
                  $ref: '#/components/schemas/PostWebSettings'
                  nullable: true
                  description: >-
                    The web settings to use for this post. If not provided, the
                    default value will be used.
                seo_settings:
                  $ref: '#/components/schemas/PostMetadata'
                  nullable: true
                  description: >-
                    The metadata to use for this post. If not provided, the
                    default value will be used.
                content_tags:
                  type: array
                  items:
                    type: string
                  nullable: true
                  description: >-
                    The content tags to use for this post. If not provided, the
                    default value will be used.
                headers:
                  type: object
                  additionalProperties:
                    type: string
                  nullable: true
                  description: >-
                    The headers to use for this post. If not provided, the
                    default value will be used.
                custom_fields:
                  type: object
                  additionalProperties:
                    type: string
                  nullable: true
                  description: >-
                    The custom fields to use for this post. If not provided, the
                    default value will be used.
                newsletter_list_id:
                  type: string
                  nullable: true
                  description: >-
                    The prefixed ID of the newsletter list to associate with
                    this post. When provided, the post will only be sent to
                    subscribers of this list. <Badge intent="warning" minimal
                    outlined>Beta</Badge>
              required:
                - title
            examples:
              Example1:
                value:
                  title: The Kitchen Sink Post (refactored version)
                  subtitle: >-
                    Contains lots of examples of each block type and the various
                    settings you could use
                  blocks:
                    - type: heading
                      level: '2'
                      textAlignment: center
                      text: This is my block!!!
                      anchorHeader: false
                      anchorIncludeInToc: false
                    - type: list
                      listType: ordered
                      items:
                        - a
                        - b
                        - c
                    - type: list
                      listType: ordered
                      items:
                        - d
                        - e
                        - f
                      startNumber: 4
                    - type: list
                      listType: unordered
                      items:
                        - g
                        - h
                        - i
                      startNumber: 4
                    - type: table
                      headerRow: true
                      headerColumn: true
                      rows:
                        - - text: A
                          - text: B
                            alignment: center
                          - text: C
                            alignment: right
                        - - text: D
                            alignment: right
                          - text: E
                            alignment: center
                          - text: F
                            alignment: left
                    - type: table
                      rows:
                        - - text: A
                          - text: B
                          - text: C
                        - - text: D
                          - text: E
                          - text: F
                    - type: table
                      headerRow: false
                      rows:
                        - - text: A
                          - text: B
                          - text: C
                        - - text: D
                          - text: E
                          - text: F
                    - type: columns
                      columns:
                        - blocks:
                            - type: paragraph
                              plaintext: Marble Column 1 {{email}}
                        - blocks:
                            - type: image
                              imageUrl: >-
                                https://cdn.britannica.com/89/164789-050-D6B5E2C7/Barack-Obama-2012.jpg
                              url: https://www.whitehouse.gov/
                              title: Barry O
                              alt_text: A picture of Barry Obama
                              caption: One Cool President
                              captionAlignment: center
                              imageAlignment: right
                              width: 75
                    - type: advertisement
                      opportunity_id: d8dfa6be-24b5-4cad-8350-ae44366dbd4c
                    - type: image
                      imageUrl: >-
                        https://cdn.britannica.com/89/164789-050-D6B5E2C7/Barack-Obama-2012.jpg
                      url: https://www.whitehouse.gov/
                      title: Barry O
                      alt_text: A picture of Barry Obama
                      caption: One Cool President
                      captionAlignment: center
                      imageAlignment: right
                      width: 75
                    - type: paragraph
                      formattedText:
                        - text: 'This is going to be '
                        - text: 'a really, really awesome time '
                          styling:
                            - bold
                        - text: Are you ready for this?
                          styling:
                            - italic
                            - bold
                    - type: button
                      href: /subscribe
                      target: _blank
                      alignment: center
                      size: large
                      text: Subscribe
                    - type: button
                      href: /signup
                      target: _blank
                      alignment: right
                      size: small
                      text: Sign Up
                    - type: button
                      href: /
                      target: _blank
                      text: View Posts
                    - type: heading
                      level: '4'
                      textAlignment: right
                      text: This is my block!!!
                      anchorHeader: true
                      anchorIncludeInToc: true
                  post_template_id: post_template_00000000-0000-0000-0000-000000000000
                  scheduled_at: '2024-12-25T12:00:00Z'
                  custom_link_tracking_enabled: true
                  email_capture_type_override: none
                  override_scheduled_at: '2022-10-26T14:01:16Z'
                  social_share: comments_and_likes_only
                  thumbnail_image_url: >-
                    https://images.squarespace-cdn.com/content/v1/56e4ca0540261d39b90e4b18/1605047208324-PONGEYKEAKTMM1LANHJ5/1ED706BF-A70B-4F26-B3D5-266B449DDA8A_1_105_c.jpeg
                  email_settings:
                    from_address: from_address
                    custom_live_url: https://beehiiv.com
                    display_title_in_email: true
                    display_byline_in_email: true
                    display_subtitle_in_email: true
                    email_header_engagement_buttons: email_header_engagement_buttons
                    email_header_social_share: email_header_social_share
                    email_preview_text: email_preview_text
                    email_subject_line: email_subject_line
                  web_settings:
                    display_thumbnail_on_web: true
                    hide_from_feed: true
                    slug: and-this-is-gonna-rock
                  seo_settings:
                    default_description: default_description
                    default_title: default_title
                    og_description: OpenGraph description
                    og_title: Opengraph Title
                    twitter_description: Twitter Stuff
                    twitter_title: My Twitter Article
                  content_tags:
                    - Obama
                    - Care
                    - Rocks
                    - Healthcare
                  recipients:
                    web:
                      tier_ids:
                        - premium
                    email:
                      tier_ids:
                        - premium
                        - free
                      include_segment_ids:
                        - seg_6426b403-39f5-42bd-86e9-9533fb0099e7
                      exclude_segment_ids:
                        - seg_e34b4085-aef6-449f-a699-7563f915f852
    get:
      description: Retrieve all posts belonging to a specific publication
      operationId: posts_index
      tags:
        - Posts
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: expand
          in: query
          description: >-
            Optionally expand the results by adding additional information.
            <br>`stats` - Adds statistics about the post(s).
            <br>`free_web_content` - Adds the web HTML rendered to a free
            reader. <br>`free_email_content` - Adds the email HTML rendered to a
            free reader. <br>`free_rss_content` - Adds the RSS feed HTML.
            <br>`premium_web_content` - Adds the web HTML rendered to a premium
            reader. <br>`premium_email_content` - Adds the email HTML rendered
            to a premium reader.
          required: false
          schema:
            type: array
            items:
              type: array
              items:
                $ref: '#/components/schemas/PostExpandField'
              nullable: true
        - name: audience
          in: query
          description: Optionally filter the results by audience
          required: false
          schema:
            $ref: '#/components/schemas/PostAudienceFilter'
            nullable: true
        - name: platform
          in: query
          description: >-
            Optionally filter the results by platform.<br>`web` - Posts only
            published to web.<br>`email` - Posts only published to
            email.<br>`both` - Posts published to email and web.<br>`all` - Does
            not restrict results by platform.
          required: false
          schema:
            $ref: '#/components/schemas/PostPlatformFilter'
            nullable: true
        - name: status
          in: query
          description: >-
            Optionally filter the results by the status of the post.<br>`draft`
            - not been scheduled.<br>`confirmed` - The post will be active after
            the `scheduled_at`.<br>`archived` - The post is no longer
            active.<br>`all` - Does not restrict results by status.
          required: false
          schema:
            $ref: '#/components/schemas/PostStatusFilter'
            nullable: true
        - name: content_tags[]
          in: query
          description: >-
            Optionally filter posts by content_tags. Adding a content tag will
            return any post with that content tag associated to
            it.<br><br><b>Example</b>: Filtering for `content_tags:
            ["sales","closing"]` will return results of posts that have *either*
            `sales` or `closing` content_tags.
          required: false
          schema:
            type: array
            items:
              type: string
            nullable: true
        - name: slugs[]
          in: query
          description: >-
            Optionally filter posts by their slugs. Adding a slug will return
            any post with that exact slug associated to
            it.<br><br><b>Example:</b> Filtering for `slugs:
            ["my-first-post","another-post"]` will return results of posts that
            have *either* `my-first-post` or `another-post` as their slug.
          required: false
          schema:
            type: array
            items:
              type: string
            nullable: true
        - name: authors[]
          in: query
          description: >-
            Optionally filter posts by their authors. Adding an author name will
            return any post with that author associated to it
            (case-insensitive).<br><br><b>Example:</b> Filtering for `authors:
            ["John Doe","Jane Smith"]` will return results of posts that have
            *either* John Doe or Jane Smith as authors.
          required: false
          schema:
            type: array
            items:
              type: string
            nullable: true
        - name: premium_tiers
          in: query
          description: >-
            Optionally filter posts by audience based on premium tiers.<br> This
            takes in an array of Display Names of the premium tiers.<br> It will
            also scope any expanded content output to the specified premium
            tiers.<br> Note: This is case insensitive.
          required: false
          schema:
            type: array
            items:
              type: string
            nullable: true
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).<br>If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: order_by
          in: query
          description: >-
            The field that the results are sorted by. Defaults to created<br>
            `created` - The time in which the post was first created.<br>
            `publish_date` - The time the post was set to be published.<br>
            `displayed_date` - The time displayed in place of the
            `publish_date`. If no `displayed_date` was set, it will default to
            the `publish_date`
          required: false
          schema:
            $ref: '#/components/schemas/PostOrderBy'
            nullable: true
        - name: direction
          in: query
          description: >-
            The direction that the results are sorted in. Defaults to asc<br>
            `asc` - Ascending, sorts from smallest to largest.<br> `desc` -
            Descending, sorts from largest to smallest.
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
        - name: hidden_from_feed
          in: query
          description: >-
            Optionally filter the results by the `hidden_from_feed` attribute of
            the post.<br>`all` - Does not restrict results by
            `hidden_from_feed`.<br>`true` - Only return posts hidden from the
            feed.<br>`false` - Only return posts that are visible on the feed.
          required: false
          schema:
            $ref: '#/components/schemas/PostsListRequestHiddenFromFeed'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostsListResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: post_00000000-0000-0000-0000-000000000000
                        subtitle: New post subtitle
                        title: New Post Title
                        authors:
                          - Clark Kent
                        created: 1666800076
                        status: draft
                        publish_date: 1666800076
                        displayed_date: 1666800076
                        split_tested: true
                        subject_line: Check this out
                        preview_text: More news on the horizon
                        slug: slug
                        thumbnail_url: thumbnail_url
                        web_url: web_url
                        audience: free
                        platform: web
                        content_tags:
                          - content_tags
                        meta_default_description: A post with great content
                        meta_default_title: My great post
                        newsletter_list_id: nl_list_00000000-0000-0000-0000-000000000000
                        hidden_from_feed: true
                        enforce_gated_content: false
                        email_capture_popup: false
                        content:
                          free:
                            web: <HTML><body><h1>New Post</h1></body></HTML>
                            email: <HTML><body><h1>New Post</h1></body></HTML>
                            rss: <HTML><body><h1>New Post</h1></body></HTML>
                          premium:
                            web: <HTML><body><h1>New Post</h1></body></HTML>
                            email: <HTML><body><h1>New Post</h1></body></HTML>
                        stats:
                          email:
                            recipients: 100
                            delivered: 100
                            opens: 50
                            unique_opens: 45
                            open_rate: 45
                            clicks: 10
                            unique_clicks: 8
                            verified_clicks: 9
                            unique_verified_clicks: 7
                            click_rate: 8
                            unsubscribes: 1
                            spam_reports: 1
                          web:
                            views: 200
                            clicks: 40
                          clicks:
                            - url: https://www.google.com
                              base_url: https://www.google.com
                              email:
                                clicks: 10
                                unique_clicks: 8
                                verified_clicks: 9
                                unique_verified_clicks: 7
                                click_through_rate: 80
                              web:
                                clicks: 40
                                unique_clicks: 40
                                click_through_rate: 20
                              total_clicks: 50
                              total_unique_clicks: 48
                              total_click_through_rate: 40
                    limit: 1
                    page: 1
                    total_results: 1
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List posts <Badge intent="info" minimal outlined>OAuth Scope:
        posts:read</Badge>
      security: *ref_0
  /publications/{publicationId}/posts/aggregate_stats:
    get:
      description: Retrieve aggregate stats for all posts
      operationId: posts_aggregate_stats
      tags:
        - Posts
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: audience
          in: query
          description: Optionally filter the results by audience
          required: false
          schema:
            $ref: '#/components/schemas/PostAudienceFilter'
            nullable: true
        - name: platform
          in: query
          description: >-
            Optionally filter the results by platform.<br>`web` - Posts only
            published to web.<br>`email` - Posts only published to
            email.<br>`both` - Posts published to email and web.<br>`all` - Does
            not restrict results by platform.
          required: false
          schema:
            $ref: '#/components/schemas/PostPlatformFilter'
            nullable: true
        - name: status
          in: query
          description: >-
            Optionally filter the results by the status of the post.<br>`draft`
            - not been scheduled.<br>`confirmed` - The post will be active after
            the `scheduled_at`.<br>`archived` - The post is no longer
            active.<br>`all` - Does not restrict results by status.
          required: false
          schema:
            $ref: '#/components/schemas/PostStatusFilter'
            nullable: true
        - name: content_tags[]
          in: query
          description: >-
            Optionally filter posts by content_tags. Adding a content tag will
            return any post with that content tag associated to it.<br>Example:
            Filtering for `content_tags: ["sales","closing"]` will return
            results of posts that have *either* sales or closing content_tags.
          required: false
          schema:
            type: array
            items:
              type: string
            nullable: true
        - name: authors[]
          in: query
          description: >-
            Optionally filter posts by their authors. Adding an author name will
            return any post with that author associated to it
            (case-insensitive).<br><br><b>Example:</b> Filtering for `authors:
            ["John Doe","Jane Smith"]` will return results of posts that have
            *either* John Doe or Jane Smith as authors.
          required: false
          schema:
            type: array
            items:
              type: string
            nullable: true
        - name: hidden_from_feed
          in: query
          description: >-
            Optionally filter the results by the `hidden_from_feed` attribute of
            the post.<br>`all` - Does not restrict results by
            `hidden_from_feed`.<br>`true` - Only return posts hidden from the
            feed.<br>`false` - Only return posts that are visible on the feed.
          required: false
          schema:
            $ref: '#/components/schemas/PostsListRequestHiddenFromFeed'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostsAggregateStatsResponse'
              examples:
                Example1:
                  value:
                    data:
                      stats:
                        email:
                          recipients: 100
                          delivered: 100
                          opens: 50
                          unique_opens: 45
                          open_rate: 45
                          clicks: 10
                          unique_clicks: 8
                          verified_clicks: 9
                          unique_verified_clicks: 7
                          click_rate: 8
                          unsubscribes: 1
                          spam_reports: 1
                        web:
                          views: 200
                          clicks: 40
                        clicks:
                          - url: https://www.google.com
                            base_url: https://www.google.com
                            email:
                              clicks: 10
                              unique_clicks: 8
                              verified_clicks: 9
                              unique_verified_clicks: 7
                              click_through_rate: 80
                            web:
                              clicks: 40
                              unique_clicks: 40
                              click_through_rate: 20
                            total_clicks: 50
                            total_unique_clicks: 48
                            total_click_through_rate: 40
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get aggregate stats <Badge intent="info" minimal outlined>OAuth Scope:
        posts:read</Badge>
      security: *ref_0
  /publications/{publicationId}/posts/{postId}:
    get:
      description: Retrieve a single Post belonging to a specific publication
      operationId: posts_show
      tags:
        - Posts
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: postId
          in: path
          description: The prefixed ID of the post object
          required: true
          schema:
            $ref: '#/components/schemas/PostId'
          example: post_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: post_00000000-0000-0000-0000-000000000000
        - name: expand
          in: query
          description: >-
            Optionally expand the results by adding additional information.
            <br>`stats` - Adds statistics about the post(s).
            <br>`free_web_content` - Adds the web HTML rendered to a free
            reader. <br>`free_email_content` - Adds the email HTML rendered to a
            free reader. <br>`free_rss_content` - Adds the RSS feed HTML.
            <br>`premium_web_content` - Adds the web HTML rendered to a premium
            reader. <br>`premium_email_content` - Adds the email HTML rendered
            to a premium reader.
          required: false
          schema:
            type: array
            items:
              type: array
              items:
                $ref: '#/components/schemas/PostExpandField'
              nullable: true
        - name: premium_tiers
          in: query
          description: >-
            Scope any expanded content output to the specified premium
            tiers.<br> This takes in an array of Display Names of the premium
            tiers.<br> Note: This is case insensitive.
          required: false
          schema:
            type: array
            items:
              type: string
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostsGetResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: post_00000000-0000-0000-0000-000000000000
                      subtitle: New post subtitle
                      title: New Post Title
                      authors:
                        - Clark Kent
                      created: 1666800076
                      status: draft
                      publish_date: 1666800076
                      displayed_date: 1666800076
                      split_tested: true
                      subject_line: Check this out
                      preview_text: More news on the horizon
                      slug: slug
                      thumbnail_url: thumbnail_url
                      web_url: web_url
                      audience: free
                      platform: web
                      content_tags:
                        - content_tags
                      meta_default_description: A post with great content
                      meta_default_title: My great post
                      newsletter_list_id: nl_list_00000000-0000-0000-0000-000000000000
                      hidden_from_feed: false
                      enforce_gated_content: false
                      email_capture_popup: false
                      content:
                        free:
                          web: <HTML><body><h1>New Post</h1></body></HTML>
                          email: <HTML><body><h1>New Post</h1></body></HTML>
                          rss: <HTML><body><h1>New Post</h1></body></HTML>
                        premium:
                          web: <HTML><body><h1>New Post</h1></body></HTML>
                          email: <HTML><body><h1>New Post</h1></body></HTML>
                      stats:
                        email:
                          recipients: 100
                          delivered: 100
                          opens: 50
                          unique_opens: 45
                          clicks: 10
                          unique_clicks: 8
                          unsubscribes: 1
                          spam_reports: 1
                        web:
                          views: 200
                          clicks: 40
                        clicks:
                          - total_clicks: 10
                            total_unique_clicks: 8
                            total_click_through_rate: 30
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get post <Badge intent="info" minimal outlined>OAuth Scope:
        posts:read</Badge>
      security: *ref_0
    delete:
      description: >-
        Delete or Archive a post. Any post that has been confirmed will have
        it's status changed to `archived`. Posts in the `draft` status will be
        permanently deleted.
      operationId: posts_delete
      tags:
        - Posts
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: postId
          in: path
          description: The prefixed ID of the post object
          required: true
          schema:
            $ref: '#/components/schemas/PostId'
          example: post_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: post_00000000-0000-0000-0000-000000000000
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostsDeleteResponse'
              examples:
                Example1:
                  value: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Delete post <Badge intent="info" minimal outlined>OAuth Scope:
        posts:write</Badge>
      security: *ref_0
  /publications/{publicationId}/post_templates:
    get:
      description: Retrieve a list of post templates available for the publication.
      operationId: postTemplates_index
      tags:
        - PostTemplates
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).<br>If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: order
          in: query
          description: The direction of the request. Defaults to `asc`.
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
        - name: order_by
          in: query
          description: The field to order by. Defaults to `created`.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostTemplatesGetResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: post_template_00000000-0000-0000-0000-000000000000
                        name: Newsletter Template
                      - id: post_template_11111111-1111-1111-1111-111111111111
                        name: Blog Post Template
                    limit: 10
                    page: 1
                    total_results: 2
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get post templates
      security: *ref_0
  /publications:
    get:
      description: Retrieve all publications associated with your API key.
      operationId: publications_index
      tags:
        - Publications
      parameters:
        - name: expand
          in: query
          description: >-
            Optionally expand the results by adding additional information like
            subscription counts and engagement stats.
          required: false
          schema:
            type: array
            items:
              type: array
              items:
                $ref: '#/components/schemas/PublicationsRequestExpandItem'
              nullable: true
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).<br>If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: direction
          in: query
          description: >-
            The direction that the results are sorted in. Defaults to asc<br>
            `asc` - Ascending, sorts from smallest to largest.<br> `desc` -
            Descending, sorts from largest to smallest.
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
        - name: order_by
          in: query
          description: >-
            The field that the results are sorted by. Defaults to created<br>
            `created` - The time in which the publication was first created.<br>
            `name` - The name of the publication.
          required: false
          schema:
            $ref: '#/components/schemas/PublicationsListRequestOrderBy'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicationsListResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: pub_ad76629e-4a39-43ad-8055-0ee89dc6db15
                        name: Bee Informed
                        organization_name: Barry's Hiiv
                        referral_program_enabled: true
                        created: 1715698529
                        stats:
                          active_subscriptions: 12
                          active_premium_subscriptions: 2
                          active_free_subscriptions: 10
                          average_open_rate: 0.8
                          average_click_rate: 0.45
                          total_sent: 12
                          total_unique_opened: 9
                          total_clicked: 6
                    page: 1
                    limit: 10
                    total_results: 1
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List publications <Badge intent="info" minimal outlined>OAuth Scope:
        publications:read</Badge>
      security: *ref_0
  /publications/{publicationId}:
    get:
      description: Retrieve a single publication
      operationId: publications_show
      tags:
        - Publications
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_ad76629e-4a39-43ad-8055-0ee89dc6db15
          examples:
            Example1:
              value: pub_ad76629e-4a39-43ad-8055-0ee89dc6db15
        - name: expand
          in: query
          description: >-
            Optionally expand the results by adding additional information like
            subscription counts and engagement stats.
          required: false
          schema:
            type: array
            items:
              type: array
              items:
                $ref: '#/components/schemas/PublicationsGetRequestExpandItem'
              nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicationsGetResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: pub_ad76629e-4a39-43ad-8055-0ee89dc6db15
                      name: Bee Informed
                      organization_name: Barry's Hiiv
                      referral_program_enabled: true
                      created: 1715698529
                      stats:
                        active_subscriptions: 12
                        active_premium_subscriptions: 2
                        active_free_subscriptions: 10
                        average_open_rate: 0.8
                        average_click_rate: 0.45
                        total_sent: 12
                        total_unique_opened: 9
                        total_clicked: 6
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get publication <Badge intent="info" minimal outlined>OAuth Scope:
        publications:read</Badge>
      security: *ref_0
  /publications/{publicationId}/referral_program:
    get:
      description: >-
        Retrieve details about the publication's referral program, including
        milestones and rewards.
      operationId: referralProgram_show
      tags:
        - ReferralProgram
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).<br>If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralProgramGetResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: mile_00000000-0000-0000-0000-000000000000
                        auto_fulfill: true
                        num_referrals: 1
                        reward:
                          id: rew_00000000-0000-0000-0000-000000000000
                          name: name
                          description: description
                          image_url: image_url
                          type: physical
                    limit: 1
                    page: 1
                    total_results: 1
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get referral program <Badge intent="info" minimal outlined>OAuth Scope:
        referral_program:read</Badge>
      security: *ref_0
  /publications/{publicationId}/segments:
    post:
      description: >-
        Create a new segment.<br><br> **Manual segments** — Use `subscriptions`
        or `emails` input to create a segment from an explicit list of
        subscription IDs or email addresses. The segment is processed
        synchronously and returns with `status: completed`. Net new email
        addresses will be ignored; create subscriptions using the `Create
        Subscription` endpoint.<br><br> **Dynamic segments** — Use
        `custom_fields` input to create a segment that filters subscribers by
        custom field values. The segment is processed asynchronously and returns
        with `status: pending`. Results will be available in the `List Segment
        Subscribers` endpoint after processing is complete.
      operationId: segments_create
      tags:
        - Segments
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Create from subscription IDs:
              value: pub_00000000-0000-0000-0000-000000000000
            Create from custom field filters:
              value: pub_00000000-0000-0000-0000-000000000000
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentShowResponse'
              examples:
                Create from subscription IDs:
                  value:
                    data:
                      id: seg_00000000-0000-0000-0000-000000000000
                      name: My Segment
                      type: manual
                      last_calculated: 1666800076
                      total_results: 2
                      status: completed
                      active: true
                Create from custom field filters:
                  value:
                    data:
                      id: seg_00000000-0000-0000-0000-000000000000
                      name: Newsletter X Subscribers
                      type: dynamic
                      status: pending
                      total_results: 0
                      active: true
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Create segment
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: >-
                    A unique name for the segment that does not already exist in
                    the publication.
                  example: My Segment
                input:
                  $ref: '#/components/schemas/SegmentSubscriptionInput'
              required:
                - name
                - input
            examples:
              Create from subscription IDs:
                value:
                  name: My Segment
                  input:
                    type: subscriptions
                    subscriptions:
                      - sub_00000000-0000-0000-0000-000000000000
                      - sub_00000000-1111-1111-1111-111111111111
              Create from custom field filters:
                value:
                  name: Newsletter X Subscribers
                  input:
                    type: custom_fields
                    operator: and
                    custom_fields:
                      - name: Newsletter X
                        operator: equal
                        value: 'true'
    get:
      description: >-
        Retrieve information about all segments belonging to a specific
        publication
      operationId: segments_index
      tags:
        - Segments
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: type
          in: query
          description: Optionally filter the results by the segment's type.
          required: false
          schema:
            $ref: '#/components/schemas/SegmentType'
            nullable: true
        - name: status
          in: query
          description: Optionally filter the results by the segment's status.
          required: false
          schema:
            $ref: '#/components/schemas/SegmentRequestStatus'
            nullable: true
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).<br>If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: order_by
          in: query
          description: >-
            The field that the results are sorted by. Defaults to created<br>
            `created` - The time in which the segment was first created.<br>
            `last_calculated` - The time that the segment last completed
            calculation. Measured in seconds since the Unix epoch.
          required: false
          schema:
            $ref: '#/components/schemas/SegmentOrderBy'
            nullable: true
        - name: direction
          in: query
          description: >-
            The direction that the results are sorted in. Defaults to asc<br>
            `asc` - Ascending, sorts from smallest to largest.<br> `desc` -
            Descending, sorts from largest to smallest.
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
        - name: expand[]
          in: query
          description: >-
            Optionally expand the response to include additional data. <br>
            `stats` - Requests the most recently calculated statistics for a
            segment. <br> Segment stats are recalculated once daily around 7
            a.m. UTC for dynamic segments, but can be manually recalculated at
            any time in the dashboard. Manual and static segments only calculate
            once upon upload or creation.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SegmentsExpandItems'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentsListResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: seg_00000000-0000-0000-0000-000000000000
                        name: name
                        type: dynamic
                        last_calculated: 1666800076
                        total_results: 15
                        status: pending
                        active: true
                        stats:
                          open_rate: 0.5
                          total_sent: 100
                          percentage_premium_subscribers: 0.2
                          percentage_subscribers_with_referrals: 0.1
                          unique_emails_clicked: 10
                          total_delivered: 100
                          total_referrals: 10
                          unsubscribed_rate: 0.05
                          total_subscribers: 100
                          clickthrough_rate: 0.5
                          unsubscribed_count: 5
                          unique_emails_opened: 10
                          premium_subscribers: 20
                          average_referrals_per_subscriber: 0.1
                    limit: 1
                    page: 1
                    total_results: 1
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List segments <Badge intent="info" minimal outlined>OAuth Scope:
        segments:read</Badge>
      security: *ref_0
  /publications/{publicationId}/segments/{segmentId}:
    get:
      description: Retrieve information about a specific segment belonging to a publication
      operationId: segments_show
      tags:
        - Segments
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: segmentId
          in: path
          description: The prefixed ID of the segment object
          required: true
          schema:
            $ref: '#/components/schemas/SegmentId'
          example: seg_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: seg_00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: >-
            Optionally expand the response to include additional data. <br>
            `stats` - Requests the most recently calculated statistics for a
            segment. <br> Segment stats are recalculated once daily around 7
            a.m. UTC for dynamic segments, but can be manually recalculated at
            any time in the dashboard. Manual and static segments only calculate
            once upon upload or creation.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SegmentsExpandItems'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentShowResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: seg_00000000-0000-0000-0000-000000000000
                      name: My Segment
                      type: dynamic
                      last_calculated: 1666800076
                      total_results: 15
                      status: completed
                      active: true
                      stats:
                        open_rate: 0.5
                        total_sent: 100
                        percentage_premium_subscribers: 0.2
                        percentage_subscribers_with_referrals: 0.1
                        unique_emails_clicked: 10
                        total_delivered: 100
                        total_referrals: 10
                        unsubscribed_rate: 0.05
                        total_subscribers: 100
                        clickthrough_rate: 0.5
                        unsubscribed_count: 5
                        unique_emails_opened: 10
                        premium_subscribers: 20
                        average_referrals_per_subscriber: 0.1
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get segment <Badge intent="info" minimal outlined>OAuth Scope:
        segments:read</Badge>
      security: *ref_0
    delete:
      description: >-
        Delete a segment. Deleting the segment does not effect the subscriptions
        in the segment.
      operationId: segments_delete
      tags:
        - Segments
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: segmentId
          in: path
          description: The prefixed ID of the segment object
          required: true
          schema:
            $ref: '#/components/schemas/SegmentId'
          example: seg_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: seg_00000000-0000-0000-0000-000000000000
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentDeleteResponse'
              examples:
                Example1:
                  value: {}
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Delete segment <Badge intent="info" minimal outlined>OAuth Scope:
        segments:write</Badge>
      security: *ref_0
  /publications/{publicationId}/segments/{segmentId}/recalculate:
    put:
      description: Recalculates a specific segment belonging to a publication
      operationId: segments_recalculate
      tags:
        - Segments
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: segmentId
          in: path
          description: The prefixed ID of the segment object
          required: true
          schema:
            $ref: '#/components/schemas/SegmentId'
          example: seg_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: seg_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentRecalculateResponse'
              examples:
                Example1:
                  value: {}
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Recalculate segment <Badge intent="info" minimal outlined>OAuth Scope:
        segments:write</Badge>
      security: *ref_0
  /publications/{publicationId}/segments/{segmentId}/members:
    get:
      description: >-
        List all members in a segment with full subscription data. Each member
        is returned as a subscription  object containing complete subscriber
        information and their subscription details.  Supports optional
        expansions for stats, custom fields, tags, referrals, and premium tiers.

        **Use this endpoint when you need detailed subscriber information.** If
        you only need subscriber IDs, use `/segments/{segmentId}/results` for a
        lighter-weight response.
      operationId: segments_list_members
      tags:
        - Segments
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: segmentId
          in: path
          description: The prefixed ID of the segment object
          required: true
          schema:
            $ref: '#/components/schemas/SegmentId'
          example: seg_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: seg_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).<br>If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: expand[]
          in: query
          description: >-
            Optionally expand the response to include additional data. <br>
            `stats` - Returns statistics about the subscription(s). <br>
            `custom_fields` - Returns custom field values set on the
            subscription. <br> `referrals` - Returns referrals made by the
            subscription. <br> `tags` - Returns tags associated with the
            subscription. <br> `subscription_premium_tiers` - Returns premium
            tier(s) the subscription is subscribed to.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SegmentMembersExpandItems'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentMembersResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: sub_00000000-0000-0000-0000-000000000000
                        email: subscriber@example.com
                        status: active
                        created: 1666800076
                        subscription_tier: free
                        subscription_premium_tier_names: []
                        utm_source: twitter
                        utm_medium: social
                        utm_channel: website
                        utm_campaign: spring_2023
                        utm_term: ''
                        utm_content: ''
                        referring_site: https://twitter.com
                        referral_code: ABC123
                    limit: 10
                    page: 1
                    total_results: 1
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List segment subscribers <Badge intent="info" minimal outlined>OAuth
        Scope: segments:read</Badge>
      security: *ref_0
  /publications/{publicationId}/segments/{segmentId}/results:
    get:
      description: >-
        List subscriber IDs for a segment. Returns a lightweight array of
        subscription IDs only, without additional subscriber details.

        **Use this endpoint when you only need subscriber IDs** (e.g., for
        counting, ID-based lookups, or  integrations with external systems). If
        you need full subscriber details (email, status, custom fields, etc.),
        use `/segments/{segmentId}/members` instead.
      operationId: segments_expand_results
      tags:
        - Segments
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: segmentId
          in: path
          description: The prefixed ID of the segment object
          required: true
          schema:
            $ref: '#/components/schemas/SegmentId'
          example: seg_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: seg_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).<br>If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentsGetResponse'
              examples:
                Example1:
                  value:
                    data:
                      - sub_00000000-0000-0000-0000-000000000000
                      - sub_00000000-1111-1111-1111-111111111111
                    limit: 1
                    page: 1
                    total_results: 1
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List segment subscriber IDs <Badge intent="info" minimal outlined>OAuth
        Scope: segments:read</Badge>
      security: *ref_0
  /publications/{publicationId}/subscriptions/by_email/{email}:
    get:
      description: >-
        <Info>Please note that this endpoint requires the email to be URL
        encoded. Please reference your language's documentation for the correct
        method of encoding.</Info> Retrieve a single subscription belonging to a
        specific email address in a specific publication.
      operationId: subscriptions_get-by-email
      tags:
        - Subscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: email
          in: path
          description: The ID of the subscriber object
          required: true
          schema:
            type: string
          example: work@example.com
          examples:
            Example1:
              value: work@example.com
        - name: expand[]
          in: query
          description: >-
            Optional list of expandable objects.<br>`subscription_premium_tiers
            ` - Returns an array of tiers the subscription is associated
            with.<br>`referrals` - Returns an array of subscriptions with
            limited data - `id`, `email`, and `status`. These are the
            subscriptions that were referred by this subscription.<br>`stats` -
            Returns statistics about the subscription(s).<br>`custom_fields` -
            Returns an array of custom field values that have been set on the
            subscription. <br>`tags` - Returns an array of tags that have been
            set on the subscription.<br>`newsletter_lists` - Returns an array of
            newsletter list prefixed IDs the subscription is actively subscribed
            to.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SubscriptionsGetRequestExpandItem'
              nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: sub_00000000-0000-0000-0000-000000000000
                      email: example@example.com
                      status: validating
                      created: 1666800076
                      subscription_tier: free
                      subscription_premium_tier_names:
                        - Premium
                        - Gold
                      utm_source: Twitter
                      utm_medium: organic
                      utm_channel: website
                      utm_campaign: utm_campaign
                      utm_term: ''
                      utm_content: ''
                      referring_site: https://www.blog.com
                      referral_code: referral_code
                      subscription_premium_tiers:
                        - id: tier_00000000-0000-0000-0000-000000000000
                          name: name
                          status: active
                      custom_fields:
                        - {}
                      tags:
                        - Premium
                        - Basic
                        - Active
                        - Engaged
                      stats:
                        emails_received: 25
                        open_rate: 60.1
                        click_through_rate: 25
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get subscription by email <Badge intent="info" minimal outlined>OAuth
        Scope: subscriptions:read</Badge>
      security: *ref_0
    put:
      description: Update a single subscription by email.
      operationId: subscriptions_update-by-email
      tags:
        - Subscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: email
          in: path
          description: The email of the subscription object
          required: true
          schema:
            type: string
          example: example@example.com
          examples:
            Example1:
              value: example@example.com
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: sub_00000000-0000-0000-0000-000000000000
                      email: newemail@example.com
                      status: active
                      created: 1666800076
                      subscription_tier: premium
                      subscription_premium_tier_names:
                        - Premium
                        - Gold
                      utm_source: Twitter
                      utm_medium: organic
                      utm_channel: website
                      utm_campaign: utm_campaign
                      utm_term: ''
                      utm_content: ''
                      referring_site: https://www.blog.com
                      referral_code: referral_code
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update subscription by email <Badge intent="info" minimal outlined>OAuth
        Scope: subscriptions:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  nullable: true
                  description: The new email address for the subscription
                tier:
                  $ref: >-
                    #/components/schemas/SubscriptionsPutRequestSubscriptionsItemTier
                  nullable: true
                  description: Optional parameter to set the tier for this subscription.
                premium_tier_ids:
                  type: array
                  items:
                    type: string
                  nullable: true
                  description: >-
                    An array of premium tier IDs to assign to this subscription.
                    When provided, the subscription will be assigned to these
                    specific premium tiers. Can be combined with `premium_tiers`
                    to include tiers from both (duplicates are removed). Takes
                    precedence over the `tier` parameter.
                premium_tiers:
                  type: array
                  items:
                    type: string
                  nullable: true
                  description: >-
                    An array of premium tier names to assign to this
                    subscription. When provided, the subscription will be
                    assigned to premium tiers matching these names. Can be
                    combined with `premium_tier_ids` to include tiers from both
                    (duplicates are removed). Takes precedence over the `tier`
                    parameter.
                stripe_customer_id:
                  $ref: '#/components/schemas/OptionalStripeCustomerId'
                  nullable: true
                  description: The Stripe Customer ID of the subscription (not required)
                unsubscribe:
                  type: boolean
                  nullable: true
                  description: >-
                    A boolean value specifying whether to unsubscribe this
                    subscription from the publication (not required)
                custom_fields:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/SubscriptionsPutRequestSubscriptionsItemCustomFieldsItem
                  nullable: true
                  description: An array of custom field objects to update
            examples:
              Example1:
                value:
                  tier: premium
                  email: newemail@example.com
                  stripe_customer_id: cus_12345abcde
                  custom_fields:
                    - name: First Name
                      value: Bruce
                    - name: Last Name
                      value: Wayne
  /publications/{publicationId}/subscriptions/{subscriptionId}:
    get:
      description: >-
        <Info>In previous versions of the API, another endpoint existed to
        retrieve a subscription by the subscriber ID. This endpoint is now
        deprecated and will be removed in a future version of the API. Please
        use this endpoint instead. The subscription ID can be found by exporting
        a list of subscriptions either via the `Settings > Publications > Export
        Data` or by exporting a CSV in a segment.</Info> Retrieve a single
        subscription belonging to a specific publication.
      operationId: subscriptions_get-by-id
      tags:
        - Subscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: subscriptionId
          in: path
          description: The prefixed ID of the subscription object
          required: true
          schema:
            $ref: '#/components/schemas/SubscriptionId'
          example: sub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: sub_00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: >-
            Optional list of expandable objects.<br>`subscription_premium_tiers`
            - Returns an array of tiers the subscription is associated
            with.<br>`referrals` - Returns an array of subscriptions with
            limited data - `id`, `email`, and `status`. These are the
            subscriptions that were referred by this subscription.<br>`stats` -
            Returns statistics about the subscription(s).<br>`custom_fields` -
            Returns an array of custom field values that have been set on the
            subscription. <br>`tags` - Returns an array of tags that have been
            set on the subscription.<br>`newsletter_lists` - Returns an array of
            newsletter list prefixed IDs the subscription is actively subscribed
            to.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SubscriptionsGetRequestExpandItem'
              nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: sub_00000000-0000-0000-0000-000000000000
                      email: example@example.com
                      status: validating
                      created: 1666800076
                      subscription_tier: free
                      subscription_premium_tier_names:
                        - Premium
                        - Gold
                      utm_source: Twitter
                      utm_medium: organic
                      utm_channel: website
                      utm_campaign: utm_campaign
                      utm_term: ''
                      utm_content: ''
                      referring_site: https://www.blog.com
                      referral_code: referral_code
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get subscription by ID <Badge intent="info" minimal outlined>OAuth
        Scope: subscriptions:read</Badge>
      security: *ref_0
    put:
      description: Update a single subscription.
      operationId: subscriptions_put
      tags:
        - Subscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: subscriptionId
          in: path
          description: The prefixed ID of the subscription object
          required: true
          schema:
            $ref: '#/components/schemas/SubscriptionId'
          example: sub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: sub_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: sub_00000000-0000-0000-0000-000000000000
                      email: newemail@example.com
                      status: active
                      created: 1666800076
                      subscription_tier: premium
                      subscription_premium_tier_names:
                        - Premium
                        - Gold
                      utm_source: Twitter
                      utm_medium: organic
                      utm_channel: website
                      utm_campaign: utm_campaign
                      utm_term: ''
                      utm_content: ''
                      referring_site: https://www.blog.com
                      referral_code: referral_code
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update subscription by ID <Badge intent="info" minimal outlined>OAuth
        Scope: subscriptions:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tier:
                  $ref: >-
                    #/components/schemas/SubscriptionsPutRequestSubscriptionsItemTier
                  nullable: true
                  description: Optional parameter to set the tier for this subscription.
                premium_tier_ids:
                  type: array
                  items:
                    type: string
                  nullable: true
                  description: >-
                    An array of premium tier IDs to assign to this subscription.
                    When provided, the subscription will be assigned to these
                    specific premium tiers. Can be combined with `premium_tiers`
                    to include tiers from both (duplicates are removed). Takes
                    precedence over the `tier` parameter.
                premium_tiers:
                  type: array
                  items:
                    type: string
                  nullable: true
                  description: >-
                    An array of premium tier names to assign to this
                    subscription. When provided, the subscription will be
                    assigned to premium tiers matching these names. Can be
                    combined with `premium_tier_ids` to include tiers from both
                    (duplicates are removed). Takes precedence over the `tier`
                    parameter.
                email:
                  type: string
                  nullable: true
                  description: The new email address for the subscription
                stripe_customer_id:
                  $ref: '#/components/schemas/OptionalStripeCustomerId'
                  nullable: true
                  description: The Stripe Customer ID of the subscription (not required)
                unsubscribe:
                  type: boolean
                  nullable: true
                  description: >-
                    A boolean value specifying whether to unsubscribe this
                    subscription from the publication (not required)
                custom_fields:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/SubscriptionsPutRequestSubscriptionsItemCustomFieldsItem
                  nullable: true
                  description: An array of custom field objects to update
            examples:
              Example1:
                value:
                  tier: premium
                  email: newemail@example.com
                  stripe_customer_id: cus_12345abcde
                  custom_fields:
                    - name: First Name
                      value: Bruce
                    - name: Last Name
                      value: Wayne
    patch:
      description: Update a single subscription.
      operationId: subscriptions_patch
      tags:
        - Subscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: subscriptionId
          in: path
          description: The prefixed ID of the subscription object
          required: true
          schema:
            $ref: '#/components/schemas/SubscriptionId'
          example: sub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: sub_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: sub_00000000-0000-0000-0000-000000000000
                      email: newemail@example.com
                      status: active
                      created: 1666800076
                      subscription_tier: premium
                      subscription_premium_tier_names:
                        - Premium
                        - Gold
                      utm_source: Twitter
                      utm_medium: organic
                      utm_channel: website
                      utm_campaign: utm_campaign
                      utm_term: ''
                      utm_content: ''
                      referring_site: https://www.blog.com
                      referral_code: referral_code
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update subscription by ID <Badge intent="info" minimal outlined>OAuth
        Scope: subscriptions:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  nullable: true
                  description: The new email address for the subscription
                tier:
                  $ref: >-
                    #/components/schemas/SubscriptionsPatchRequestSubscriptionsItemTier
                  nullable: true
                  description: Optional parameter to set the tier for this subscription.
                premium_tier_ids:
                  type: array
                  items:
                    type: string
                  nullable: true
                  description: >-
                    An array of premium tier IDs to assign to this subscription.
                    When provided, the subscription will be assigned to these
                    specific premium tiers. Can be combined with `premium_tiers`
                    to include tiers from both (duplicates are removed). Takes
                    precedence over the `tier` parameter.
                premium_tiers:
                  type: array
                  items:
                    type: string
                  nullable: true
                  description: >-
                    An array of premium tier names to assign to this
                    subscription. When provided, the subscription will be
                    assigned to premium tiers matching these names. Can be
                    combined with `premium_tier_ids` to include tiers from both
                    (duplicates are removed). Takes precedence over the `tier`
                    parameter.
                stripe_customer_id:
                  $ref: '#/components/schemas/OptionalStripeCustomerId'
                  nullable: true
                  description: The Stripe Customer ID of the subscription (not required)
                unsubscribe:
                  type: boolean
                  nullable: true
                  description: >-
                    A boolean value specifying whether to unsubscribe this
                    subscription from the publication (not required)
                custom_fields:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/SubscriptionsPatchRequestSubscriptionsItemCustomFieldsItem
                  nullable: true
                  description: An array of custom field objects to update
            examples:
              Example1:
                value:
                  tier: premium
                  email: newemail@example.com
                  stripe_customer_id: cus_12345abcde
                  custom_fields:
                    - name: First Name
                      value: Bruce
                    - name: Last Name
                      value: Wayne
    delete:
      description: >-
        <Warning>This cannot be undone. All data associated with the
        subscription will also be deleted. We recommend unsubscribing when
        possible instead of deleting. If a premium subscription is deleted they
        will no longer be billed.</Warning> Deletes a subscription.
      operationId: subscriptions_delete
      tags:
        - Subscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: subscriptionId
          in: path
          description: The prefixed ID of the subscription object
          required: true
          schema:
            $ref: '#/components/schemas/SubscriptionId'
          example: sub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: sub_00000000-0000-0000-0000-000000000000
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionDeleteResponse'
              examples:
                Example1:
                  value: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Delete subscription <Badge intent="info" minimal outlined>OAuth Scope:
        subscriptions:write</Badge>
      security: *ref_0
  /publications/{publicationId}/subscriptions/by_subscriber_id/{subscriberId}:
    get:
      description: >-
        Retrieve a single subscription belonging to a specific publication via
        the subscriber ID.
      operationId: subscriptions_get-by-subscriber-id
      tags:
        - Subscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: subscriberId
          in: path
          description: The ID of the subscriber object
          required: true
          schema:
            type: string
          example: 00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: 00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: >-
            Optional list of expandable objects.<br>`subscription_premium_tiers`
            - Returns an array of tiers the subscription is associated
            with.<br>`referrals` - Returns an array of subscriptions with
            limited data - `id`, `email`, and `status`. These are the
            subscriptions that were referred by this subscription.<br>`stats` -
            Returns statistics about the subscription(s).<br>`custom_fields` -
            Returns an array of custom field values that have been set on the
            subscription.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SubscriptionsGetRequestExpandItem'
              nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: sub_00000000-0000-0000-0000-000000000000
                      email: example@example.com
                      status: validating
                      created: 1666800076
                      subscription_tier: free
                      subscription_premium_tier_names:
                        - Premium
                        - Gold
                      utm_source: Twitter
                      utm_medium: organic
                      utm_channel: website
                      utm_campaign: utm_campaign
                      utm_term: ''
                      utm_content: ''
                      referring_site: https://www.blog.com
                      referral_code: referral_code
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get subscription by subscriber ID <Badge intent="info" minimal
        outlined>OAuth Scope: subscriptions:read</Badge>
      security: *ref_0
  /publications/{publicationId}/subscriptions/{subscriptionId}/jwt_token:
    get:
      description: >-
        Generate a JWT token that can be used to automatically log in
        subscribers via URL. This token is short lived and should be used
        immediately.
      operationId: subscriptions_get-jwt_token
      tags:
        - Subscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: subscriptionId
          in: path
          description: The prefixed ID of the subscription object
          required: true
          schema:
            $ref: '#/components/schemas/SubscriptionId'
          example: sub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: sub_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionJwtTokenResponse'
              examples:
                Example1:
                  value:
                    data:
                      jwt_token: >-
                        01234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get subscription JWT token <Badge intent="info" minimal outlined>OAuth
        Scope: subscriptions:read</Badge>
      security: *ref_0
  /publications/{publicationId}/subscriptions/{subscriptionId}/tags:
    post:
      description: >-
        Adds tags to a subscription. If the tag does not exist on the
        publication, it will be created automatically.
      operationId: subscriptionTags_create
      tags:
        - SubscriptionTags
      parameters:
        - name: publicationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: publicationId
          examples:
            Example1:
              value: publicationId
        - name: subscriptionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/SubscriptionId'
          example: subscriptionId
          examples:
            Example1:
              value: subscriptionId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionTagsCreateResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: sub_00000000-0000-0000-0000-000000000000
                      email: example@example.com
                      status: validating
                      created: 1666800076
                      subscription_tier: free
                      subscription_premium_tier_names:
                        - Premium
                        - Gold
                      utm_source: Twitter
                      utm_medium: organic
                      utm_channel: website
                      utm_campaign: utm_campaign
                      utm_term: ''
                      utm_content: ''
                      referring_site: https://www.blog.com
                      referral_code: referral_code
                      tags:
                        - Premium
                        - Basic
                        - Active
                        - Engaged
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Add subscription tag <Badge intent="info" minimal outlined>OAuth Scope:
        subscriptions:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tags:
                  type: array
                  items:
                    type: string
                  nullable: true
                  description: Tags that can be used to group subscribers
            examples:
              Example1:
                value:
                  tags:
                    - Premium
                    - Basic
  /publications/{publicationId}/tiers:
    post:
      description: Create a new tier for a publication.
      operationId: tiers_create
      tags:
        - Tiers
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TierResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: tier_00000000-0000-0000-0000-000000000000
                      name: Gold
                      status: active
                      description: description
                      stats:
                        active_subscriptions: 1
                      prices:
                        - id: price_00000000-0000-0000-0000-000000000000
                          amount_cents: 500
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Create a tier <Badge intent="info" minimal outlined>OAuth Scope:
        tiers:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Gold Tier
                description:
                  type: string
                  nullable: true
                prices_attributes:
                  type: array
                  items:
                    $ref: '#/components/schemas/TierPricesAttributesItem'
                  nullable: true
              required:
                - name
            examples:
              Example1:
                value:
                  name: Gold Tier
                  description: Our premium tier with exclusive benefits
                  prices_attributes:
                    - currency: usd
                      amount_cents: 500
                      enabled: true
                      interval: month
                      interval_display: Monthly
                      cta: Subscribe Now
                      features:
                        - Exclusive content
                        - Ad-free experience
                        - Priority support
    get:
      description: Retrieve all tiers belonging to a specific publication
      operationId: tiers_index
      tags:
        - Tiers
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: >-
            Optional list of expandable objects.<br>`stats` - Returns statistics
            about the tier(s).<br>`prices` - Returns prices for the tier(s).
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the
            number of results specified by the `limit` (default: 10).<br>If not
            specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
            nullable: true
        - name: direction
          in: query
          description: >-
            The direction that the results are sorted in. Defaults to asc<br>
            `asc` - Ascending, sorts from smallest to largest.<br> `desc` -
            Descending, sorts from largest to smallest.
          required: false
          schema:
            $ref: '#/components/schemas/RequestDirection'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexTiersResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: tier_00000000-0000-0000-0000-000000000000
                        name: Gold
                        status: active
                        description: description
                        stats:
                          active_subscriptions: 1
                        prices:
                          - id: price_00000000-0000-0000-0000-000000000000
                            amount_cents: 500
                    limit: 1
                    page: 1
                    total_results: 1
                    total_pages: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List tiers <Badge intent="info" minimal outlined>OAuth Scope:
        tiers:read</Badge>
      security: *ref_0
  /publications/{publicationId}/tiers/{tierId}:
    get:
      description: Retrieve a single tier belonging to a specific publication
      operationId: tiers_show
      tags:
        - Tiers
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: tierId
          in: path
          description: The prefixed ID of the tier object
          required: true
          schema:
            $ref: '#/components/schemas/TierId'
          example: tier_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: tier_00000000-0000-0000-0000-000000000000
        - name: expand[]
          in: query
          description: >-
            Optional list of expandable objects.<br>`stats` - Returns statistics
            about the tier(s).<br>`prices` - Returns prices for the tier(s).
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TierResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: tier_00000000-0000-0000-0000-000000000000
                      name: Gold
                      status: active
                      description: description
                      stats:
                        active_subscriptions: 1
                      prices:
                        - id: price_00000000-0000-0000-0000-000000000000
                          amount_cents: 500
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get tier <Badge intent="info" minimal outlined>OAuth Scope:
        tiers:read</Badge>
      security: *ref_0
    put:
      description: Update an existing tier belonging to a specific publication
      operationId: tiers_put
      tags:
        - Tiers
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: tierId
          in: path
          description: The prefixed ID of the tier object
          required: true
          schema:
            $ref: '#/components/schemas/TierId'
          example: tier_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: tier_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TierResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: tier_00000000-0000-0000-0000-000000000000
                      name: Gold
                      status: active
                      description: description
                      stats:
                        active_subscriptions: 1
                      prices:
                        - id: price_00000000-0000-0000-0000-000000000000
                          amount_cents: 500
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update a tier <Badge intent="info" minimal outlined>OAuth Scope:
        tiers:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  nullable: true
                description:
                  type: string
                  nullable: true
                prices_attributes:
                  type: array
                  items:
                    $ref: '#/components/schemas/UpdateTierPriceRequest'
                  nullable: true
            examples:
              Example1:
                value:
                  name: Gold
                  description: Our premium tier with exclusive benefits
                  prices_attributes:
                    - id: price_00000000-0000-0000-0000-000000000000
                      currency: usd
                      amount_cents: 500
                      interval: month
                      interval_display: Monthly
                      cta: Subscribe Now
                      features:
                        - Exclusive content
                      delete: true
    patch:
      description: Update an existing tier belonging to a specific publication
      operationId: tiers_patch
      tags:
        - Tiers
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: tierId
          in: path
          description: The prefixed ID of the tier object
          required: true
          schema:
            $ref: '#/components/schemas/TierId'
          example: tier_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: tier_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TierResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: tier_00000000-0000-0000-0000-000000000000
                      name: Gold
                      status: active
                      description: description
                      stats:
                        active_subscriptions: 1
                      prices:
                        - id: price_00000000-0000-0000-0000-000000000000
                          amount_cents: 500
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update a tier <Badge intent="info" minimal outlined>OAuth Scope:
        tiers:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  nullable: true
                description:
                  type: string
                  nullable: true
                prices_attributes:
                  type: array
                  items:
                    $ref: '#/components/schemas/UpdateTierPriceRequest'
                  nullable: true
            examples:
              Example1:
                value:
                  name: Gold
                  description: Our premium tier with exclusive benefits
                  prices_attributes:
                    - id: price_00000000-0000-0000-0000-000000000000
                      currency: usd
                      amount_cents: 500
                      interval: month
                      interval_display: Monthly
                      cta: Subscribe Now
                      features:
                        - Exclusive content
                      delete: true
  /publications/{publicationId}/webhooks:
    post:
      description: Create a new webhook for a given publication.
      operationId: webhooks_create
      tags:
        - Webhooks
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: ep_0ca1a8505a64924059c391744d0
                      url: https://example.com/webhook
                      created: 1666800076
                      updated: 1666800076
                      event_types:
                        - post.sent
                        - subscription.confirmed
                      description: >-
                        A webhook to receive new posts data and new subscription
                        confirmations.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Create a webhook <Badge intent="info" minimal outlined>OAuth Scope:
        webhooks:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: The webhook URL to send events to.
                  example: https://example.com/webhook
                event_types:
                  type: array
                  items:
                    $ref: '#/components/schemas/WebhookEventType'
                  description: The types of events the webhook will receive.
                description:
                  type: string
                  nullable: true
                  description: A description of the webhook.
              required:
                - url
                - event_types
            examples:
              Example1:
                value:
                  url: https://example.com/webhook
                  event_types:
                    - post.sent
    get:
      description: Retrieve all webhooks belonging to a specific publication.
      operationId: webhooks_index
      tags:
        - Webhooks
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range
            between 1 and 100, and the default is 10.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexWebhooksResponse'
              examples:
                Example1:
                  value:
                    data:
                      - id: ep_0ca1a8505a64924059c391744d0
                        url: https://example.com/webhook
                        created: 1666800076
                        updated: 1666800076
                        event_types:
                          - post.sent
                          - subscription.confirmed
                        description: >-
                          A webhook to receive new posts data and new
                          subscription confirmations.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        List webhooks <Badge intent="info" minimal outlined>OAuth Scope:
        webhooks:read</Badge>
      security: *ref_0
  /publications/{publicationId}/webhooks/{endpointId}:
    get:
      description: Retrieve a specific webhook belonging to a publication.
      operationId: webhooks_show
      tags:
        - Webhooks
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: endpointId
          in: path
          description: The prefixed ID of the webhook object
          required: true
          schema:
            $ref: '#/components/schemas/EndpointId'
          example: ep_0000000000000000000000000000
          examples:
            Example1:
              value: ep_0000000000000000000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: ep_0ca1a8505a64924059c391744d0
                      url: https://example.com/webhook
                      created: 1666800076
                      updated: 1666800076
                      event_types:
                        - post.sent
                        - subscription.confirmed
                      description: >-
                        A webhook to receive new posts data and new subscription
                        confirmations.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get webhook <Badge intent="info" minimal outlined>OAuth Scope:
        webhooks:read</Badge>
      security: *ref_0
    patch:
      description: Update a webhook subscription for a publication.
      operationId: webhooks_update
      tags:
        - Webhooks
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: endpointId
          in: path
          description: The prefixed ID of the webhook object
          required: true
          schema:
            $ref: '#/components/schemas/EndpointId'
          example: ep_0000000000000000000000000000
          examples:
            Example1:
              value: ep_0000000000000000000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: ep_0ca1a8505a64924059c391744d0
                      url: https://example.com/webhook
                      created: 1666800076
                      updated: 1666800076
                      event_types:
                        - post.sent
                        - subscription.confirmed
                      description: >-
                        A webhook to receive new posts data and new subscription
                        confirmations.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Update webhook <Badge intent="info" minimal outlined>OAuth Scope:
        webhooks:write</Badge>
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                event_types:
                  type: array
                  items:
                    $ref: '#/components/schemas/WebhookEventType'
                  nullable: true
                  description: The types of events the webhook will receive.
                description:
                  type: string
                  nullable: true
                  description: A description of the webhook.
            examples:
              Example1:
                value:
                  event_types:
                    - post.sent
                    - subscription.confirmed
                  description: >-
                    A webhook to receive new posts data and new subscription
                    confirmations.
    delete:
      description: Delete a webhook subscription from a publication.
      operationId: webhooks_delete
      tags:
        - Webhooks
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/PublicationId'
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: endpointId
          in: path
          description: The prefixed ID of the webhook object
          required: true
          schema:
            $ref: '#/components/schemas/EndpointId'
          example: ep_0000000000000000000000000000
          examples:
            Example1:
              value: ep_0000000000000000000000000000
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhooksDeleteResponse'
              examples:
                Example1:
                  value: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Delete a webhook <Badge intent="info" minimal outlined>OAuth Scope:
        webhooks:write</Badge>
      security: *ref_0
  /publications/{publicationId}/webhooks/{endpointId}/tests:
    get:
      description: Send test info to an already set up webhook endpoint.
      operationId: webhooks_test
      tags:
        - Webhooks
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            type: string
          example: pub_00000000-0000-0000-0000-000000000000
          examples:
            Example1:
              value: pub_00000000-0000-0000-0000-000000000000
        - name: endpointId
          in: path
          description: The prefixed ID of the webhook object
          required: true
          schema:
            $ref: '#/components/schemas/EndpointId'
          example: ep_0000000000000000000000000000
          examples:
            Example1:
              value: ep_0000000000000000000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/GetPublicationsPublicationIdWebhooksWebhookIdTestsResponse
              examples:
                Example1:
                  value:
                    data:
                      key: value
                    event_timestamp: 1666800076
                    event_type: post.sent
                    uid: test_00000000-0000-0000-0000-000000000000
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Test webhook <Badge intent="info" minimal outlined>OAuth Scope:
        webhooks:read</Badge>
      security: *ref_0
  /workspaces/identify:
    get:
      description: >-
        Retrieve information about the workspace the OAuth or API token is
        associated with.
      operationId: workspaces_identify
      tags:
        - Workspaces
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceIdentifyResponse'
              examples:
                Example1:
                  value:
                    data:
                      id: work_00000000-0000-0000-0000-000000000000
                      name: Bruce's Hiiv
                      owner_email: bruce.wayne@wayneenterprise.com
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Identify workspace <Badge intent="info" minimal outlined>OAuth Scope:
        identify:read</Badge>
      security: *ref_0
  /workspaces/publications/by_subscription_email/{email}:
    get:
      description: >-
        Retrieve all publications in the workspace that have a subscription for
        the specified email address. The workspace is determined by the provided
        API key.
      operationId: workspaces_publications-by-subscription-email
      tags:
        - Workspaces
      parameters:
        - name: email
          in: path
          description: The email address to search for subscriptions
          required: true
          schema:
            type: string
          example: bruce.wayne@wayneenterprise.com
          examples:
            Example1:
              value: bruce.wayne@wayneenterprise.com
            Example2:
              value: bruce.wayne@wayneenterprise.com
            Example3:
              value: bruce.wayne@wayneenterprise.com
        - name: expand
          in: query
          description: >-
            Optionally expand the results by adding additional information.
            <br>`subscription` - Returns the full Subscription object for the
            email address in each publication. <br>`publication` - Returns the
            full Publication object instead of just ID and name.
            <br>`subscription_custom_fields` - Returns custom field values
            nested within the subscription object. (Returns the subscription
            object regardless of whether `subscription` is requested.)
          required: false
          schema:
            type: array
            items:
              type: array
              items:
                $ref: >-
                  #/components/schemas/PublicationsBySubscriptionEmailRequestExpandItem
              nullable: true
          example: &ref_5
            - subscription
            - publication
            - subscription_custom_fields
          examples:
            Example1:
              value: *ref_5
            Example2:
              value:
                - subscription_custom_fields
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: >-
                    #/components/schemas/PublicationsBySubscriptionEmailResponseItem
              examples:
                Example1:
                  value:
                    - publication_id: pub_00000000-0000-0000-0000-000000000000
                      publication_name: Publication Name 1
                      subscription_id: sub_00000000-0000-0000-0000-000000000000
                      status: active
                    - publication_id: pub_11111111-1111-1111-1111-111111111111
                      publication_name: Publication Name 2
                      subscription_id: sub_11111111-1111-1111-1111-111111111111
                      status: active
                Example2:
                  value:
                    - publication_id: pub_00000000-0000-0000-0000-000000000000
                      publication_name: Publication Name 1
                      subscription_id: sub_00000000-0000-0000-0000-000000000000
                      status: active
                      publication:
                        id: pub_00000000-0000-0000-0000-000000000000
                        name: Publication Name 1
                        organization_name: Organization Name
                        referral_program_enabled: true
                        created: 1234567890
                      subscription:
                        id: sub_00000000-0000-0000-0000-000000000000
                        email: bruce.wayne@wayneenterprise.com
                        status: active
                        created: 1234567890
                        subscription_tier: free
                        subscription_premium_tier_names: []
                        utm_source: ''
                        utm_medium: ''
                        utm_channel: ''
                        utm_campaign: ''
                        utm_term: ''
                        utm_content: ''
                        referring_site: ''
                        referral_code: ''
                        custom_fields:
                          - name: First Name
                            kind: string
                            value: Bruce
                          - name: Last Name
                            kind: string
                            value: Wayne
                Example3:
                  value:
                    - publication_id: pub_00000000-0000-0000-0000-000000000000
                      publication_name: Publication Name 1
                      subscription_id: sub_00000000-0000-0000-0000-000000000000
                      status: active
                      subscription:
                        id: sub_00000000-0000-0000-0000-000000000000
                        email: bruce.wayne@wayneenterprise.com
                        status: active
                        created: 1234567890
                        subscription_tier: free
                        subscription_premium_tier_names: []
                        utm_source: ''
                        utm_medium: ''
                        utm_channel: ''
                        utm_campaign: ''
                        utm_term: ''
                        utm_content: ''
                        referring_site: ''
                        referral_code: ''
                        custom_fields:
                          - name: First Name
                            kind: string
                            value: Bruce
                          - name: Last Name
                            kind: string
                            value: Wayne
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: >-
        Get publications by subscription email <Badge intent="info" minimal
        outlined>OAuth Scope: publications:read</Badge>
      security: *ref_0
components:
  schemas:
    CustomFieldType:
      title: CustomFieldType
      type: string
      enum:
        - string
        - integer
        - boolean
        - date
        - datetime
        - list
        - double
      description: The type of value being stored in the custom field.
    CustomField:
      title: CustomField
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: The name of the existing custom field
        kind:
          $ref: '#/components/schemas/CustomFieldType'
          nullable: true
          description: The type of value being stored in the custom field.
        value:
          $ref: '#/components/schemas/CustomFieldDataType'
          nullable: true
          description: The value stored for the subscription
    CustomFieldDataType:
      title: CustomFieldDataType
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
        - type: array
          items:
            type: string
    CustomFieldValue:
      title: CustomFieldValue
      type: object
      description: The object required for setting custom field values on a subscription
      properties:
        name:
          type: string
          nullable: true
          description: The name of the existing custom field
        value:
          $ref: '#/components/schemas/CustomFieldDataType'
          nullable: true
          description: The value stored for the subscription
    EmailBlastStatus:
      title: EmailBlastStatus
      type: string
      enum:
        - active
        - inactive
      description: >-
        The status of the blast.<br>`inactive` - not been scheduled.<br>`active`
        - The blast is scheduled to send.
    EmailBlast:
      title: EmailBlast
      type: object
      properties:
        id:
          $ref: '#/components/schemas/EmailBlastId'
          description: The prefixed email blast id
        created:
          type: integer
          description: >-
            The time the blast was created. Measured in seconds since the Unix
            epoch
        last_sent:
          type: integer
          description: >-
            The time the blast was last sent. Measured in seconds since the Unix
            epoch
        status:
          $ref: '#/components/schemas/EmailBlastStatus'
          description: >-
            The status of the blast.<br>`inactive` - not been
            scheduled.<br>`active` - The blast is scheduled to send.
        subject_line:
          type: string
          description: The email subject line.
        preview_text:
          type: string
          description: The email preview text
        stats:
          $ref: '#/components/schemas/EmailBlastStats'
          nullable: true
        content:
          $ref: '#/components/schemas/EmailBlastContent'
          nullable: true
      required:
        - id
        - created
        - last_sent
        - status
        - subject_line
        - preview_text
    EmailBlastContentEmail:
      title: EmailBlastContentEmail
      type: object
      properties:
        free:
          type: string
          nullable: true
        premium:
          type: string
          nullable: true
    EmailBlastContent:
      title: EmailBlastContent
      type: object
      description: >-
        Optional html content for an email blast. Retrievable by including any
        of `expand: [free_email_content, premium_email_content]` in the post
        request body.


        **Note:** Generating HTML is slow. We recommend only requesting the HTML
        versions you need at the time.
      properties:
        email:
          $ref: '#/components/schemas/EmailBlastContentEmail'
          nullable: true
    EmailBlastStatsEmail:
      title: EmailBlastStatsEmail
      type: object
      description: >-
        Stats scoped only to email recipients. Not relevant for posts published
        only to web
      properties:
        recipients:
          type: integer
          nullable: true
          description: Total number of email recipients
        opens:
          type: integer
          nullable: true
          description: Total number of email opens
        unique_opens:
          type: integer
          minimum: 0
          nullable: true
          description: Total number of unique email opens
        open_rate:
          type: number
          format: double
          nullable: true
          description: The percentage of emails that have been opened
        clicks:
          type: integer
          nullable: true
          description: Total number of email clicks
        unique_clicks:
          type: integer
          nullable: true
          description: Unique number of email clicks
        click_rate:
          type: number
          format: double
          nullable: true
          description: The percentage of emails that have been clicked
        unsubscribes:
          type: integer
          nullable: true
          description: Total number of email unsubscribes
        spam_reports:
          type: integer
          minimum: 0
          nullable: true
          description: The number of subscribers that reported this post email as spam
    EmailBlastStatsClicks:
      title: EmailBlastStatsClicks
      type: object
      properties:
        url:
          type: string
          nullable: true
          description: The URL the stats are for
        total_clicks:
          type: integer
          nullable: true
        total_unique_clicks:
          type: integer
          nullable: true
        total_click_through_rate:
          type: number
          format: double
          nullable: true
          description: >-
            The percentage of clicks on the URL compared to the total number of
            recipients and web views
    EmailBlastStats:
      title: EmailBlastStats
      type: object
      description: >-
        Optional list of stats for an email blast. Retrievable by including
        `expand: [stats]` in the email blast request body.
      properties:
        email:
          $ref: '#/components/schemas/EmailBlastStatsEmail'
          nullable: true
          description: >-
            Stats scoped only to email recipients. Not relevant for posts
            published only to web
        clicks:
          type: array
          items:
            $ref: '#/components/schemas/EmailBlastStatsClicks'
          nullable: true
          description: An array of click statistics for each URL in the post
    DoubleOptOverride:
      title: DoubleOptOverride
      type: string
      description: Override publication double-opt settings for this subscription.
    ErrorDetail:
      title: ErrorDetail
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
        - message
        - code
    Error:
      title: Error
      type: object
      description: The top level error response.
      properties:
        status:
          type: integer
        statusText:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
      required:
        - status
        - statusText
        - errors
    Milestone:
      title: Milestone
      type: object
      description: The milestone object.
      properties:
        id:
          $ref: '#/components/schemas/MilestoneId'
          description: A unique prefixed id of the milestone.
        auto_fulfill:
          type: boolean
          description: >-
            Only available with a promo code reward type. This indicates that an
            email will automatically be sent when the milestone is reached
            containing the reward promo code.
        num_referrals:
          type: integer
          minimum: 0
          description: The number of referrals needed to reach this milestone.
        reward:
          $ref: '#/components/schemas/MilestoneReward'
      required:
        - id
        - auto_fulfill
        - num_referrals
        - reward
    MilestoneRewardType:
      title: MilestoneRewardType
      type: string
      enum:
        - physical
        - promo_code
        - digital
        - premium_gift
      description: >-
        What type of reward this is.<br>`physical` - A product which must be
        sent to the subscriber.<br>`promo_code` - A code that is redeemable for
        goods or services.
    MilestoneReward:
      title: MilestoneReward
      type: object
      description: The reward object.
      properties:
        id:
          $ref: '#/components/schemas/RewardId'
          description: A unique prefixed id of the reward.
        name:
          type: string
          description: The name given to the reward at creation.
        description:
          type: string
          description: The description given to the name at creation.
        image_url:
          type: string
          description: A URL of an image to be displayed with the reward.
        type:
          $ref: '#/components/schemas/MilestoneRewardType'
          description: >-
            What type of reward this is.<br>`physical` - A product which must be
            sent to the subscriber.<br>`promo_code` - A code that is redeemable
            for goods or services.
      required:
        - id
        - name
        - description
        - image_url
        - type
    SubscriptionStatus:
      title: SubscriptionStatus
      type: string
      enum:
        - validating
        - invalid
        - pending
        - active
        - inactive
        - needs_attention
      description: >-
        The status of the subscription.<br>`validating` - The email address is
        being validated.<br>`invalid` - The email address is
        invalid.<br>`pending` - The email address is valid, but the subscription
        is pending double opt-in.<br>`active` - The email was valid and the
        subscription is active.<br>`inactive` - The subscription was made
        inactive, possibly due to an unsubscribe.<br>`needs_attention` - The
        subscription requires approval or denial.
    SubscriptionSubscriptionTier:
      title: SubscriptionSubscriptionTier
      type: string
      enum:
        - free
        - premium
      description: The current tier of the subscription.
    SubscriptionAcquisitionChannel:
      title: SubscriptionAcquisitionChannel
      type: string
      enum:
        - ''
        - website
        - import
        - embed
        - api
        - referral
        - recommendation
        - magic_link
        - boost
        - boost_send
        - boost_direct_link
        - integration
        - product
      description: The acquisition channel
    Subscription:
      title: Subscription
      type: object
      description: The subscription object
      properties:
        id:
          $ref: '#/components/schemas/SubscriptionId'
          description: The prefixed subscription id
        email:
          type: string
          format: email
        status:
          $ref: '#/components/schemas/SubscriptionExpandedStatus'
          description: >-
            The status of the subscription.<br>`validating` - The email address
            is being validated.<br>`invalid` - The email address is
            invalid.<br>`pending` - The email address is valid, but the
            subscription is pending double opt-in.<br>`active` - The email was
            valid and the subscription is active.<br>`inactive` - The
            subscription was made inactive, possibly due to an
            unsubscribe.<br>`needs_attention` - The subscription requires
            approval or denial.
        created:
          type: integer
          description: >-
            The date the subscription was created. Measured in seconds since the
            Unix epoch
        subscription_tier:
          $ref: '#/components/schemas/SubscriptionExpandedSubscriptionTier'
          description: The current tier of the subscription.
        subscription_premium_tier_names:
          type: array
          items:
            type: string
          description: >-
            The current premium tiers of the subscription. Empty if the
            subscriber is not associated with any premium tiers.
        utm_source:
          type: string
          description: The acquisition source; where the subscriber came from
        utm_medium:
          type: string
          description: The acquisition medium; how the subscriber got to your publication
        utm_channel:
          $ref: '#/components/schemas/SubscriptionExpandedUtmChannel'
          description: The acquisition channel
        utm_campaign:
          type: string
          description: The acquisition campaign
        utm_term:
          type: string
          description: The acquisition term; typically the keyword or search term
        utm_content:
          type: string
          description: >-
            The acquisition content; typically used for A/B testing or ad
            variations
        referring_site:
          type: string
          description: The website that the subscriber was referred from
        referral_code:
          type: string
          description: >-
            The code associated to this subscriber to refer others. When a new
            subscription is created with this referral code, credit for the
            referral goes to this subscription.
        subscription_premium_tiers:
          $ref: '#/components/schemas/SubscriptionTierList'
          nullable: true
        custom_fields:
          $ref: '#/components/schemas/SubscriptionCustomFieldList'
          nullable: true
        tags:
          $ref: '#/components/schemas/SubscriptionTags'
          nullable: true
        stats:
          $ref: '#/components/schemas/SubscriptionStats'
          nullable: true
        newsletter_list_ids:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            The prefixed IDs of the newsletter lists this subscription is
            actively subscribed to. Requires `expand[]=newsletter_lists`. <Badge
            intent="warning" minimal outlined>Beta</Badge>
      required:
        - id
        - email
        - status
        - created
        - subscription_tier
        - subscription_premium_tier_names
        - utm_source
        - utm_medium
        - utm_channel
        - utm_campaign
        - utm_term
        - utm_content
        - referring_site
        - referral_code
    SubscriptionJwtToken:
      title: SubscriptionJwtToken
      type: object
      description: The JWT token object
      properties:
        jwt_token:
          type: string
          description: The JWT token
      required:
        - jwt_token
    SubscriptionStatusWithTags:
      title: SubscriptionStatusWithTags
      type: string
      enum:
        - validating
        - invalid
        - pending
        - active
        - inactive
        - needs_attention
      description: >-
        The status of the subscription.<br>`validating` - The email address is
        being validated.<br>`invalid` - The email address is
        invalid.<br>`pending` - The email address is valid, but the subscription
        is pending double opt-in.<br>`active` - The email was valid and the
        subscription is active.<br>`inactive` - The subscription was made
        inactive, possibly due to an unsubscribe.<br>`needs_attention` - The
        subscription requires approval or denial.
    SubscriptionExpandedTagsSubscriptionTier:
      title: SubscriptionExpandedTagsSubscriptionTier
      type: string
      enum:
        - free
        - premium
      description: The current tier of the subscription.
    SubscriptionExpandedTagsUtmChannel:
      title: SubscriptionExpandedTagsUtmChannel
      type: string
      enum:
        - ''
        - website
        - import
        - embed
        - api
        - referral
        - recommendation
        - magic_link
        - boost
        - boost_send
        - boost_direct_link
        - integration
        - product
      description: The acquisition channel
    SubscriptionExpandedStatus:
      title: SubscriptionExpandedStatus
      type: string
      enum:
        - validating
        - invalid
        - pending
        - active
        - inactive
        - needs_attention
        - paused
      description: >-
        The status of the subscription.<br>`validating` - The email address is
        being validated.<br>`invalid` - The email address is
        invalid.<br>`pending` - The email address is valid, but the subscription
        is pending double opt-in.<br>`active` - The email was valid and the
        subscription is active.<br>`inactive` - The subscription was made
        inactive, possibly due to an unsubscribe.<br>`needs_attention` - The
        subscription requires approval or denial.<br>`paused` - The subscriber
        has paused their subscription.
    SubscriptionExpandedSubscriptionTier:
      title: SubscriptionExpandedSubscriptionTier
      type: string
      enum:
        - free
        - premium
      description: The current tier of the subscription.
    SubscriptionExpandedUtmChannel:
      title: SubscriptionExpandedUtmChannel
      type: string
      enum:
        - ''
        - website
        - import
        - embed
        - api
        - referral
        - recommendation
        - magic_link
        - boost
        - boost_send
        - boost_direct_link
        - integration
        - product
      description: The acquisition channel
    SubscriptionCustomFieldList:
      title: SubscriptionCustomFieldList
      type: array
      items:
        $ref: '#/components/schemas/CustomField'
      description: >-
        Optional list of custom fields for a subscription. Retrievable by
        including `expand: [custom_field]` in the request body.
    SubscriptionStats:
      title: SubscriptionStats
      type: object
      description: >-
        Optional list of stats for a subscription. Retrievable by including
        `expand: [stats]` in the request body.
      properties:
        emails_received:
          type: integer
          nullable: true
          description: The total number of emails that have been sent to this subscriber
        open_rate:
          type: number
          format: double
          minimum: 0
          maximum: 100
          nullable: true
          description: The percentage of emails that the subscriber has opened
        click_through_rate:
          type: number
          format: double
          minimum: 0
          maximum: 100
          nullable: true
          description: The percentage of emails that the subscriber has clicked a link in
    SubscriptionTags:
      title: SubscriptionTags
      type: array
      items:
        type: string
      description: >-
        Optional list of tags for a subscription. Retrievable by including
        `expand: [tags]` in the request body.

        Max limit of 100 unique tags per publication.
    SubscriptionTierInfoStatus:
      title: SubscriptionTierInfoStatus
      type: string
      enum:
        - active
        - archived
      description: Returns whether or not the tier has any active prices.
    SubscriptionTierInfo:
      title: SubscriptionTierInfo
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TierId'
        name:
          type: string
        status:
          $ref: '#/components/schemas/SubscriptionTierInfoStatus'
          description: Returns whether or not the tier has any active prices.
      required:
        - id
        - name
        - status
    SubscriptionTierList:
      title: SubscriptionTierList
      type: array
      items:
        $ref: '#/components/schemas/SubscriptionTierInfo'
      description: >-
        Optional list of tiers for a subscription. Retrievable by including
        `expand: [subscription_premium_tiers]` in the request body.
    PostStatus:
      title: PostStatus
      type: string
      enum:
        - draft
        - confirmed
        - archived
      description: >-
        The status of the post.<br>`draft` - not been scheduled.<br>`confirmed`
        - The post will be active after the `scheduled_at`.<br>`archived` - The
        post is no longer active.
    SubscriptionsCreateRequestTier:
      title: SubscriptionsCreateRequestTier
      type: string
      enum:
        - free
        - premium
      description: The tier for this subscription.
    SubscriptionRequest:
      title: SubscriptionRequest
      type: object
      properties:
        email:
          type: string
          description: The email address of the subscription.
          example: bruce.wayne@wayneenterprise.com
        reactivate_existing:
          type: boolean
          nullable: true
          description: >-
            Whether or not to reactivate the subscription if they have already
            unsubscribed. This option should be used only if the subscriber is
            knowingly resubscribing.
        send_welcome_email:
          type: boolean
          nullable: true
        utm_source:
          type: string
          nullable: true
          description: The source of the subscription.
        utm_medium:
          type: string
          nullable: true
          description: The medium of the subscription
        utm_campaign:
          type: string
          nullable: true
          description: The acquisition campaign of the subscription
        utm_term:
          type: string
          nullable: true
          description: The acquisition term; typically the keyword or search term
        utm_content:
          type: string
          nullable: true
          description: >-
            The acquisition content; typically used for A/B testing or ad
            variations
        referring_site:
          type: string
          nullable: true
          description: The website that the subscriber was referred from
        referral_code:
          type: string
          nullable: true
          description: >-
            This should be a subscribers referral_code. This gives referral
            credit for the new subscription.
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldValue'
          nullable: true
          description: >-
            The custom fields must already exist for the publication. Any new
            custom fields here will be discarded.
        double_opt_override:
          $ref: '#/components/schemas/DoubleOptOverride'
          nullable: true
          description: >-
            Override the publication's default double opt-in settings for this
            subscription. Possible values are:

            - "on" — The subscriber will receive a double opt-in confirmation
            email and will need to confirm their subscription prior to being
            marked as active.

            - "off" — The subscriber will be marked as active immediately and
            will not receive a double opt-in confirmation email.

            - "not_set" — The publication's default double opt-in settings will
            be applied to this subscription.
        tier:
          $ref: '#/components/schemas/SubscriptionsCreateRequestTier'
          nullable: true
          description: The tier for this subscription.
        premium_tiers:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            An array of premium tier names to assign to this subscription. When
            provided, the subscription will be assigned to premium tiers
            matching these names. Can be combined with `premium_tier_ids` to
            include tiers from both (duplicates are removed). Takes precedence
            over the `tier` parameter.
        premium_tier_ids:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            An array of premium tier IDs to assign to this subscription. When
            provided, the subscription will be assigned to these specific
            premium tiers. Can be combined with `premium_tiers` to include tiers
            from both (duplicates are removed). Takes precedence over the `tier`
            parameter.
        stripe_customer_id:
          $ref: '#/components/schemas/OptionalStripeCustomerId'
          nullable: true
          description: The Stripe customer ID for this subscription.
        automation_ids:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Enroll the subscriber into automations after their subscription has
            been created. Requires the automations to have an active *Add by
            API* trigger.
        newsletter_list_ids:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            An array of newsletter list prefixed IDs to subscribe the new
            subscription to. The newsletter lists must belong to the same
            publication. <Badge intent="warning" minimal outlined>Beta</Badge>
      required:
        - email
    PostAudience:
      title: PostAudience
      type: string
      enum:
        - free
        - premium
        - both
      description: >-
        The audience that the post is available to on the web. Only applicable
        if the platform is `web` or `both`.
    PostPlatform:
      title: PostPlatform
      type: string
      enum:
        - web
        - email
        - both
      description: The platform that the post is or will be published to.
    PostCreate:
      title: PostCreate
      type: object
      properties:
        id:
          $ref: '#/components/schemas/PostId'
          description: The prefixed post id
      required:
        - id
    Post:
      title: Post
      type: object
      properties:
        id:
          $ref: '#/components/schemas/PostId'
          description: The prefixed post id
        subtitle:
          type: string
          description: The subtitle displayed in web views
        title:
          type: string
          description: The title displayed in web views
        authors:
          type: array
          items:
            type: string
          description: An array of author names
        created:
          type: integer
          description: >-
            The time the post was created. Measured in seconds since the Unix
            epoch
        status:
          $ref: '#/components/schemas/PostStatus'
          description: >-
            The status of the post.<br>`draft` - not been
            scheduled.<br>`confirmed` - The post will be active after the
            `scheduled_at`.<br>`archived` - The post is no longer active.
        publish_date:
          type: integer
          nullable: true
          description: >-
            The time the post was set to be published. Measured in seconds since
            the Unix epoch
        displayed_date:
          type: integer
          nullable: true
          description: >-
            The time displayed in place of the `publish_date`. Measured in
            seconds since the Unix epoch
        split_tested:
          type: boolean
          description: >-
            A flag to indicate if a split test was done. Only applicable to
            email posts.
        subject_line:
          type: string
          description: >-
            The email subject line. In cases of A/B Testing, this will be
            adjusted to the winning subject line.
        preview_text:
          type: string
          description: The email preview text
        slug:
          type: string
          description: The web slug where this post can be accessed.
        thumbnail_url:
          type: string
          description: >-
            The URL of the thumbnail. Defaults to the Publication logo if not
            set.
        web_url:
          type: string
          description: >-
            The full URL where this post can be accessed on the web. Only
            applicable if the platform is `web` or `both`.
        audience:
          $ref: '#/components/schemas/PostAudience'
          description: >-
            The audience that the post is available to on the web. Only
            applicable if the platform is `web` or `both`.
        platform:
          $ref: '#/components/schemas/PostPlatform'
          description: The platform that the post is or will be published to.
        content_tags:
          type: array
          items:
            type: string
          description: All content tags that were associated with the post.
        meta_default_description:
          type: string
          nullable: true
          description: >-
            Meta tag description for the post, called SEO Description in the
            admin UI
        meta_default_title:
          type: string
          nullable: true
          description: meta tag title for the post, called SEO Title in the admin UI
        newsletter_list_id:
          type: string
          nullable: true
          description: >-
            The prefixed ID of the newsletter list this post is associated with.
            When set, the post targets only subscribers of this newsletter list.
            <Badge intent="warning" minimal outlined>Beta</Badge>
        hidden_from_feed:
          type: boolean
          description: A flag to indicate if the post is hidden from the website feed.
        enforce_gated_content:
          type: boolean
          description: >-
            A flag to indicate if the post enforces gated content for
            non-subscribers.
        email_capture_popup:
          type: boolean
          description: A flag to indicate if popup email capture is enabled for this post.
        content:
          $ref: '#/components/schemas/PostContent'
          nullable: true
        stats:
          $ref: '#/components/schemas/PostStats'
          nullable: true
      required:
        - id
        - subtitle
        - title
        - authors
        - created
        - status
        - split_tested
        - subject_line
        - preview_text
        - slug
        - thumbnail_url
        - web_url
        - audience
        - platform
        - content_tags
        - hidden_from_feed
        - enforce_gated_content
        - email_capture_popup
    PostClickStatsEmail:
      title: PostClickStatsEmail
      type: object
      description: >-
        URL stats scoped only to email recipients. Not relevant for posts
        published only to web
      properties:
        clicks:
          type: integer
          nullable: true
        unique_clicks:
          type: integer
          nullable: true
        verified_clicks:
          type: integer
          nullable: true
          description: >-
            Total number of verified human email clicks on this URL. Verified
            clicks have passed bot detection and are confirmed to be from real
            subscribers.
        unique_verified_clicks:
          type: integer
          nullable: true
          description: >-
            Unique number of verified human email clicks on this URL. Only
            counts the first verified click per subscriber.
        click_through_rate:
          type: number
          format: double
          nullable: true
          description: >-
            The percentage of email clicks on the URL compared to the total
            number of recipients
    PostClickStatsWeb:
      title: PostClickStatsWeb
      type: object
      description: >-
        Stats scoped only to web views. Not relevant for posts published only to
        email
      properties:
        clicks:
          type: integer
          nullable: true
        unique_clicks:
          type: integer
          nullable: true
        click_through_rate:
          type: number
          format: double
          nullable: true
          description: >-
            The percentage of clicks on the URL compared to the total number of
            web views
    ClickStats:
      title: ClickStats
      type: object
      description: Details about specific URL's click stats from a post.
      properties:
        url:
          type: string
          nullable: true
          description: The URL the stats are for
        base_url:
          type: string
          nullable: true
          description: >-
            The canonical URL with all query parameters and fragments removed.
            Derived by stripping everything after the '?' and '#' characters.
            Preserves the protocol, host (including casing), port, and path
            exactly as they appear in the original URL. Guaranteed to be present
            whenever url is present, enabling grouping of clicks by destination
            regardless of tracking parameters.
        email:
          $ref: '#/components/schemas/PostClickStatsEmail'
          nullable: true
          description: >-
            URL stats scoped only to email recipients. Not relevant for posts
            published only to web
        web:
          $ref: '#/components/schemas/PostClickStatsWeb'
          nullable: true
          description: >-
            Stats scoped only to web views. Not relevant for posts published
            only to email
        total_clicks:
          type: integer
          nullable: true
        total_unique_clicks:
          type: integer
          nullable: true
        total_click_through_rate:
          type: number
          format: double
          nullable: true
          description: >-
            The percentage of clicks on the URL compared to the total number of
            recipients and web views
    FreePostContent:
      title: FreePostContent
      type: object
      description: The requested free post HTML. This HTML has paywalls enforced.
      properties:
        web:
          type: string
          nullable: true
          description: The web HTML rendered to a free or annonomous reader.
        email:
          type: string
          nullable: true
          description: The email HTML rendered to a free reader.
        rss:
          type: string
          nullable: true
          description: The HTML that is rendered in RSS feeds.
    PremiumPostContent:
      title: PremiumPostContent
      type: object
      description: >-
        The requested premium post HTML. This HTML does not have paywalls
        enforced.
      properties:
        web:
          type: string
          nullable: true
          description: The website HTML rendered to a free reader
        email:
          type: string
          nullable: true
          description: The email HTML rendered to a premium reader
    PostContent:
      title: PostContent
      type: object
      description: >-
        Optional html content for a post. Retrievable by including any of
        `expand: [free_web_content, free_email_content, free_rss_content,
        premium_web_content, premium_email_content]` in the post request body.


        **Note:** Generating HTML is slow. We recommend only requesting the HTML
        versions you need at the time.
      properties:
        free:
          $ref: '#/components/schemas/FreePostContent'
          nullable: true
          description: The requested free post HTML. This HTML has paywalls enforced.
        premium:
          $ref: '#/components/schemas/PremiumPostContent'
          nullable: true
          description: >-
            The requested premium post HTML. This HTML does not have paywalls
            enforced.
    PostStatsEmail:
      title: PostStatsEmail
      type: object
      description: >-
        Stats scoped only to email recipients. Not relevant for posts published
        only to web
      properties:
        recipients:
          type: integer
          nullable: true
          description: Total number of email recipients
        delivered:
          type: integer
          nullable: true
          description: Total number of emails delivered
        opens:
          type: integer
          nullable: true
          description: Total number of email opens
        unique_opens:
          type: integer
          minimum: 0
          nullable: true
          description: Total number of unique email opens
        open_rate:
          type: number
          format: double
          nullable: true
          description: The percentage of emails that have been opened
        clicks:
          type: integer
          nullable: true
          description: Total number of email clicks
        unique_clicks:
          type: integer
          nullable: true
          description: Unique number of email clicks
        verified_clicks:
          type: integer
          nullable: true
          description: >-
            Total number of verified human email clicks across all URLs in this
            post. Verified clicks have passed bot detection and are confirmed to
            be from real subscribers.
        unique_verified_clicks:
          type: integer
          nullable: true
          description: >-
            Unique number of verified human email clicks across all URLs in this
            post. Only counts the first verified click per subscriber.
        click_rate:
          type: number
          format: double
          nullable: true
          description: The percentage of emails that have been clicked
        unsubscribes:
          type: integer
          nullable: true
          description: Total number of email unsubscribes
        spam_reports:
          type: integer
          minimum: 0
          nullable: true
          description: The number of subscribers that reported this post email as spam
    PostStatsWeb:
      title: PostStatsWeb
      type: object
      description: >-
        Stats scoped only to web views. Not relevant for posts published only to
        email
      properties:
        views:
          type: integer
          nullable: true
          description: Total number of web views
        clicks:
          type: integer
          nullable: true
          description: Total number of web clicks
    PostStats:
      title: PostStats
      type: object
      description: >-
        Optional list of stats for a post. Retrievable by including `expand:
        [stats]` in the post request body. <br><br> **Note:** If a timeout
        occurs while aggregating stats, subsequent requests may return
        consolidated click metrics rather than individual raw click metrics.
      properties:
        email:
          $ref: '#/components/schemas/PostStatsEmail'
          nullable: true
          description: >-
            Stats scoped only to email recipients. Not relevant for posts
            published only to web
        web:
          $ref: '#/components/schemas/PostStatsWeb'
          nullable: true
          description: >-
            Stats scoped only to web views. Not relevant for posts published
            only to email
        clicks:
          type: array
          items:
            $ref: '#/components/schemas/ClickStats'
          nullable: true
          description: An array of click statistics for each URL in the post
    Publication:
      title: Publication
      type: object
      properties:
        id:
          $ref: '#/components/schemas/PublicationId'
          description: A unique prefixed id of the publication
        name:
          type: string
          description: The name of the publication
        organization_name:
          type: string
          description: The name of the organization
        referral_program_enabled:
          type: boolean
          description: >-
            A boolean field indicating whether the referral program is active
            for this publication.
        created:
          type: number
          format: double
          description: >-
            The time that the publication was created. Measured in seconds since
            the Unix epoch
        stats:
          $ref: '#/components/schemas/PublicationStats'
          nullable: true
      required:
        - id
        - name
        - organization_name
        - referral_program_enabled
        - created
    ActiveSubscriptionCount:
      title: ActiveSubscriptionCount
      oneOf:
        - type: integer
        - type: boolean
      description: Total number of active free and premium subscriptions
    ActivePremiumSubscriptionCount:
      title: ActivePremiumSubscriptionCount
      oneOf:
        - type: integer
        - type: boolean
      description: Total number of active premium/paid subscriptions
    ActiveFreeSubscriptionCount:
      title: ActiveFreeSubscriptionCount
      oneOf:
        - type: integer
        - type: boolean
      description: Total number of active free subscriptions
    AverageOpenRate:
      title: AverageOpenRate
      oneOf:
        - type: number
          format: double
        - type: boolean
      description: The publications historical average open rate
    AverageClickRate:
      title: AverageClickRate
      oneOf:
        - type: number
          format: double
        - type: boolean
      description: The publications historical average click through rate
    TotalEmailsSent:
      title: TotalEmailsSent
      oneOf:
        - type: integer
        - type: boolean
      description: Total number of emails sent
    TotalUniqueOpens:
      title: TotalUniqueOpens
      oneOf:
        - type: integer
        - type: boolean
      description: >-
        Total number of uniquely opened emails. Only counts the first open for
        each subscriber.
    TotalClicks:
      title: TotalClicks
      oneOf:
        - type: integer
        - type: boolean
      description: The total number of links clicked from emails.
    PublicationStats:
      title: PublicationStats
      type: object
      description: >-
        Optional list of stats for a publication. Retrievable by including an
        `expand` array in the publication request body. Add `"stats"` to the
        array to retrieve all, or add individual stats (prefaced with `stat_`)
        to only retrieve specific ones.


        Examples:

        {
          "expand": ["stats"]
        }


        {
          "expand": ["stat_active_subscriptions", "stat_average_click_rate"]
        }
      properties:
        active_subscriptions:
          $ref: '#/components/schemas/ActiveSubscriptionCount'
          nullable: true
          description: Total number of active free and premium subscriptions
        active_premium_subscriptions:
          $ref: '#/components/schemas/ActivePremiumSubscriptionCount'
          nullable: true
          description: Total number of active premium/paid subscriptions
        active_free_subscriptions:
          $ref: '#/components/schemas/ActiveFreeSubscriptionCount'
          nullable: true
          description: Total number of active free subscriptions
        average_open_rate:
          $ref: '#/components/schemas/AverageOpenRate'
          nullable: true
          description: The publications historical average open rate
        average_click_rate:
          $ref: '#/components/schemas/AverageClickRate'
          nullable: true
          description: The publications historical average click through rate
        total_sent:
          $ref: '#/components/schemas/TotalEmailsSent'
          nullable: true
          description: Total number of emails sent
        total_unique_opened:
          $ref: '#/components/schemas/TotalUniqueOpens'
          nullable: true
          description: >-
            Total number of uniquely opened emails. Only counts the first open
            for each subscriber.
        total_clicked:
          $ref: '#/components/schemas/TotalClicks'
          nullable: true
          description: The total number of links clicked from emails.
    SegmentType:
      title: SegmentType
      type: string
      enum:
        - dynamic
        - static
        - manual
        - all
      description: >-
        The type of segment.<br>`dynamic` - The segment is recalculated at set
        intervals.<br>`static` - The segment is calculated once at
        creation.<br>`manual` - The segment is not calculated at all. The
        results are created via CSV.
    SegmentStatus:
      title: SegmentStatus
      type: string
      enum:
        - pending
        - processing
        - completed
        - failed
      description: >-
        The status of the segment's most recent calculation.<br>`pending` - The
        segment has not been calculated yet.<br>`processing` - The calculation
        is in progress, and has not completed.<br>`completed` - The calculation
        was successful.<br>`failed` - Something went wrong during the
        calculation.
    Segment:
      title: Segment
      type: object
      description: The segment object. To expand results, see the results endpoint.
      properties:
        id:
          $ref: '#/components/schemas/SegmentId'
          description: The prefixed ID of the segment.
        name:
          type: string
          description: The name of the segment.
        type:
          $ref: '#/components/schemas/SegmentType'
          description: >-
            The type of segment.<br>`dynamic` - The segment is recalculated at
            set intervals.<br>`static` - The segment is calculated once at
            creation.<br>`manual` - The segment is not calculated at all. The
            results are created via CSV.
        last_calculated:
          type: integer
          nullable: true
          description: >-
            The time the Segment was last calculated. Measured in seconds since
            the Unix epoch
        total_results:
          type: integer
          description: >-
            The total number of subscriptions that belong in the segment from
            the last calculation.
        status:
          $ref: '#/components/schemas/SegmentStatus'
          description: >-
            The status of the segment's most recent calculation.<br>`pending` -
            The segment has not been calculated yet.<br>`processing` - The
            calculation is in progress, and has not completed.<br>`completed` -
            The calculation was successful.<br>`failed` - Something went wrong
            during the calculation.
        active:
          type: boolean
          description: >-
            Dynamic segments are marked inactive if they haven't been used in a
            specific period of time. Inactive segments will not automatically be
            recalculated.
        stats:
          $ref: '#/components/schemas/SegmentStats'
          nullable: true
      required:
        - id
        - name
        - type
        - total_results
        - status
        - active
    SegmentStats:
      title: SegmentStats
      type: object
      properties:
        open_rate:
          type: number
          format: double
          description: The average open rate of the subscribers in the segment.
        total_sent:
          type: integer
          description: The total number of emails sent to the subscribers in the segment.
        percentage_premium_subscribers:
          type: number
          format: double
          description: >-
            The percentage of subscribers in this segment who are premium in any
            tier.
        percentage_subscribers_with_referrals:
          type: number
          format: double
          description: >-
            The percentage of subscribers in this segment who have referred at
            least one other subscriber.
        unique_emails_clicked:
          type: integer
          description: >-
            The total number of unique emails clicked by subscribers in the
            segment.
        total_delivered:
          type: integer
          description: The total number of emails delivered to subscribers in the segment.
        total_referrals:
          type: integer
          description: The total number of referrals from subscribers in the segment.
        unsubscribed_rate:
          type: number
          format: double
          description: The percentage of subscribers in this segment who have unsubscribed.
        total_subscribers:
          type: integer
          description: The total number of subscribers in the segment.
        clickthrough_rate:
          type: number
          format: double
          description: The average clickthrough rate of the subscribers in the segment.
        unsubscribed_count:
          type: integer
          description: The total number of subscribers in the segment who are unsubscribed.
        unique_emails_opened:
          type: integer
          description: >-
            The total number of unique emails opened by subscribers in the
            segment.
        premium_subscribers:
          type: integer
          description: The total number of premium subscribers in the segment.
        average_referrals_per_subscriber:
          type: number
          format: double
          description: The average number of referrals per subscriber in the segment.
      required:
        - open_rate
        - total_sent
        - percentage_premium_subscribers
        - percentage_subscribers_with_referrals
        - unique_emails_clicked
        - total_delivered
        - total_referrals
        - unsubscribed_rate
        - total_subscribers
        - clickthrough_rate
        - unsubscribed_count
        - unique_emails_opened
        - premium_subscribers
        - average_referrals_per_subscriber
    AutomationStatus:
      title: AutomationStatus
      type: string
      enum:
        - running
        - finishing
        - inactive
        - live
        - draft
    AutomationTriggerEvent:
      title: AutomationTriggerEvent
      type: string
      enum:
        - api
        - downgrade
        - email_submission
        - form_submission
        - manual
        - poll_submission
        - purchased_product
        - referral_action
        - segment_action
        - signup
        - unengaged
        - upgrade
    Automation:
      title: Automation
      type: object
      properties:
        id:
          $ref: '#/components/schemas/AutomationId'
          description: A unique prefixed id of the automation
        status:
          $ref: '#/components/schemas/AutomationStatus'
        name:
          type: string
        trigger_events:
          type: array
          items:
            $ref: '#/components/schemas/AutomationTriggerEvent'
          description: The types of events that can trigger the automation.
        description:
          type: string
          nullable: true
        stats:
          $ref: '#/components/schemas/AutomationStats'
          nullable: true
      required:
        - id
        - status
        - name
        - trigger_events
    AutomationStats:
      title: AutomationStats
      type: object
      description: >-
        Optional statistics for an automation. Retrievable by including `expand:
        [stats]` in the automation request.
      properties:
        journeys:
          $ref: '#/components/schemas/AutomationStatsJourneys'
          nullable: true
          description: Journey counts for the automation
        email:
          $ref: '#/components/schemas/AutomationStatsEmail'
          nullable: true
          description: Aggregate email engagement statistics
    AutomationStatsJourneys:
      title: AutomationStatsJourneys
      type: object
      description: Journey counts for an automation.
      properties:
        running:
          type: integer
          nullable: true
          description: Number of journeys currently in progress
        completed:
          type: integer
          nullable: true
          description: Number of completed journeys
        total:
          type: integer
          nullable: true
          description: Total number of journeys
    AutomationStatsEmail:
      title: AutomationStatsEmail
      type: object
      description: Aggregate email engagement statistics for an automation.
      properties:
        recipients:
          type: integer
          nullable: true
          description: Total number of email recipients across all emails
        delivered:
          type: integer
          nullable: true
          description: Total number of emails delivered
        opens:
          type: integer
          nullable: true
          description: Total number of email opens
        unique_opens:
          type: integer
          nullable: true
          description: Total number of unique email opens
        open_rate:
          type: number
          format: double
          nullable: true
          description: The percentage of emails that have been opened
        clicks:
          type: integer
          nullable: true
          description: Total number of email clicks
        unique_clicks:
          type: integer
          nullable: true
          description: Unique number of email clicks
        click_rate:
          type: number
          format: double
          nullable: true
          description: The percentage of emails that have been clicked
        unsubscribes:
          type: integer
          nullable: true
          description: Total number of email unsubscribes
        spam_reports:
          type: integer
          nullable: true
          description: The number of subscribers that reported emails as spam
    AutomationJourneyStatus:
      title: AutomationJourneyStatus
      type: string
      enum:
        - in_progress
        - completed
        - exited_early
        - manually_removed
    AutomationJourney:
      title: AutomationJourney
      type: object
      description: A subscribers' journey through an automation flow.
      properties:
        id:
          $ref: '#/components/schemas/AutomationJourneyId'
          description: The prefixed automation journey id
        automation_id:
          $ref: '#/components/schemas/AutomationId'
          description: The prefixed automation id
        subscription_id:
          $ref: '#/components/schemas/SubscriptionId'
          nullable: true
        email:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/AutomationJourneyStatus'
        started_at:
          type: integer
          nullable: true
          description: >-
            The time that the subscriber started their flow through the
            automation. Measured in seconds since the Unix epoch.
        completed_at:
          type: integer
          nullable: true
          description: >-
            The time that the subscriber finished their flow through the
            automation. Measured in seconds since the Unix epoch.
      required:
        - id
        - automation_id
        - status
    RequestDirection:
      title: RequestDirection
      type: string
      enum:
        - asc
        - desc
      description: The direction of the request. Defaults to `asc`.
    AdvertisementOpportunity:
      title: AdvertisementOpportunity
      type: object
      properties:
        id:
          type: string
          description: The ID of the opportunity.
        advertiser_name:
          type: string
          description: The name of the advertiser.
        payout_rate:
          type: string
          description: The amount you'll earn.
        advertisement_kind:
          type: string
          description: What kind of an ad it is. With or without logo.
        send_by_window_start_at:
          type: integer
          description: >-
            The earliest this ad can be sent. Measured in seconds since the Unix
            epoch.
        send_by_window_end_at:
          type: integer
          description: >-
            When this ad needs to be sent by. Measured in seconds since the Unix
            epoch.
      required:
        - id
        - advertiser_name
        - payout_rate
        - advertisement_kind
        - send_by_window_start_at
        - send_by_window_end_at
    AdvertisementOpportunitiesGetResponse:
      title: AdvertisementOpportunitiesGetResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AdvertisementOpportunity'
          description: A list of post templates available for this publication.
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 2
      required:
        - data
        - total_results
    AuthorType:
      title: AuthorType
      type: string
      enum:
        - user
        - guest_author
    AuthorSocialMediaLinks:
      title: AuthorSocialMediaLinks
      type: object
      properties:
        twitter_handle:
          type: string
          nullable: true
        facebook_url:
          type: string
          nullable: true
        instagram_url:
          type: string
          nullable: true
        linkedin_url:
          type: string
          nullable: true
        youtube_url:
          type: string
          nullable: true
        tiktok_url:
          type: string
          nullable: true
        discord_url:
          type: string
          nullable: true
        bluesky_url:
          type: string
          nullable: true
        rss_url:
          type: string
          nullable: true
    Author:
      title: Author
      type: object
      properties:
        id:
          type: string
          description: The UUID of the author.
        type:
          $ref: '#/components/schemas/AuthorType'
          description: The author type.
        name:
          type: string
          description: The author display name.
        bio:
          type: string
          nullable: true
          description: The biography text for the author.
        bio_image_url:
          type: string
          nullable: true
          description: The profile image URL for the author.
        social_media_links:
          $ref: '#/components/schemas/AuthorSocialMediaLinks'
      required:
        - id
        - type
        - name
        - social_media_links
    AuthorsListResponse:
      title: AuthorsListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Author'
          description: A list of authors available for this publication.
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
          example: 10
        page:
          type: integer
          minimum: 0
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 1
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    AuthorsGetResponse:
      title: AuthorsGetResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Author'
      required:
        - data
    AutomationJourneysGetRequestStatus:
      title: AutomationJourneysGetRequestStatus
      type: string
      enum:
        - in_progress
        - completed
        - exited_early
        - all
    AutomationJourneysResponse:
      title: AutomationJourneysResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AutomationJourney'
      required:
        - data
    AutomationJourneysIndexResponse:
      title: AutomationJourneysIndexResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AutomationJourney'
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
          example: 10
        page:
          type: integer
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 2
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    AutomationsListRequestExpandItem:
      title: AutomationsListRequestExpandItem
      type: string
      enum:
        - stats
    AutomationsListResponse:
      title: AutomationsListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Automation'
          nullable: true
        limit:
          type: integer
          nullable: true
          description: >-
            The limit placed on the results. If no limit was specified in the
            request,this defaults to 10.
        page:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
        total_results:
          type: integer
          nullable: true
          description: The total number of results from all pages.
        total_pages:
          type: integer
          nullable: true
          description: The total number of pages.
    AutomationsGetRequestExpandItem:
      title: AutomationsGetRequestExpandItem
      type: string
      enum:
        - stats
    AutomationsGetResponse:
      title: AutomationsGetResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Automation'
          nullable: true
    AutomationEmailsListResponse:
      title: AutomationEmailsListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AutomationEmail'
        limit:
          type: integer
          nullable: true
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
        has_more:
          type: boolean
          nullable: true
          description: >-
            **Cursor pagination only**: Indicates whether there are more results
            available after the current page.
        next_cursor:
          type: string
          nullable: true
          description: >-
            **Cursor pagination only**: The cursor token to use for fetching the
            next page of results. This will be null if has_more is false.
        page:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            **Offset pagination only**: The page number the results are from.
            Only present when using deprecated offset-based pagination.
        total_results:
          type: integer
          nullable: true
          description: The total number of results from all pages.
        total_pages:
          type: integer
          nullable: true
          description: The total number of pages.
      required:
        - data
    AutomationEmail:
      title: AutomationEmail
      type: object
      description: An email message within an automation.
      properties:
        id:
          type: string
          description: The unique ID of the email message
        automation_step_id:
          type: string
          description: The unique ID of the automation step this email belongs to
        subject_line:
          type: string
          description: The email subject line
        preview_text:
          type: string
          description: The email preview text
        status:
          type: string
          description: >-
            The status of the email message. `active` - The email is active and
            will be sent. `inactive` - The email is inactive.
        first_sent_at:
          type: integer
          nullable: true
          description: >-
            The time the email was first sent. Measured in seconds since the
            Unix epoch
        last_sent_at:
          type: integer
          nullable: true
          description: >-
            The time the email was last sent. Measured in seconds since the Unix
            epoch
        created_at:
          type: integer
          description: >-
            The time the email was created. Measured in seconds since the Unix
            epoch
        stats:
          $ref: '#/components/schemas/AutomationEmailStats'
          nullable: true
      required:
        - id
        - automation_step_id
        - subject_line
        - preview_text
        - status
        - created_at
    AutomationEmailStats:
      title: AutomationEmailStats
      type: object
      description: Statistics for an automation email message.
      properties:
        email:
          $ref: '#/components/schemas/AutomationEmailStatsEmail'
          nullable: true
          description: Stats scoped to email recipients
        clicks:
          type: array
          items:
            $ref: '#/components/schemas/AutomationEmailStatsClicks'
          nullable: true
          description: An array of click statistics for each URL in the email
    AutomationEmailStatsEmail:
      title: AutomationEmailStatsEmail
      type: object
      description: Email engagement statistics for an automation email.
      properties:
        recipients:
          type: integer
          nullable: true
          description: Total number of email recipients
        delivered:
          type: integer
          nullable: true
          description: Total number of emails delivered
        opens:
          type: integer
          nullable: true
          description: Total number of email opens
        unique_opens:
          type: integer
          minimum: 0
          nullable: true
          description: Total number of unique email opens
        open_rate:
          type: number
          format: double
          nullable: true
          description: The percentage of emails that have been opened
        clicks:
          type: integer
          nullable: true
          description: Total number of email clicks
        unique_clicks:
          type: integer
          nullable: true
          description: Unique number of email clicks
        click_rate:
          type: number
          format: double
          nullable: true
          description: The percentage of emails that have been clicked
        unsubscribes:
          type: integer
          nullable: true
          description: Total number of email unsubscribes
        spam_reports:
          type: integer
          minimum: 0
          nullable: true
          description: The number of subscribers that reported this email as spam
    AutomationEmailStatsClicks:
      title: AutomationEmailStatsClicks
      type: object
      properties:
        url:
          type: string
          nullable: true
          description: The URL the stats are for
        total_clicks:
          type: integer
          nullable: true
        total_unique_clicks:
          type: integer
          nullable: true
        total_click_through_rate:
          type: number
          format: double
          nullable: true
          description: >-
            The percentage of clicks on the URL compared to the total number of
            unique opens
    BulkSubscriptionsCreateRequestTier:
      title: BulkSubscriptionsCreateRequestTier
      type: string
      enum:
        - free
        - premium
      description: The tier for this subscription.
    BulkSubscriptionCreateResponse:
      title: BulkSubscriptionCreateResponse
      type: object
      description: The response containing the import ID
      properties:
        message:
          type: string
          description: The result of the create request
          example: Bulk Subscription Create Request Sent.
        import_id:
          type: string
          description: >-
            The database ID of the import object created from the Bulk
            Subscription Create request
          example: 00000000-0000-0000-0000-000000000000
      required:
        - message
        - import_id
    BulkSubscriptionUpdatesListResponseDataItemType:
      title: BulkSubscriptionUpdatesListResponseDataItemType
      type: string
      enum:
        - status
        - bulk
      description: The type of update (status or bulk)
    BulkSubscriptionUpdatesListResponseDataItemStatus:
      title: BulkSubscriptionUpdatesListResponseDataItemStatus
      type: string
      enum:
        - pending
        - processing
        - complete
        - failed
      description: The status of the update
    BulkSubscriptionUpdatesListResponseDataItem:
      title: BulkSubscriptionUpdatesListResponseDataItem
      type: object
      properties:
        id:
          type: string
          nullable: true
          description: The ID of the update object
        type:
          $ref: '#/components/schemas/BulkSubscriptionUpdatesListResponseDataItemType'
          nullable: true
          description: The type of update (status or bulk)
        params:
          type: string
          nullable: true
          description: The parameters passed in for the update
        status:
          $ref: >-
            #/components/schemas/BulkSubscriptionUpdatesListResponseDataItemStatus
          nullable: true
          description: The status of the update
        publication_id:
          $ref: '#/components/schemas/PublicationId'
          nullable: true
          description: The publication ID associated with this update
        failure_reason:
          type: string
          nullable: true
          description: If the job as a whole fails, this will detail the errors encountered
        completed:
          type: integer
          nullable: true
          description: The timestamp of the job's completion
        created:
          type: integer
          nullable: true
          description: The timestamp of the job's creation
        updated:
          type: integer
          nullable: true
          description: The timestamp of the job's update
        error_log:
          type: array
          items:
            type: string
          nullable: true
          description: An array of errors encountered for individual updates within the job
    BulkSubscriptionUpdatesListResponse:
      title: BulkSubscriptionUpdatesListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BulkSubscriptionUpdatesListResponseDataItem'
          nullable: true
          description: An array of Subscription Update objects
    BulkSubscriptionUpdatesGetResponseDataType:
      title: BulkSubscriptionUpdatesGetResponseDataType
      type: string
      enum:
        - bulk
        - status
      description: The type of update (status or bulk)
    BulkSubscriptionUpdatesGetResponseDataStatus:
      title: BulkSubscriptionUpdatesGetResponseDataStatus
      type: string
      enum:
        - pending
        - processing
        - complete
        - failed
      description: The status of the update
    BulkSubscriptionUpdatesGetResponseData:
      title: BulkSubscriptionUpdatesGetResponseData
      type: object
      properties:
        id:
          type: string
          nullable: true
          description: The ID of the update object
        type:
          $ref: '#/components/schemas/BulkSubscriptionUpdatesGetResponseDataType'
          nullable: true
          description: The type of update (status or bulk)
        params:
          type: string
          nullable: true
          description: The parameters passed in for the update
        status:
          $ref: '#/components/schemas/BulkSubscriptionUpdatesGetResponseDataStatus'
          nullable: true
          description: The status of the update
        publication_id:
          $ref: '#/components/schemas/PublicationId'
          nullable: true
          description: The publication ID associated with this update
        failure_reason:
          type: string
          nullable: true
          description: If the job as a whole fails, this will detail the errors encountered
        completed:
          type: integer
          nullable: true
          description: The timestamp of the job's completion
        created:
          type: integer
          nullable: true
          description: The timestamp of the job's creation
        updated:
          type: integer
          nullable: true
          description: The timestamp of the job's update
        error_log:
          type: array
          items:
            type: string
          nullable: true
          description: An array of errors encountered for individual updates within the job
    BulkSubscriptionUpdatesGetResponse:
      title: BulkSubscriptionUpdatesGetResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BulkSubscriptionUpdatesGetResponseData'
          nullable: true
    SubscriptionsPutRequestSubscriptionsItemTier:
      title: SubscriptionsPutRequestSubscriptionsItemTier
      type: string
      enum:
        - free
        - premium
      description: The Tier of the Subscription (not required)
    SubscriptionsPutRequestSubscriptionsItemCustomFieldsItem:
      title: SubscriptionsPutRequestSubscriptionsItemCustomFieldsItem
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: The name of the existing custom field
        value:
          $ref: '#/components/schemas/CustomFieldDataType'
          nullable: true
          description: The value of the custom field
        delete:
          type: boolean
          nullable: true
          description: >-
            A boolean value to specify whether to delete this custom field entry
            from the subscription
    SubscriptionsPutRequestSubscriptionsItem:
      title: SubscriptionsPutRequestSubscriptionsItem
      type: object
      properties:
        subscription_id:
          $ref: '#/components/schemas/SubscriptionId'
        tier:
          $ref: '#/components/schemas/SubscriptionsPutRequestSubscriptionsItemTier'
          nullable: true
          description: The Tier of the Subscription (not required)
        stripe_customer_id:
          $ref: '#/components/schemas/OptionalStripeCustomerId'
          nullable: true
          description: The Stripe Customer ID of the subscription (not required)
        unsubscribe:
          type: boolean
          nullable: true
          description: >-
            A boolean value specifying whether to unsubscribe this subscription
            from the publication (not required)
        custom_fields:
          type: array
          items:
            $ref: >-
              #/components/schemas/SubscriptionsPutRequestSubscriptionsItemCustomFieldsItem
          nullable: true
          description: An array of custom field objects to update
      required:
        - subscription_id
    SubscriptionsPatchRequestSubscriptionsItemTier:
      title: SubscriptionsPatchRequestSubscriptionsItemTier
      type: string
      enum:
        - free
        - premium
      description: The Tier of the Subscription (not required)
    SubscriptionsPatchRequestSubscriptionsItemCustomFieldsItem:
      title: SubscriptionsPatchRequestSubscriptionsItemCustomFieldsItem
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: The display value of the custom field
        value:
          $ref: '#/components/schemas/CustomFieldDataType'
          nullable: true
          description: The value of the custom field
        delete:
          type: boolean
          nullable: true
          description: >-
            A boolean value to specify whether to delete this custom field entry
            from the subscription
    SubscriptionsPatchRequestSubscriptionsItem:
      title: SubscriptionsPatchRequestSubscriptionsItem
      type: object
      properties:
        subscription_id:
          $ref: '#/components/schemas/SubscriptionId'
        tier:
          $ref: '#/components/schemas/SubscriptionsPatchRequestSubscriptionsItemTier'
          nullable: true
          description: The Tier of the Subscription (not required)
        stripe_customer_id:
          $ref: '#/components/schemas/OptionalStripeCustomerId'
          nullable: true
          description: The Stripe Customer ID of the subscription (not required)
        unsubscribe:
          type: boolean
          nullable: true
          description: >-
            A boolean value specifying whether to unsubscribe this subscription
            from the publication (not required)
        custom_fields:
          type: array
          items:
            $ref: >-
              #/components/schemas/SubscriptionsPatchRequestSubscriptionsItemCustomFieldsItem
          nullable: true
          description: An array of custom field objects to update
      required:
        - subscription_id
    ConditionSetStatus:
      title: ConditionSetStatus
      type: string
      enum:
        - active
        - archived
    ConditionSetPurpose:
      title: ConditionSetPurpose
      type: string
      enum:
        - dynamic_content
      description: The purpose of the condition set, indicating its intended use.
    ConditionSetStats:
      title: ConditionSetStats
      type: object
      properties:
        active_subscriber_count:
          type: integer
          description: >-
            Count of active subscribers matching this condition set, calculated
            synchronously at request time.
      required:
        - active_subscriber_count
    ConditionSetListItem:
      title: ConditionSetListItem
      type: object
      properties:
        id:
          type: string
          description: The UUID of the condition set.
        name:
          type: string
          description: The display name of the condition set.
        status:
          $ref: '#/components/schemas/ConditionSetStatus'
          description: Whether the condition set is currently active or has been archived.
        created:
          type: integer
          description: >-
            The time the condition set was created. Measured in seconds since
            the Unix epoch.
        updated:
          type: integer
          description: >-
            The time the condition set was last updated. Measured in seconds
            since the Unix epoch.
        purpose:
          $ref: '#/components/schemas/ConditionSetPurpose'
          description: The purpose of the condition set, indicating its intended use.
      required:
        - id
        - name
        - status
        - created
        - updated
        - purpose
    ConditionSet:
      title: ConditionSet
      type: object
      properties:
        id:
          type: string
          description: The UUID of the condition set.
        name:
          type: string
          description: The display name of the condition set.
        status:
          $ref: '#/components/schemas/ConditionSetStatus'
          description: Whether the condition set is currently active or has been archived.
        created:
          type: integer
          description: >-
            The time the condition set was created. Measured in seconds since
            the Unix epoch.
        updated:
          type: integer
          description: >-
            The time the condition set was last updated. Measured in seconds
            since the Unix epoch.
        purpose:
          $ref: '#/components/schemas/ConditionSetPurpose'
          description: The purpose of the condition set, indicating its intended use.
        stats:
          $ref: '#/components/schemas/ConditionSetStats'
          nullable: true
          description: >-
            Subscriber count statistics for the condition set. Included when
            `expand[]=stats` is specified in the request.
      required:
        - id
        - name
        - status
        - created
        - updated
        - purpose
    ConditionSetShowExpandItems:
      title: ConditionSetShowExpandItems
      type: string
      enum:
        - stats
    ConditionSetsListResponse:
      title: ConditionSetsListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConditionSetListItem'
          description: An array of condition sets.
        limit:
          type: integer
          nullable: true
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
        has_more:
          type: boolean
          nullable: true
          description: >-
            **Cursor pagination only**: Indicates whether there are more results
            available after the current page. Only present when using
            cursor-based pagination.
        next_cursor:
          type: string
          nullable: true
          description: >-
            **Cursor pagination only**: The cursor token to use for fetching the
            next page of results. This will be null if has_more is false. Only
            present when using cursor-based pagination.
        total_results:
          type: integer
          nullable: true
          description: The total number of results from all pages.
      required:
        - data
    ConditionSetShowResponse:
      title: ConditionSetShowResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ConditionSet'
      required:
        - data
    CustomFieldInfo:
      title: CustomFieldInfo
      type: object
      properties:
        id:
          type: string
          nullable: true
        kind:
          $ref: '#/components/schemas/CustomFieldType'
          nullable: true
        display:
          type: string
          nullable: true
        created:
          type: integer
          nullable: true
        options:
          type: array
          items:
            type: string
          nullable: true
          description: Array of option values. Only included when kind is "list".
    CustomFieldResponse:
      title: CustomFieldResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CustomFieldInfo'
          nullable: true
    CustomFieldIndexResponse:
      title: CustomFieldIndexResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldInfo'
          nullable: true
        limit:
          type: integer
          nullable: true
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
        page:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
        total_results:
          type: integer
          nullable: true
          description: The total number of results from all pages.
        total_pages:
          type: integer
          nullable: true
          description: The total number of pages.
    CustomFieldsDeleteResponse:
      title: CustomFieldsDeleteResponse
      type: object
      properties:
        message:
          type: string
          nullable: true
    CustomFieldsPatchResponse:
      title: CustomFieldsPatchResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CustomFieldInfo'
          nullable: true
    EmailBlastsListRequestExpandItem:
      title: EmailBlastsListRequestExpandItem
      type: string
      enum:
        - stats
    EmailBlastsListRequestStatus:
      title: EmailBlastsListRequestStatus
      type: string
      enum:
        - active
        - inactive
    EmailBlastsListRequestOrderBy:
      title: EmailBlastsListRequestOrderBy
      type: string
      enum:
        - created
        - last_sent
    EmailBlastsListResponse:
      title: EmailBlastsListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EmailBlast'
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
          example: 1
        page:
          type: integer
          minimum: 0
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 1
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    EmailBlastsGetRequestExpandItem:
      title: EmailBlastsGetRequestExpandItem
      type: string
      enum:
        - stats
    EmailBlastsGetResponse:
      title: EmailBlastsGetResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/EmailBlast'
      required:
        - data
    PublicationEngagementGranularity:
      title: PublicationEngagementGranularity
      type: string
      enum:
        - day
        - week
        - month
    PublicationEngagementEmailType:
      title: PublicationEngagementEmailType
      type: string
      enum:
        - all
        - post
        - message
    NumberOfDays:
      title: NumberOfDays
      type: integer
      minimum: 1
      maximum: 31
    PublicationEngagementMetrics:
      title: PublicationEngagementMetrics
      type: object
      properties:
        date:
          type: string
          format: date
          description: >-
            The starting date of the period for which the engagement metrics are
            reported based on the selected granularity.<br><br> `day`
            granularity: The specific day.<br> `week` granularity: The Monday of
            the week.<br> `month` granularity: The first day of the month.
        total_opens:
          type: integer
          description: The total number of times emails were opened during the period.
        unique_opens:
          type: integer
          description: >-
            The number of unique subscribers who opened emails during the
            period.
        total_clicks:
          type: integer
          description: The total number of times links were clicked during the period.
        total_verified_clicks:
          type: integer
          description: >-
            The total number of times links were clicked, during the period, as
            <a
            href="https://www.beehiiv.com/support/article/28404633659159-introducing-verified-clicks-accurate-email-engagement-metrics?srsltid=AfmBOoregRzZ1N6bcwITVRA-Lo6NE06y6xNwb7WO85Gv0mrWMij-yFgb">verified
            by our system</a>.
        unique_clicks:
          type: integer
          description: >-
            The number of unique subscribers who clicked links during the
            period.
        unique_verified_clicks:
          type: integer
          description: >-
            The number of times links were clicked by unique subscribers, during
            the period, as <a
            href="https://www.beehiiv.com/support/article/28404633659159-introducing-verified-clicks-accurate-email-engagement-metrics?srsltid=AfmBOoregRzZ1N6bcwITVRA-Lo6NE06y6xNwb7WO85Gv0mrWMij-yFgb">verified
            by our system</a>.
      required:
        - date
        - total_opens
        - unique_opens
        - total_clicks
        - total_verified_clicks
        - unique_clicks
        - unique_verified_clicks
    PublicationEngagementsResponse:
      title: PublicationEngagementsResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PublicationEngagementMetrics'
          description: >-
            The list of engagement metrics for the publication within the
            specified date range and granularity. Returns an empty list if there
            is no engagement data for the specified period.
        publication_id:
          $ref: '#/components/schemas/PublicationId'
          description: >-
            The unique identifier of the publication. Passed as a path parameter
            in the request.
        granularity:
          $ref: '#/components/schemas/PublicationEngagementGranularity'
          description: The granularity at which the engagement metrics are reported.
        email_type:
          $ref: '#/components/schemas/PublicationEngagementEmailType'
          description: >-
            The email type filter applied to the engagement metrics. Defaults to
            `all`.
        start_date:
          type: string
          format: date
          description: The starting date of the engagement metrics.
          example: '2025-01-01'
        number_of_days:
          $ref: '#/components/schemas/NumberOfDays'
          description: The number of days of engagement metrics returned.
      required:
        - data
        - publication_id
        - granularity
        - email_type
        - start_date
        - number_of_days
    SubscriptionId:
      title: SubscriptionId
      type: string
      pattern: ^(sub_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the subscription.
    EmailBlastId:
      title: EmailBlastId
      type: string
      pattern: ^(blast_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the email blast.
    PublicationId:
      title: PublicationId
      type: string
      pattern: ^(pub_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the publication.
    SegmentId:
      title: SegmentId
      type: string
      pattern: ^(seg_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the segment.
    AutomationId:
      title: AutomationId
      type: string
      pattern: ^(aut_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the automation.
    AutomationJourneyId:
      title: AutomationJourneyId
      type: string
      pattern: ^(aj_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the automation journey.
    PostId:
      title: PostId
      type: string
      pattern: ^(post_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the post.
    PollId:
      title: PollId
      type: string
      pattern: ^(poll_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the poll.
    MilestoneId:
      title: MilestoneId
      type: string
      pattern: ^(mile_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the milestone.
    RewardId:
      title: RewardId
      type: string
      pattern: ^(rew_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the reward.
    TierId:
      title: TierId
      type: string
      pattern: ^(tier_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the tier.
    PriceId:
      title: PriceId
      type: string
      pattern: ^(price_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the price.
    EndpointId:
      title: EndpointId
      type: string
      pattern: ^(ep_.+)$
      description: The prefixed ID of the endpoint.
    PostTemplateId:
      title: PostTemplateId
      type: string
      pattern: ^(post_template_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the post template.
    PaywallId:
      title: PaywallId
      type: string
      pattern: ^(paywall_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the paywall.
    ExternalRssFeedId:
      title: ExternalRssFeedId
      type: string
      pattern: ^(external_rss_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the external RSS feed.
    WorkspaceId:
      title: WorkspaceId
      type: string
      pattern: ^(work_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the workspace.
    NewsletterListId:
      title: NewsletterListId
      type: string
      pattern: ^(nl_list_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the newsletter list.
    NewsletterListSubscriptionId:
      title: NewsletterListSubscriptionId
      type: string
      pattern: ^(nl_list_sub_[0-9a-fA-F\-]+)$
      description: The prefixed ID of the newsletter list subscription.
    OptionalStripeCustomerId:
      title: OptionalStripeCustomerId
      type: string
      pattern: ^(cus_[0-9a-zA-Z]+)?$
      nullable: true
      description: The prefixed ID of the Stripe customer.
    NewsletterListStatus:
      title: NewsletterListStatus
      type: string
      enum:
        - draft
        - active
        - archived
      description: The status of the newsletter list.
    NewsletterListInfo:
      title: NewsletterListInfo
      type: object
      properties:
        id:
          $ref: '#/components/schemas/NewsletterListId'
          description: The prefixed ID of the newsletter list.
        name:
          type: string
          description: The name of the newsletter list.
          example: Weekly Digest
        slug:
          type: string
          description: The URL-friendly slug of the newsletter list.
          example: weekly-digest
        description:
          type: string
          nullable: true
          description: A description of the newsletter list.
        status:
          $ref: '#/components/schemas/NewsletterListStatus'
          description: The status of the newsletter list.
        auto_subscribe:
          type: boolean
          description: Whether new subscribers are automatically subscribed to this list.
          example: false
        subscriber_count:
          type: integer
          description: The number of active subscribers on this list.
          example: 100
        created_at:
          type: integer
          description: >-
            The time the newsletter list was created. Measured in seconds since
            the Unix epoch.
          example: 1672531200
        updated_at:
          type: integer
          description: >-
            The time the newsletter list was last updated. Measured in seconds
            since the Unix epoch.
          example: 1672531200
      required:
        - id
        - name
        - slug
        - status
        - auto_subscribe
        - subscriber_count
        - created_at
        - updated_at
    NewsletterListResponse:
      title: NewsletterListResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/NewsletterListInfo'
      required:
        - data
    NewsletterListIndexResponse:
      title: NewsletterListIndexResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/NewsletterListInfo'
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
          example: 10
        page:
          type: integer
          minimum: 0
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 1
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    NewsletterListSubscriptionStatus:
      title: NewsletterListSubscriptionStatus
      type: string
      enum:
        - pending
        - active
        - inactive
        - paused
      description: The status of the newsletter list subscription.
    NewsletterListSubscriptionInfo:
      title: NewsletterListSubscriptionInfo
      type: object
      properties:
        id:
          $ref: '#/components/schemas/NewsletterListSubscriptionId'
          description: The prefixed ID of the newsletter list subscription.
        newsletter_list_id:
          $ref: '#/components/schemas/NewsletterListId'
          description: The prefixed ID of the newsletter list.
        subscription_id:
          $ref: '#/components/schemas/SubscriptionId'
          description: The prefixed ID of the subscription.
        status:
          $ref: '#/components/schemas/NewsletterListSubscriptionStatus'
          description: The status of the newsletter list subscription.
        subscribed_at:
          type: integer
          nullable: true
          description: >-
            The time the subscription was activated. Measured in seconds since
            the Unix epoch.
        unsubscribed_at:
          type: integer
          nullable: true
          description: >-
            The time the subscription was deactivated. Measured in seconds since
            the Unix epoch.
        created_at:
          type: integer
          description: >-
            The time the newsletter list subscription was created. Measured in
            seconds since the Unix epoch.
          example: 1672531200
      required:
        - id
        - newsletter_list_id
        - subscription_id
        - status
        - created_at
    NewsletterListSubscriptionResponse:
      title: NewsletterListSubscriptionResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/NewsletterListSubscriptionInfo'
      required:
        - data
    NewsletterListSubscriptionIndexResponse:
      title: NewsletterListSubscriptionIndexResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/NewsletterListSubscriptionInfo'
        limit:
          type: integer
          nullable: true
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
        has_more:
          type: boolean
          nullable: true
          description: >-
            **Cursor pagination only**: Indicates whether there are more results
            available after the current page. Only present when using
            cursor-based pagination.
        next_cursor:
          type: string
          nullable: true
          description: >-
            **Cursor pagination only**: The cursor token to use for fetching the
            next page of results. This will be null if has_more is false. Only
            present when using cursor-based pagination.
        total_results:
          type: integer
          nullable: true
          description: The total number of results from all pages.
      required:
        - data
    PollChoice:
      title: PollChoice
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the poll choice.
        label:
          type: string
          description: The text label for this choice.
      required:
        - id
        - label
    PollStats:
      title: PollStats
      type: object
      properties:
        completions:
          type: integer
          description: The total number of responses to this poll.
        vote_counts:
          type: object
          additionalProperties:
            type: integer
          description: >-
            A map of poll choice labels to the number of votes each choice
            received.
      required:
        - completions
        - vote_counts
    PollResponseItem:
      title: PollResponseItem
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the poll response.
        subscription_id:
          $ref: '#/components/schemas/SubscriptionId'
          description: The prefixed ID of the subscription that responded.
        poll_choice_id:
          type: string
          description: The UUID of the poll choice selected.
        poll_choice_label:
          type: string
          nullable: true
          description: The text label of the poll choice selected.
        created_at:
          type: integer
          description: >-
            The time the response was created. Measured in seconds since the
            Unix epoch.
        extended_feedback:
          type: string
          nullable: true
          description: Optional extended feedback provided by the subscriber.
        post_id:
          type: string
          nullable: true
          description: >-
            The prefixed ID of the post where the response was collected. Only
            included when `expand[]=post` is specified.
        post_title:
          type: string
          nullable: true
          description: >-
            The title of the post where the response was collected. Only
            included when `expand[]=post` is specified.
        post_publish_date:
          type: integer
          nullable: true
          description: >-
            The scheduled publication date of the post where the response was
            collected. Measured in seconds since the Unix epoch. Only included
            when `expand[]=post` is specified. Null if the post is not yet
            scheduled.
      required:
        - id
        - subscription_id
        - poll_choice_id
        - created_at
    Poll:
      title: Poll
      type: object
      properties:
        id:
          $ref: '#/components/schemas/PollId'
          description: The prefixed ID of the poll.
        name:
          type: string
          description: The name of the poll.
        question:
          type: string
          description: The poll question text.
        description:
          type: string
          nullable: true
          description: An optional description of the poll.
        poll_type:
          $ref: '#/components/schemas/PollType'
          description: The type of poll.
        status:
          $ref: '#/components/schemas/PollStatus'
          description: The current status of the poll.
        created_at:
          type: integer
          description: >-
            The time the poll was created. Measured in seconds since the Unix
            epoch.
        poll_choices:
          type: array
          items:
            $ref: '#/components/schemas/PollChoice'
          description: The available choices for this poll.
        trivia_answer:
          type: string
          nullable: true
          description: >-
            The correct answer for trivia-type polls. Only included when
            `expand[]=trivia_answer` is specified and the poll is of type
            trivia.
        stats:
          $ref: '#/components/schemas/PollStats'
          nullable: true
          description: >-
            Aggregate statistics for the poll. Only included when
            `expand[]=stats` is specified.
        total_responses:
          type: integer
          nullable: true
          description: >-
            Total number of responses to this poll. Only included when
            `expand[]=poll_responses` is specified.
        poll_responses:
          type: array
          items:
            $ref: '#/components/schemas/PollResponseItem'
          nullable: true
          description: >-
            Up to 10 most recent subscriber responses. Only included when
            `expand[]=poll_responses` is specified. Use
            /polls/{pollId}/responses for paginated access to all responses.
      required:
        - id
        - name
        - question
        - poll_type
        - status
        - created_at
        - poll_choices
    PollType:
      title: PollType
      type: string
      enum:
        - voting
        - trivia
    PollStatus:
      title: PollStatus
      type: string
      enum:
        - draft
        - published
    PollOrderBy:
      title: PollOrderBy
      type: string
      enum:
        - created
        - name
    PollsExpandItems:
      title: PollsExpandItems
      type: string
      enum:
        - stats
        - poll_responses
        - trivia_answer
    PollsListResponse:
      title: PollsListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Poll'
          description: An array of polls.
        limit:
          type: integer
          nullable: true
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
        page:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            **Offset pagination only**: The page number the results are from.
            Only present when using deprecated offset-based pagination.
        total_pages:
          type: integer
          nullable: true
          description: >-
            **Offset pagination only**: The total number of pages. Only present
            when using deprecated offset-based pagination.
        has_more:
          type: boolean
          nullable: true
          description: >-
            **Cursor pagination only**: Indicates whether there are more results
            available after the current page. Only present when using
            cursor-based pagination.
        next_cursor:
          type: string
          nullable: true
          description: >-
            **Cursor pagination only**: The cursor token to use for fetching the
            next page of results. This will be null if has_more is false. Only
            present when using cursor-based pagination.
        total_results:
          type: integer
          nullable: true
          description: The total number of results from all pages.
      required:
        - data
    PollShowResponse:
      title: PollShowResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Poll'
      required:
        - data
    PollResponsesExpandItems:
      title: PollResponsesExpandItems
      type: string
      enum:
        - post
    PollResponsesOrderBy:
      title: PollResponsesOrderBy
      type: string
      enum:
        - created
    PollResponsesListResponse:
      title: PollResponsesListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PollResponseItem'
          description: An array of poll responses.
        limit:
          type: integer
          nullable: true
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
        page:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            **Offset pagination only**: The page number the results are from.
            Only present when using deprecated offset-based pagination.
        total_pages:
          type: integer
          nullable: true
          description: >-
            **Offset pagination only**: The total number of pages. Only present
            when using deprecated offset-based pagination.
        has_more:
          type: boolean
          nullable: true
          description: >-
            **Cursor pagination only**: Indicates whether there are more results
            available after the current page.
        next_cursor:
          type: string
          nullable: true
          description: >-
            **Cursor pagination only**: The cursor token to use for fetching the
            next page of results.
        total_results:
          type: integer
          nullable: true
          description: The total number of results from all pages.
      required:
        - data
    PostCreateBodyBase:
      title: PostCreateBodyBase
      type: object
      properties:
        title:
          type: string
          description: The title of the post.
        subtitle:
          type: string
          nullable: true
          description: The subtitle of the post.
        post_template_id:
          $ref: '#/components/schemas/PostTemplateId'
          nullable: true
          description: >-
            The ID of the template to use for the post. If not provided, the
            default template will be used.
        scheduled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            The time in which the post will be published. If not provided, the
            post will be published immediately.
        custom_link_tracking_enabled:
          type: boolean
          nullable: true
          description: >-
            If true, custom link tracking will be enabled for this post. If not
            provided, the default value will be used.
        email_capture_type_override:
          $ref: '#/components/schemas/PostEmailCaptureTypeOverride'
          nullable: true
          description: >-
            The email capture type to use for this post. If not provided, the
            default value will be used.
        override_scheduled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            If you wish to display a date other than the scheduled_at date in
            the email, you can provide a date here. This will not affect the
            actual publish date of the post.
        social_share:
          $ref: '#/components/schemas/PostSocialShare'
          nullable: true
          description: >-
            The social share type to use for this post. If not provided, the
            default value will be used.
        thumbnail_image_url:
          type: string
          nullable: true
          description: >-
            The URL of the thumbnail image to use for the post. If not provided,
            the default value will be used.
        recipients:
          $ref: '#/components/schemas/PostRecipients'
          nullable: true
          description: >-
            The recipients to use for this post. If not provided, the default
            value will be used.
        email_settings:
          $ref: '#/components/schemas/PostEmailSettings'
          nullable: true
          description: >-
            The email settings to use for this post. If not provided, the
            default value will be used.
        web_settings:
          $ref: '#/components/schemas/PostWebSettings'
          nullable: true
          description: >-
            The web settings to use for this post. If not provided, the default
            value will be used.
        seo_settings:
          $ref: '#/components/schemas/PostMetadata'
          nullable: true
          description: >-
            The metadata to use for this post. If not provided, the default
            value will be used.
        content_tags:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            The content tags to use for this post. If not provided, the default
            value will be used.
        headers:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: >-
            The headers to use for this post. If not provided, the default value
            will be used.
        custom_fields:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: >-
            The custom fields to use for this post. If not provided, the default
            value will be used.
        newsletter_list_id:
          type: string
          nullable: true
          description: >-
            The prefixed ID of the newsletter list to associate with this post.
            When provided, the post will only be sent to subscribers of this
            list. <Badge intent="warning" minimal outlined>Beta</Badge>
      required:
        - title
    CreatePostRequestWithBodyContent:
      title: CreatePostRequestWithBodyContent
      type: object
      properties:
        body_content:
          type: string
          description: >-
            The content of the post as a single raw HTML string. The HTML is
            wrapped in an `htmlSnippet` block internally. Note that `<style>`
            and `<link>` tags are removed during sanitization — use inline
            styles for all visual styling.
        title:
          type: string
          description: The title of the post.
        subtitle:
          type: string
          nullable: true
          description: The subtitle of the post.
        post_template_id:
          $ref: '#/components/schemas/PostTemplateId'
          nullable: true
          description: >-
            The ID of the template to use for the post. If not provided, the
            default template will be used.
        scheduled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            The time in which the post will be published. If not provided, the
            post will be published immediately.
        custom_link_tracking_enabled:
          type: boolean
          nullable: true
          description: >-
            If true, custom link tracking will be enabled for this post. If not
            provided, the default value will be used.
        email_capture_type_override:
          $ref: '#/components/schemas/PostEmailCaptureTypeOverride'
          nullable: true
          description: >-
            The email capture type to use for this post. If not provided, the
            default value will be used.
        override_scheduled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            If you wish to display a date other than the scheduled_at date in
            the email, you can provide a date here. This will not affect the
            actual publish date of the post.
        social_share:
          $ref: '#/components/schemas/PostSocialShare'
          nullable: true
          description: >-
            The social share type to use for this post. If not provided, the
            default value will be used.
        thumbnail_image_url:
          type: string
          nullable: true
          description: >-
            The URL of the thumbnail image to use for the post. If not provided,
            the default value will be used.
        recipients:
          $ref: '#/components/schemas/PostRecipients'
          nullable: true
          description: >-
            The recipients to use for this post. If not provided, the default
            value will be used.
        email_settings:
          $ref: '#/components/schemas/PostEmailSettings'
          nullable: true
          description: >-
            The email settings to use for this post. If not provided, the
            default value will be used.
        web_settings:
          $ref: '#/components/schemas/PostWebSettings'
          nullable: true
          description: >-
            The web settings to use for this post. If not provided, the default
            value will be used.
        seo_settings:
          $ref: '#/components/schemas/PostMetadata'
          nullable: true
          description: >-
            The metadata to use for this post. If not provided, the default
            value will be used.
        content_tags:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            The content tags to use for this post. If not provided, the default
            value will be used.
        headers:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: >-
            The headers to use for this post. If not provided, the default value
            will be used.
        custom_fields:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: >-
            The custom fields to use for this post. If not provided, the default
            value will be used.
        newsletter_list_id:
          type: string
          nullable: true
          description: >-
            The prefixed ID of the newsletter list to associate with this post.
            When provided, the post will only be sent to subscribers of this
            list. <Badge intent="warning" minimal outlined>Beta</Badge>
      required:
        - body_content
        - title
    CreatePostRequestWithBlocks:
      title: CreatePostRequestWithBlocks
      type: object
      properties:
        blocks:
          type: array
          items:
            $ref: '#/components/schemas/Block'
          description: >-
            The structured content blocks that make up the post. Supports block
            types such as paragraph, image, heading, button, html, table, list,
            columns, and more. You can embed raw HTML snippets within blocks
            using the `html` block type.
        title:
          type: string
          description: The title of the post.
        subtitle:
          type: string
          nullable: true
          description: The subtitle of the post.
        post_template_id:
          $ref: '#/components/schemas/PostTemplateId'
          nullable: true
          description: >-
            The ID of the template to use for the post. If not provided, the
            default template will be used.
        scheduled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            The time in which the post will be published. If not provided, the
            post will be published immediately.
        custom_link_tracking_enabled:
          type: boolean
          nullable: true
          description: >-
            If true, custom link tracking will be enabled for this post. If not
            provided, the default value will be used.
        email_capture_type_override:
          $ref: '#/components/schemas/PostEmailCaptureTypeOverride'
          nullable: true
          description: >-
            The email capture type to use for this post. If not provided, the
            default value will be used.
        override_scheduled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            If you wish to display a date other than the scheduled_at date in
            the email, you can provide a date here. This will not affect the
            actual publish date of the post.
        social_share:
          $ref: '#/components/schemas/PostSocialShare'
          nullable: true
          description: >-
            The social share type to use for this post. If not provided, the
            default value will be used.
        thumbnail_image_url:
          type: string
          nullable: true
          description: >-
            The URL of the thumbnail image to use for the post. If not provided,
            the default value will be used.
        recipients:
          $ref: '#/components/schemas/PostRecipients'
          nullable: true
          description: >-
            The recipients to use for this post. If not provided, the default
            value will be used.
        email_settings:
          $ref: '#/components/schemas/PostEmailSettings'
          nullable: true
          description: >-
            The email settings to use for this post. If not provided, the
            default value will be used.
        web_settings:
          $ref: '#/components/schemas/PostWebSettings'
          nullable: true
          description: >-
            The web settings to use for this post. If not provided, the default
            value will be used.
        seo_settings:
          $ref: '#/components/schemas/PostMetadata'
          nullable: true
          description: >-
            The metadata to use for this post. If not provided, the default
            value will be used.
        content_tags:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            The content tags to use for this post. If not provided, the default
            value will be used.
        headers:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: >-
            The headers to use for this post. If not provided, the default value
            will be used.
        custom_fields:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: >-
            The custom fields to use for this post. If not provided, the default
            value will be used.
        newsletter_list_id:
          type: string
          nullable: true
          description: >-
            The prefixed ID of the newsletter list to associate with this post.
            When provided, the post will only be sent to subscribers of this
            list. <Badge intent="warning" minimal outlined>Beta</Badge>
      required:
        - blocks
        - title
    PostCreateRequest:
      title: PostCreateRequest
      oneOf:
        - $ref: '#/components/schemas/CreatePostRequestWithBlocks'
        - $ref: '#/components/schemas/CreatePostRequestWithBodyContent'
      description: The request to create a post.
    BlockType:
      title: BlockType
      type: string
      enum:
        - image
        - paragraph
        - button
        - heading
        - rss
      description: The type of block in the post.
    QuoteVariant:
      title: QuoteVariant
      type: string
      enum:
        - block
        - inline
        - quotation
      description: The variant of the quote block.
    TextAlignment:
      title: TextAlignment
      type: string
      enum:
        - left
        - center
        - right
      description: The text alignment of the header.
    Sizes:
      title: Sizes
      type: string
      enum:
        - small
        - normal
        - large
      description: The sizes of the button.
    HeadingLevel:
      title: HeadingLevel
      type: string
      enum:
        - '1'
        - '2'
        - '3'
        - '4'
        - '5'
        - '6'
      description: The level of the header.
    BorderStyle:
      title: BorderStyle
      type: string
      enum:
        - solid
        - dashed
        - dotted
    VisualSettings:
      title: VisualSettings
      type: object
      properties:
        background_color:
          type: string
          nullable: true
          description: The background color of the block.
        text_color:
          type: string
          nullable: true
          description: The text color of the block.
        border_color:
          type: string
          nullable: true
          description: The border color of the block.
        border_style:
          $ref: '#/components/schemas/BorderStyle'
          nullable: true
          description: The border style of the block.
        border_width:
          type: integer
          nullable: true
          description: The border width of the block.
        border_width_top:
          type: integer
          nullable: true
          description: The border width of the top of the block.
        border_width_bottom:
          type: integer
          nullable: true
          description: The border width of the bottom of the block.
        border_width_left:
          type: integer
          nullable: true
          description: The border width of the left of the block.
        border_width_right:
          type: integer
          nullable: true
          description: The border width of the right of the block.
        border_radius:
          type: integer
          nullable: true
          description: The border radius of the block.
        border_radius_top_left:
          type: integer
          nullable: true
          description: The border radius of the top left of the block.
        border_radius_top_right:
          type: integer
          nullable: true
          description: The border radius of the top right of the block.
        border_radius_bottom_left:
          type: integer
          nullable: true
          description: The border radius of the bottom left of the block.
        border_radius_bottom_right:
          type: integer
          nullable: true
          description: The border radius of the bottom right of the block.
        inner_spacing:
          type: integer
          nullable: true
          description: The inner spacing of the block.
        inner_spacing_top:
          type: integer
          nullable: true
          description: The inner spacing of the top of the block.
        inner_spacing_bottom:
          type: integer
          nullable: true
          description: The inner spacing of the bottom of the block.
        inner_spacing_left:
          type: integer
          nullable: true
          description: The inner spacing of the left of the block.
        inner_spacing_right:
          type: integer
          nullable: true
          description: The inner spacing of the right of the block.
        outer_spacing:
          type: integer
          nullable: true
          description: The outer spacing of the block.
        outer_spacing_top:
          type: integer
          nullable: true
          description: The outer spacing of the top of the block.
        outer_spacing_bottom:
          type: integer
          nullable: true
          description: The outer spacing of the bottom of the block.
        outer_spacing_left:
          type: integer
          nullable: true
          description: The outer spacing of the left of the block.
        outer_spacing_right:
          type: integer
          nullable: true
          description: The outer spacing of the right of the block.
    ReferralCondition:
      title: ReferralCondition
      type: string
      enum:
        - eq
        - gt
        - lt
    VisibilitySettings:
      title: VisibilitySettings
      type: object
      properties:
        show_on_web:
          type: boolean
          nullable: true
          description: Whether to show the block on the web.
        show_on_email:
          type: boolean
          nullable: true
          description: Whether to show the block on the email.
        show_to_anonymous_users_web:
          type: boolean
          nullable: true
          description: Whether to show the block to anonymous users on the web.
        show_to_free_subscribers:
          type: boolean
          nullable: true
          description: Whether to show the block to free subscribers.
        show_to_paid_subscribers:
          type: boolean
          nullable: true
          description: Whether to show the block to paid subscribers.
        show_to_subscribers_with_referral_value:
          type: integer
          nullable: true
          description: The exact referral count required to show the block to subscribers.
        show_to_subscribers_with_referral_condition:
          $ref: '#/components/schemas/ReferralCondition'
          nullable: true
          description: The condition required to show the block to subscribers.
        condition_set_ids:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            An optional list of condition set UUIDs to gate this block behind
            dynamic content targeting. When provided, only subscribers matching
            the specified condition sets will see this block. Condition sets
            must belong to the same publication and be active.
        condition_set_operator:
          $ref: '#/components/schemas/ConditionSetOperator'
          nullable: true
          description: >-
            Instructs how to combine multiple condition sets. Defaults to "or"
            (subscriber can match any condition). Use "and" to show the block if
            the subscriber meets all conditions.
    Link:
      title: Link
      type: object
      properties:
        href:
          type: string
          description: The URL of the link.
        target:
          type: string
          nullable: true
          description: The target of the link (e.g., _blank).
      required:
        - href
    ContentBreakBlock:
      title: ContentBreakBlock
      type: object
      properties: {}
    PaywallBreakBlock:
      title: PaywallBreakBlock
      type: object
      properties:
        paywall_id:
          $ref: '#/components/schemas/PaywallId'
          description: The ID of the paywall.
      required:
        - paywall_id
    ParagrahBlockTextSection:
      title: ParagrahBlockTextSection
      type: object
      properties:
        text:
          type: string
          description: The text content of the paragraph.
        styling:
          type: array
          items:
            type: string
          nullable: true
          description: The styling of the text (e.g., bold, italic).
        link:
          $ref: '#/components/schemas/Link'
          nullable: true
          description: The link of the text.
      required:
        - text
    ConditionSetOperator:
      title: ConditionSetOperator
      type: string
      enum:
        - and
        - or
      description: >-
        How multiple condition sets are combined when evaluating dynamic content
        targeting.
    BaseBlock:
      title: BaseBlock
      type: object
      properties:
        visual_settings:
          $ref: '#/components/schemas/VisualSettings'
          nullable: true
          description: Optional styling for borders, spacing, colors, etc.
        visibility_settings:
          $ref: '#/components/schemas/VisibilitySettings'
          nullable: true
          description: >-
            Optional rules for when/where this block is shown, including dynamic
            content targeting via condition sets.
    ParagraphBlock:
      title: ParagraphBlock
      type: object
      properties:
        plaintext:
          type: string
          nullable: true
          description: The plaintext content of the paragraph.
        formattedText:
          type: array
          items:
            $ref: '#/components/schemas/ParagrahBlockTextSection'
          nullable: true
          description: The formatted content of the paragraph.
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    ImageBlock:
      title: ImageBlock
      type: object
      properties:
        imageUrl:
          type: string
          description: The URL of the image.
        url:
          type: string
          nullable: true
          description: The URL that the image should link to.
        title:
          type: string
          nullable: true
          description: The title of the image.
        alt_text:
          type: string
          nullable: true
          description: Alternative text for the image.
        caption:
          type: string
          nullable: true
          description: A caption for the image.
        imageAlignment:
          $ref: '#/components/schemas/TextAlignment'
          nullable: true
          description: The text alignment of the image.
        captionAlignment:
          $ref: '#/components/schemas/TextAlignment'
          nullable: true
          description: The text alignment of the caption.
        width:
          type: integer
          nullable: true
          description: The width of the image. Should be between 1 and 100.
      required:
        - imageUrl
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    ButtonBlock:
      title: ButtonBlock
      type: object
      properties:
        href:
          type: string
          description: The URL the button should use.
        text:
          type: string
          description: The text content of the button.
        target:
          type: string
          nullable: true
          description: The target of the button (e.g., _blank).
        alignment:
          $ref: '#/components/schemas/TextAlignment'
          nullable: true
          description: The text alignment of the button.
        size:
          $ref: '#/components/schemas/Sizes'
          nullable: true
          description: The size of the button (e.g., small, normal, large).
      required:
        - href
        - text
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    HeaderBlock:
      title: HeaderBlock
      type: object
      properties:
        level:
          $ref: '#/components/schemas/HeadingLevel'
          description: The level of the header (e.g., 1, 2, 3, etc.).
        textAlignment:
          $ref: '#/components/schemas/TextAlignment'
          nullable: true
          description: The text alignment of the header (e.g., left, center, right).
        text:
          type: string
          description: The text content of the header.
        anchorHeader:
          type: boolean
          nullable: true
          description: Whether the header should be an anchor header.
        anchorIncludeInToc:
          type: boolean
          nullable: true
          description: Whether the header should be included in the table of contents.
      required:
        - level
        - text
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    HTMLBlock:
      title: HTMLBlock
      type: object
      properties:
        html:
          type: string
          description: >-
            The raw HTML content. Note that `<style>` and `<link>` tags are
            removed during sanitization — use inline styles for all visual
            styling.
      required:
        - html
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    RssBlockLayout:
      title: RssBlockLayout
      type: string
      enum:
        - 1-col
        - 2-col
        - 3-col
        - 4-col
      description: The layout of the articles from the feed.
    RssCtaStyle:
      title: RssCtaStyle
      type: string
      enum:
        - CTA button
        - CTA link
        - Title as link
        - Thumbnail as link
        - Title and thumbnail as link
      description: The style of the call to action.
    RssCtaAlignment:
      title: RssCtaAlignment
      type: string
      enum:
        - Left
        - Center
        - Right
      description: The alignment of the call to action.
    RssThumbnailPosition:
      title: RssThumbnailPosition
      type: string
      enum:
        - Above Title
        - Below Title
        - Left of content
        - Right of content
        - Alternating Horizontally
      description: The position of the thumbnail.
    RssBlock:
      title: RssBlock
      type: object
      description: A block in the post content.
      properties:
        externalRssFeedId:
          $ref: '#/components/schemas/ExternalRssFeedId'
          nullable: true
          description: The ID of the external RSS feed.
        rssFeedUrl:
          type: string
          nullable: true
          description: The URL of the RSS feed.
        articleLayout:
          $ref: '#/components/schemas/RssBlockLayout'
          nullable: true
          description: The layout of the articles from the feed.
        articlesToShow:
          type: integer
          nullable: true
          description: The number of articles to show from the feed.
        showCta:
          type: boolean
          nullable: true
          description: Whether to show a call to action.
        ctaText:
          type: string
          nullable: true
          description: >-
            The text of the call to action. Applicable if ctaStyle is button or
            link.
        ctaStyle:
          $ref: '#/components/schemas/RssCtaStyle'
          nullable: true
          description: The style of the call to action.
        ctaAlignment:
          $ref: '#/components/schemas/RssCtaAlignment'
          nullable: true
          description: The alignment of the call to action.
        refreshOnSend:
          type: boolean
          nullable: true
          description: >-
            Whether or not to refresh the contents from the RSS feed before
            sending out the email.
        showArticleTitle:
          type: boolean
          nullable: true
          description: Whether to show the article title.
        showArticleThumbnail:
          type: boolean
          nullable: true
          description: Whether to show the article thumbnail.
        thumbnailPosition:
          $ref: '#/components/schemas/RssThumbnailPosition'
          nullable: true
          description: The position of the thumbnail.
        showAuthor:
          type: boolean
          nullable: true
          description: Whether to show the author.
        showPublishedDate:
          type: boolean
          nullable: true
          description: Whether to show the date the article was published
        showCategories:
          type: boolean
          nullable: true
          description: Whether to show the categories.
        showDescription:
          type: boolean
          nullable: true
          description: Whether to show the article description.
        showContent:
          type: boolean
          nullable: true
          description: Whether to show the article content.
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    AdvertisementBlock:
      title: AdvertisementBlock
      type: object
      properties:
        opportunity_id:
          type: string
          description: The ID of the Advertisement opportunity.
      required:
        - opportunity_id
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    ColumnsBlock:
      title: ColumnsBlock
      type: object
      properties:
        columns:
          type: array
          items:
            $ref: '#/components/schemas/ColumnBlock'
          description: The blocks that make up the columns.
      required:
        - columns
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    ColumnBlock:
      title: ColumnBlock
      type: object
      properties:
        blocks:
          type: array
          items:
            $ref: '#/components/schemas/EmbeddableBlocks'
          description: The blocks that make up the column.
      required:
        - blocks
    EmbeddableBlocks:
      title: EmbeddableBlocks
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - paragraph
            - $ref: '#/components/schemas/ParagraphBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - image
            - $ref: '#/components/schemas/ImageBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - button
            - $ref: '#/components/schemas/ButtonBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - heading
            - $ref: '#/components/schemas/HeaderBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - rss
            - $ref: '#/components/schemas/RssBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - advertisement
            - $ref: '#/components/schemas/AdvertisementBlock'
          required:
            - type
      description: A block in the post content that can be embedded within a column.
    ListType:
      title: ListType
      type: string
      enum:
        - ordered
        - unordered
      description: The type of list (e.g., ordered, unordered).
    ListBlock:
      title: ListBlock
      type: object
      properties:
        items:
          type: array
          items:
            type: string
          description: The items in the list.
        listType:
          $ref: '#/components/schemas/ListType'
          nullable: true
          description: The type of list (e.g., ordered, unordered).
        startNumber:
          type: integer
          nullable: true
          description: >-
            The number to start the list at. Only applicable if listType is
            ordered.
      required:
        - items
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    TableCellData:
      title: TableCellData
      type: object
      properties:
        text:
          type: string
          description: The text content of the cell.
        alignment:
          $ref: '#/components/schemas/TextAlignment'
          nullable: true
          description: The text alignment of the cell.
      required:
        - text
    TableBlock:
      title: TableBlock
      type: object
      properties:
        rows:
          type: array
          items:
            type: array
            items:
              $ref: '#/components/schemas/TableCellData'
          description: The rows of the table.
        headerRow:
          type: boolean
          nullable: true
          description: Whether the first row is a header row.
        headerColumn:
          type: boolean
          nullable: true
          description: Whether the first column is a header column.
      required:
        - rows
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    EmbedLinkBlock:
      title: EmbedLinkBlock
      type: object
      properties:
        url:
          type: string
          description: The URL of the embed link.
      required:
        - url
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    PollBlock:
      title: PollBlock
      type: object
      properties:
        poll_id:
          $ref: '#/components/schemas/PollId'
          description: The ID of the poll you wish to include.
        show_options_initially:
          type: boolean
          nullable: true
          description: Whether to show the poll options initially. Defaults to false.
      required:
        - poll_id
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    QuoteBlock:
      title: QuoteBlock
      type: object
      properties:
        variant:
          $ref: '#/components/schemas/QuoteVariant'
          nullable: true
          description: The type of quote block. Defaults to "block".
        quote:
          type: string
          description: The text of the quote.
        alignment:
          $ref: '#/components/schemas/TextAlignment'
          nullable: true
          description: The text alignment of the quote. Defaults depend on the variant.
        author:
          type: string
          nullable: true
          description: The author of the quote.
      required:
        - quote
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
    Block:
      title: Block
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - paragraph
            - $ref: '#/components/schemas/ParagraphBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - image
            - $ref: '#/components/schemas/ImageBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - button
            - $ref: '#/components/schemas/ButtonBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - heading
            - $ref: '#/components/schemas/HeaderBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - rss
            - $ref: '#/components/schemas/RssBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - advertisement
            - $ref: '#/components/schemas/AdvertisementBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - columns
            - $ref: '#/components/schemas/ColumnsBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - list
            - $ref: '#/components/schemas/ListBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - table
            - $ref: '#/components/schemas/TableBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - html
            - $ref: '#/components/schemas/HTMLBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - embed_link
            - $ref: '#/components/schemas/EmbedLinkBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - poll
            - $ref: '#/components/schemas/PollBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - quote
            - $ref: '#/components/schemas/QuoteBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - content_break
            - $ref: '#/components/schemas/ContentBreakBlock'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - paywall_break
            - $ref: '#/components/schemas/PaywallBreakBlock'
          required:
            - type
      description: A block in the post content.
    PostWebRecipients:
      title: PostWebRecipients
      type: object
      properties:
        tier_ids:
          type: array
          items:
            type: string
          nullable: true
        include_segment_ids:
          type: array
          items:
            $ref: '#/components/schemas/SegmentId'
          nullable: true
        exclude_segment_ids:
          type: array
          items:
            $ref: '#/components/schemas/SegmentId'
          nullable: true
    PostEmailRecipients:
      title: PostEmailRecipients
      type: object
      properties:
        tier_ids:
          type: array
          items:
            type: string
          nullable: true
        include_segment_ids:
          type: array
          items:
            $ref: '#/components/schemas/SegmentId'
          nullable: true
        exclude_segment_ids:
          type: array
          items:
            $ref: '#/components/schemas/SegmentId'
          nullable: true
    PostMetadata:
      title: PostMetadata
      type: object
      properties:
        default_description:
          type: string
          nullable: true
        default_title:
          type: string
          nullable: true
        og_description:
          type: string
          nullable: true
        og_title:
          type: string
          nullable: true
        twitter_description:
          type: string
          nullable: true
        twitter_title:
          type: string
          nullable: true
    PostRecipients:
      title: PostRecipients
      type: object
      properties:
        web:
          $ref: '#/components/schemas/PostWebRecipients'
        email:
          $ref: '#/components/schemas/PostEmailRecipients'
      required:
        - web
        - email
    PostEmailSettings:
      title: PostEmailSettings
      type: object
      properties:
        from_address:
          type: string
          nullable: true
        custom_live_url:
          type: string
          nullable: true
        display_title_in_email:
          type: boolean
          nullable: true
        display_byline_in_email:
          type: boolean
          nullable: true
        display_subtitle_in_email:
          type: boolean
          nullable: true
        email_header_engagement_buttons:
          type: string
          nullable: true
        email_header_social_share:
          type: string
          nullable: true
        email_preview_text:
          type: string
          nullable: true
        email_subject_line:
          type: string
          nullable: true
    PostWebSettings:
      title: PostWebSettings
      type: object
      properties:
        display_thumbnail_on_web:
          type: boolean
          nullable: true
        hide_from_feed:
          type: boolean
          nullable: true
        paywall_break_price_id:
          $ref: '#/components/schemas/PriceId'
          nullable: true
        paywall_id:
          $ref: '#/components/schemas/PaywallId'
          nullable: true
        slug:
          type: string
          nullable: true
    PostEmailCaptureTypeOverride:
      title: PostEmailCaptureTypeOverride
      type: string
      enum:
        - none
        - gated
        - popup
    PostSocialShare:
      title: PostSocialShare
      type: string
      enum:
        - comments_and_likes_only
        - with_comments_and_likes
        - top
        - none
    PostExpandField:
      title: PostExpandField
      type: string
      enum:
        - stats
        - free_web_content
        - free_email_content
        - free_rss_content
        - premium_web_content
        - premium_email_content
    PostAudienceFilter:
      title: PostAudienceFilter
      type: string
      enum:
        - free
        - premium
        - all
    PostPlatformFilter:
      title: PostPlatformFilter
      type: string
      enum:
        - web
        - email
        - both
        - all
    PostPublishStatus:
      title: PostPublishStatus
      type: string
      enum:
        - draft
        - confirmed
    PostStatusFilter:
      title: PostStatusFilter
      type: string
      enum:
        - draft
        - confirmed
        - archived
        - all
    PostOrderBy:
      title: PostOrderBy
      type: string
      enum:
        - created
        - publish_date
        - displayed_date
    PostsListRequestHiddenFromFeed:
      title: PostsListRequestHiddenFromFeed
      type: string
      enum:
        - all
        - 'true'
        - 'false'
    PostsListResponse:
      title: PostsListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request,this defaults to 10.
          example: 1
        page:
          type: integer
          minimum: 0
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 1
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    PostsAggregateStatsResponse:
      title: PostsAggregateStatsResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PostsAggregateStatsResponseStats'
      required:
        - data
    PostsAggregateStatsResponseStats:
      title: PostsAggregateStatsResponseStats
      type: object
      properties:
        stats:
          $ref: '#/components/schemas/PostStats'
      required:
        - stats
    PostsGetResponse:
      title: PostsGetResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Post'
      required:
        - data
    PostsCreateResponse:
      title: PostsCreateResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PostCreate'
      required:
        - data
    PostsDeleteResponse:
      title: PostsDeleteResponse
      type: object
      properties: {}
    PostTemplate:
      title: PostTemplate
      type: object
      properties:
        id:
          $ref: '#/components/schemas/PostTemplateId'
          description: The prefixed ID of the post template.
        name:
          type: string
          description: The name of the post template.
      required:
        - id
        - name
    PostTemplatesGetResponse:
      title: PostTemplatesGetResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PostTemplate'
          description: A list of post templates available for this publication.
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
          example: 10
        page:
          type: integer
          minimum: 0
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 2
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    PublicationsRequestExpandItem:
      title: PublicationsRequestExpandItem
      type: string
      enum:
        - stats
        - stat_active_subscriptions
        - stat_active_premium_subscriptions
        - stat_active_free_subscriptions
        - stat_average_open_rate
        - stat_average_click_rate
        - stat_total_sent
        - stat_total_unique_opened
        - stat_total_clicked
    PublicationsListRequestOrderBy:
      title: PublicationsListRequestOrderBy
      type: string
      enum:
        - created
        - name
    PublicationsListResponse:
      title: PublicationsListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Publication'
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request,this defaults to 10.
          example: 10
        page:
          type: integer
          minimum: 0
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 1
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    PublicationsGetRequestExpandItem:
      title: PublicationsGetRequestExpandItem
      type: string
      enum:
        - stats
        - stat_active_subscriptions
        - stat_active_premium_subscriptions
        - stat_active_free_subscriptions
        - stat_average_open_rate
        - stat_average_click_rate
        - stat_total_sent
        - stat_total_unique_opened
        - stat_total_clicked
    PublicationsGetResponse:
      title: PublicationsGetResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Publication'
      required:
        - data
    ReferralProgramGetResponse:
      title: ReferralProgramGetResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Milestone'
          description: >-
            A list of the milestones related to this publication's referral
            program.
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request,this defaults to 10.
          example: 1
        page:
          type: integer
          minimum: 0
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 1
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    SegmentRequestStatus:
      title: SegmentRequestStatus
      type: string
      enum:
        - pending
        - processing
        - completed
        - failed
        - all
    SegmentSubscriptionInput:
      title: SegmentSubscriptionInput
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - subscriptions
            - $ref: '#/components/schemas/Subscriptions'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - emails
            - $ref: '#/components/schemas/Emails'
          required:
            - type
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - custom_fields
            - $ref: '#/components/schemas/CustomFields'
          required:
            - type
      description: >-
        Input for segment creation. Use `subscriptions` or `emails` to create a
        manual segment from explicit lists, or `custom_fields` to create a
        dynamic segment filtered by custom field values.
    Emails:
      title: Emails
      type: object
      description: >-
        A list of email addresses to be included in the segment. Only existing
        subscribers will be matched — unlike the beehiiv UI, this endpoint does
        not import or create new subscriptions for unrecognized email addresses.
        Emails that do not correspond to an existing subscription in the
        publication will be silently skipped.
      properties:
        emails:
          type: array
          items:
            type: string
      required:
        - emails
    Subscriptions:
      title: Subscriptions
      type: object
      description: >-
        A list of subscription IDs to be included in the segment. Will be
        skipped if the subscription does not already exist in the publication.
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionId'
      required:
        - subscriptions
    CustomFields:
      title: CustomFields
      type: object
      description: >-
        Create a dynamic segment by filtering subscribers based on custom field
        values. The segment is processed asynchronously and will initially have
        a `pending` status.
      properties:
        operator:
          $ref: '#/components/schemas/CustomFieldsLogicalOperator'
          nullable: true
          description: >-
            The logical operator used to combine multiple custom field filters.
            Defaults to `and` if not specified.
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldFilter'
      required:
        - custom_fields
    CustomFieldFilter:
      title: CustomFieldFilter
      type: object
      description: A single custom field filter condition.
      properties:
        name:
          type: string
          description: >-
            The display name of the custom field (case-insensitive match). Must
            be an existing custom field on the publication.
        operator:
          type: string
          description: >-
            The comparison operator for the filter (e.g., `equal`, `not_equal`,
            `contains`, `exists`, `does_not_exist`). Available operators depend
            on the custom field's type.
        value:
          type: string
          nullable: true
          description: >-
            The value to compare against. Required for all operators except
            `exists` and `does_not_exist`.
      required:
        - name
        - operator
    CustomFieldsLogicalOperator:
      title: CustomFieldsLogicalOperator
      type: string
      enum:
        - and
        - or
    SegmentOrderBy:
      title: SegmentOrderBy
      type: string
      enum:
        - created
        - last_calculated
    SegmentsListResponse:
      title: SegmentsListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Segment'
          description: An array of all segments.
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request,this defaults to 10.
          example: 1
        page:
          type: integer
          minimum: 0
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 1
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    SegmentsGetResponse:
      title: SegmentsGetResponse
      type: object
      properties:
        data:
          type: array
          items:
            type: string
          description: An array of subscription ids
          example:
            - sub_00000000-0000-0000-0000-000000000000
            - sub_00000000-1111-1111-1111-111111111111
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request,this defaults to 10.
          example: 1
        page:
          type: integer
          minimum: 0
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 1
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    SegmentShowResponse:
      title: SegmentShowResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Segment'
      required:
        - data
    SegmentRecalculateResponse:
      title: SegmentRecalculateResponse
      type: object
      properties:
        message:
          type: string
          nullable: true
    SegmentDeleteResponse:
      title: SegmentDeleteResponse
      type: object
      properties:
        message:
          type: string
          nullable: true
    SegmentsExpandItems:
      title: SegmentsExpandItems
      type: string
      enum:
        - stats
    SegmentMembersExpandItems:
      title: SegmentMembersExpandItems
      type: string
      enum:
        - stats
        - custom_fields
        - referrals
        - tags
        - subscription_premium_tiers
    SegmentMembersResponse:
      title: SegmentMembersResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request,this defaults to 10.
          example: 10
        page:
          type: integer
          minimum: 0
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 1
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    SubscriptionsListRequestExpandItem:
      title: SubscriptionsListRequestExpandItem
      type: string
      enum:
        - stats
        - custom_fields
        - referrals
        - newsletter_lists
    SubscriptionsListRequestStatus:
      title: SubscriptionsListRequestStatus
      type: string
      enum:
        - validating
        - invalid
        - pending
        - active
        - inactive
        - all
    SubscriptionsListRequestTier:
      title: SubscriptionsListRequestTier
      type: string
      enum:
        - free
        - premium
        - all
    SubscriptionsListRequestOrderBy:
      title: SubscriptionsListRequestOrderBy
      type: string
      enum:
        - created
    SubscriptionsListResponse:
      title: SubscriptionsListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
        limit:
          type: integer
          nullable: true
          description: >-
            The limit placed on the results. If no limit was specified in the
            request, this defaults to 10.
        page:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            **Offset pagination only**: The page number the results are from.
            Only present when using deprecated offset-based pagination.
        total_pages:
          type: integer
          nullable: true
          description: >-
            **Offset pagination only**: The total number of pages. Only present
            when using deprecated offset-based pagination.
        has_more:
          type: boolean
          nullable: true
          description: >-
            **Cursor pagination only**: Indicates whether there are more results
            available after the current page. Only present when using
            cursor-based pagination.
        next_cursor:
          type: string
          nullable: true
          description: >-
            **Cursor pagination only**: The cursor token to use for fetching the
            next page of results. This will be null if has_more is false. Only
            present when using cursor-based pagination.
        total_results:
          type: integer
          nullable: true
          description: >-
            **Mixed pagination**: The total number of results from all pages.
            For offset-based pagination, this is always included.
      required:
        - data
    SubscriptionsCreateResponse:
      title: SubscriptionsCreateResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Subscription'
      required:
        - data
    SubscriptionsPutRequestNewStatus:
      title: SubscriptionsPutRequestNewStatus
      type: string
      enum:
        - active
        - inactive
      description: The new status value to apply to these subscription IDs
    SubscriptionsPutResponseData:
      title: SubscriptionsPutResponseData
      type: object
      properties:
        subscription_update_id:
          type: string
          nullable: true
          description: >-
            The ID of the Subscription Update object responsible for handling
            the update job
    SubscriptionsPutResponse:
      title: SubscriptionsPutResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SubscriptionsPutResponseData'
      required:
        - data
    SubscriptionsPatchRequestNewStatus:
      title: SubscriptionsPatchRequestNewStatus
      type: string
      enum:
        - active
        - inactive
      description: The new status value to apply to these subscription IDs
    SubscriptionsPatchResponseData:
      title: SubscriptionsPatchResponseData
      type: object
      properties:
        subscription_update_id:
          type: string
          nullable: true
          description: >-
            The ID of the Subscription Update object responsible for handling
            the update job
    SubscriptionsPatchResponse:
      title: SubscriptionsPatchResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SubscriptionsPatchResponseData'
      required:
        - data
    SubscriptionsGetRequestExpandItem:
      title: SubscriptionsGetRequestExpandItem
      type: string
      enum:
        - stats
        - custom_fields
        - referrals
        - tags
        - newsletter_lists
    SubscriptionsGetResponse:
      title: SubscriptionsGetResponse
      type: object
      description: The requested subscription object
      properties:
        data:
          $ref: '#/components/schemas/Subscription'
      required:
        - data
    SubscriptionsPutRequestTier:
      title: SubscriptionsPutRequestTier
      type: string
      enum:
        - free
        - premium
      description: Optional parameter to set the tier for this subscription.
    SubscriptionsPutRequestCustomFieldsItem:
      title: SubscriptionsPutRequestCustomFieldsItem
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: The name of the existing custom field
        value:
          $ref: '#/components/schemas/CustomFieldDataType'
          nullable: true
          description: >-
            The value to stored for the subscription. Will be ignored if
            `delete: true` is included.
        delete:
          type: boolean
          nullable: true
          description: >-
            Optionally delete any value stored. If true, any passed in `value`
            attribute will be ignored.
    SubscriptionResponse:
      title: SubscriptionResponse
      type: object
      description: The response containing subscription data
      properties:
        data:
          $ref: '#/components/schemas/Subscription'
      required:
        - data
    SubscriptionJwtTokenResponse:
      title: SubscriptionJwtTokenResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SubscriptionJwtToken'
      required:
        - data
    SubscriptionDeleteResponse:
      title: SubscriptionDeleteResponse
      type: object
      properties:
        message:
          type: string
          nullable: true
    SubscriptionTagsCreateResponse:
      title: SubscriptionTagsCreateResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Subscription'
          nullable: true
    IndexTiersResponse:
      title: IndexTiersResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Tier'
        limit:
          type: integer
          description: >-
            The limit placed on the results. If no limit was specified in the
            request,this defaults to 10.
          example: 1
        page:
          type: integer
          minimum: 0
          description: >-
            The page number the results are from. If no page was specified in
            the request, this defaults to page 1.
          example: 1
        total_results:
          type: integer
          description: The total number of results from all pages.
          example: 1
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
      required:
        - data
        - limit
        - page
        - total_results
        - total_pages
    TierPriceCurrency:
      title: TierPriceCurrency
      type: string
      enum:
        - usd
        - aud
        - cad
        - eur
        - inr
        - brl
    TierPriceInterval:
      title: TierPriceInterval
      type: string
      enum:
        - month
        - quarter
        - year
        - one_time
        - donation
    TierStatus:
      title: TierStatus
      type: string
      enum:
        - active
        - archived
      description: Returns whether or not the tier has any active prices.
    Tier:
      title: Tier
      type: object
      description: The subscription tier object.
      properties:
        id:
          $ref: '#/components/schemas/TierId'
        name:
          type: string
        status:
          $ref: '#/components/schemas/TierStatus'
          description: Returns whether or not the tier has any active prices.
        description:
          type: string
          nullable: true
        stats:
          $ref: '#/components/schemas/TierStats'
          nullable: true
        prices:
          type: array
          items:
            $ref: '#/components/schemas/TierPrice'
          nullable: true
          description: >-
            Optional list of prices for a tier. Retrievable by including
            `expand: [prices]` in the tier request body.
      required:
        - id
        - name
        - status
    TierStats:
      title: TierStats
      type: object
      description: >-
        Optional list of stats for a tier. Retrievable by including `expand:
        [stats]` in the tier request body.
      properties:
        active_subscriptions:
          type: integer
          description: Total number of active subscriptions belonging to this tier.
      required:
        - active_subscriptions
    TierPrice:
      title: TierPrice
      type: object
      description: Price belonging to a Tier
      properties:
        id:
          $ref: '#/components/schemas/PriceId'
          nullable: true
        currency:
          $ref: '#/components/schemas/TierPriceCurrency'
          nullable: true
        amount_cents:
          type: integer
          nullable: true
        enabled:
          type: boolean
          nullable: true
        interval:
          $ref: '#/components/schemas/TierPriceInterval'
          nullable: true
        denominator:
          type: string
          nullable: true
        cta:
          type: string
          nullable: true
          description: >-
            When using the external Stripe checkout, this text will be displayed
            on the button
        features:
          type: array
          items:
            type: string
          nullable: true
    TierPricesAttributesItem:
      title: TierPricesAttributesItem
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/TierPriceCurrency'
        amount_cents:
          type: integer
        enabled:
          type: boolean
          nullable: true
        interval:
          $ref: '#/components/schemas/TierPriceInterval'
        interval_display:
          type: string
          nullable: true
        cta:
          type: string
          nullable: true
        features:
          type: array
          items:
            type: string
          nullable: true
      required:
        - currency
        - amount_cents
        - interval
    TierResponse:
      title: TierResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Tier'
          nullable: true
    UpdateTierPriceRequest:
      title: UpdateTierPriceRequest
      type: object
      properties:
        id:
          $ref: '#/components/schemas/PriceId'
          description: ID of the existing price.
        currency:
          $ref: '#/components/schemas/TierPriceCurrency'
        amount_cents:
          type: integer
          example: 1000
        interval:
          $ref: '#/components/schemas/TierPriceInterval'
        interval_display:
          type: string
          nullable: true
        cta:
          type: string
          nullable: true
        features:
          type: array
          items:
            type: string
          nullable: true
        delete:
          type: boolean
          nullable: true
          description: Optionally delete the price when updating the tier.
      required:
        - id
        - currency
        - amount_cents
        - interval
    IndexWebhooksResponse:
      title: IndexWebhooksResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
      required:
        - data
    Webhook:
      title: Webhook
      type: object
      properties:
        id:
          $ref: '#/components/schemas/EndpointId'
          description: The prefixed ID for the webhook.
        url:
          type: string
          format: uri
          description: The webhook URL to send events to.
        created:
          type: integer
          description: >-
            The date the webhook was created. Measured in seconds since the Unix
            epoch.
        updated:
          type: integer
          description: >-
            The date the webhook was last updated. Measured in seconds since the
            Unix epoch.
        event_types:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventType'
          description: The types of events the webhook will receive.
        description:
          type: string
          description: The user-defined description for the webhook.
      required:
        - id
        - url
        - created
        - updated
        - event_types
        - description
    WebhookEventType:
      title: WebhookEventType
      type: string
      enum:
        - post.sent
        - post.updated
        - subscription.confirmed
        - subscription.created
        - subscription.downgraded
        - subscription.paused
        - subscription.resumed
        - subscription.tier.paused
        - subscription.tier.resumed
        - subscription.upgraded
        - subscription.tier.created
        - subscription.tier.deleted
        - subscription.deleted
        - newsletter_list_subscription.subscribed
        - newsletter_list_subscription.unsubscribed
        - newsletter_list_subscription.paused
        - newsletter_list_subscription.resumed
        - post.scheduled
        - survey.response_submitted
    WebhookResponse:
      title: WebhookResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Webhook'
      required:
        - data
    GetPublicationsPublicationIdWebhooksWebhookIdTestsResponse:
      title: GetPublicationsPublicationIdWebhooksWebhookIdTestsResponse
      type: object
      properties:
        data:
          type: object
          additionalProperties: true
          description: The test event.
        event_timestamp:
          type: integer
          description: The timestamp of the test event.
          example: 1666800076
        event_type:
          type: string
          description: The type of webhook events that the endpoint is set up to receive.
          example: post.sent
        uid:
          type: string
          description: The unique identifier for the test event.
          example: test_00000000-0000-0000-0000-000000000000
      required:
        - data
        - event_timestamp
        - event_type
        - uid
    WebhooksDeleteResponse:
      title: WebhooksDeleteResponse
      type: object
      properties:
        message:
          type: string
          nullable: true
    WorkspaceIdentity:
      title: WorkspaceIdentity
      type: object
      properties:
        id:
          $ref: '#/components/schemas/WorkspaceId'
          description: The prefixed ID of the workspace.
        name:
          type: string
          description: The name of the workspace.
        owner_email:
          type: string
          description: The email of the owner of the workspace.
      required:
        - id
        - name
        - owner_email
    WorkspaceIdentifyResponse:
      title: WorkspaceIdentifyResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WorkspaceIdentity'
      required:
        - data
    PublicationsBySubscriptionEmailRequestExpandItem:
      title: PublicationsBySubscriptionEmailRequestExpandItem
      type: string
      enum:
        - subscription
        - publication
        - subscription_custom_fields
    PublicationsBySubscriptionEmailResponseItem:
      title: PublicationsBySubscriptionEmailResponseItem
      type: object
      properties:
        publication_id:
          $ref: '#/components/schemas/PublicationId'
          description: The prefixed ID of the publication
        publication_name:
          type: string
          description: The name of the publication
        subscription_id:
          $ref: '#/components/schemas/SubscriptionId'
          description: >-
            The prefixed ID of the subscription matching the email address for
            this publication
        status:
          $ref: '#/components/schemas/SubscriptionExpandedStatus'
          description: >-
            The status of the subscription matching the email address for this
            publication
        publication:
          $ref: '#/components/schemas/Publication'
          nullable: true
          description: >-
            The full Publication object. Only present when `expand` includes
            `publication`.
        subscription:
          $ref: '#/components/schemas/Subscription'
          nullable: true
          description: >-
            The Subscription object matching the email address for this
            publication.  Only present when `expand` includes `subscription` or
            `subscription_custom_fields`.
      required:
        - publication_id
        - publication_name
        - subscription_id
        - status
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
servers:
  - url: https://api.beehiiv.com/v2
    description: Default