openapi.yaml

openapi: 3.0.2
info:
  title: NinjaAPI
  description: ''
  version: 1.0.0
servers:
  - url: https://api.buttondown.email/v1
tags:
  - name: Subscriber
  - name: Tag
  - name: Email
  - name: Newsletter
  - name: Export
  - name: Image
  - name: Action
  - name: HealthCheck
paths:
  /exports:
    post:
      tags:
        - Export
      summary: Create Export
      operationId: Export_createNewExport
      security:
        - GlobalAuth: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportInput'
        required: false
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Export'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    get:
      tags:
        - Export
      summary: List Exports
      operationId: Export_listExports
      security:
        - GlobalAuth: []
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Export_'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /exports/{pk}:
    get:
      tags:
        - Export
      summary: Retrieve Export
      operationId: Export_getExport
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: pk
          schema:
            title: Pk
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Export'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /tags:
    post:
      tags:
        - Tag
      summary: Create Tag
      operationId: Tag_createNewTag
      security:
        - GlobalAuth: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagInput'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    get:
      tags:
        - Tag
      summary: List Tags
      operationId: Tag_listTags
      security:
        - GlobalAuth: []
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Tag_'
  /tags/{tag_id}:
    get:
      tags:
        - Tag
      summary: Retrieve Tag
      operationId: Tag_getTag
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: tag_id
          schema:
            title: Tag Id
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
    patch:
      tags:
        - Tag
      summary: Update Tag
      operationId: Tag_updateTag
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: tag_id
          schema:
            title: Tag Id
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagUpdateInput'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_UpdateTagErrorCode_'
    delete:
      tags:
        - Tag
      summary: Delete Tag
      operationId: Tag_removeTag
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: tag_id
          schema:
            title: Tag Id
            type: string
          required: true
      responses:
        '204':
          description: No Content
  /ping:
    get:
      tags:
        - HealthCheck
      summary: Ping
      operationId: HealthCheck_pingHealthCheck
      security:
        - GlobalAuth: []
      parameters: []
      responses:
        '200':
          description: OK
  /images:
    post:
      tags:
        - Image
      summary: Create Image
      operationId: Image_createNewImage
      security:
        - GlobalAuth: []
      parameters: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImageCreateNewImageRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
  /images/{image_id}:
    delete:
      tags:
        - Image
      summary: Delete Image
      operationId: Image_deleteImage
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: image_id
          schema:
            title: Image Id
            type: string
          required: true
      responses:
        '204':
          description: No Content
  /emails:
    post:
      tags:
        - Email
      summary: Create Email
      operationId: Email_createNewEmail
      security:
        - GlobalAuth: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailInput'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Email'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_EmailCreationErrorCode_'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    get:
      tags:
        - Email
      summary: List Emails
      operationId: Email_listEmails
      security:
        - GlobalAuth: []
      parameters:
        - in: query
          name: status
          schema:
            default:
              - about_to_send
              - in_flight
              - sent
            type: array
            items:
              $ref: '#/components/schemas/EmailStatus'
          required: false
        - in: query
          name: included_tags
          schema:
            title: Included Tags
            default: []
            type: array
            items:
              type: string
          required: false
        - in: query
          name: excluded_tags
          schema:
            title: Excluded Tags
            default: []
            type: array
            items:
              type: string
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Email_'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /emails/{pk}:
    get:
      tags:
        - Email
      summary: Retrieve Email
      operationId: Email_getEmail
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: pk
          schema:
            title: Pk
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Email'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /emails/{pk}/analytics:
    get:
      tags:
        - Email
      summary: Retrieve Email Analytics
      operationId: Email_getAnalytics
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: pk
          schema:
            title: Pk
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /subscribers:
    post:
      tags:
        - Subscriber
      summary: Create Subscriber
      operationId: Subscriber_createNewSubscriber
      security:
        - GlobalAuth: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriberInput'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    get:
      tags:
        - Subscriber
      summary: List Subscribers
      operationId: Subscriber_listSubscribers
      security:
        - GlobalAuth: []
      parameters:
        - in: query
          name: type
          schema:
            $ref: '#/components/schemas/SubscriberType'
          required: false
        - in: query
          name: email
          schema:
            title: Email
            default: ''
            type: string
          required: false
        - in: query
          name: tag
          schema:
            title: Tag
            default: ''
            type: string
          required: false
        - in: query
          name: '-tag'
          schema:
            title: '-Tag'
            type: string
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Subscriber_'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_ListSubscribersErrorCode_'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /subscribers/{pk}:
    get:
      tags:
        - Subscriber
      summary: Retrieve Subscriber
      operationId: Subscriber_getSubscriber
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: pk
          schema:
            title: Pk
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
    delete:
      tags:
        - Subscriber
      summary: Delete Subscriber
      operationId: Subscriber_removeSubscriber
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: pk
          schema:
            title: Pk
            type: string
          required: true
      responses:
        '204':
          description: No Content
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    patch:
      tags:
        - Subscriber
      summary: Update Subscriber
      operationId: Subscriber_updateDetails
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: pk
          schema:
            title: Pk
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriberUpdateInput'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_UpdateSubscriberErrorCode_'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /subscribers/{pk}/send-reminder:
    post:
      tags:
        - Subscriber
      summary: Send Reminder
      operationId: Subscriber_sendReminder
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: pk
          schema:
            title: Pk
            type: string
          required: true
      responses:
        '200':
          description: OK
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /subscribers/{pk}/emails/{email_pk}:
    post:
      tags:
        - Email
      summary: Send Email To
      operationId: Email_sendTo
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: pk
          schema:
            title: Pk
            type: string
          required: true
        - in: path
          name: email_pk
          schema:
            title: Email Pk
            type: string
          required: true
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /newsletters:
    get:
      tags:
        - Newsletter
      summary: List Newsletters
      operationId: Newsletter_listNewsletters
      security:
        - GlobalAuth: []
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Newsletter_'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    post:
      tags:
        - Newsletter
      summary: Create Newsletter
      operationId: Newsletter_createNewNewsletter
      security:
        - GlobalAuth: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewsletterInput'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Newsletter'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_CreateNewsletterErrorCode_'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /newsletters/{pk}:
    patch:
      tags:
        - Newsletter
      summary: Update Newsletter
      operationId: Newsletter_updateContent
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: pk
          schema:
            title: Pk
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewsletterUpdateInput'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Newsletter'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    delete:
      tags:
        - Newsletter
      summary: Delete Newsletter
      operationId: Newsletter_deleteById
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: pk
          schema:
            title: Pk
            type: string
          required: true
      responses:
        '204':
          description: No Content
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /bulk_actions:
    post:
      tags:
        - Action
      summary: Create Bulk Action
      operationId: Action_createBulkAction
      security:
        - GlobalAuth: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkActionInput'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAction'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /bulk_actions/{pk}:
    get:
      tags:
        - Action
      summary: Retrieve Bulk Action
      operationId: Action_getBulkAction
      security:
        - GlobalAuth: []
      parameters:
        - in: path
          name: pk
          schema:
            title: Pk
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAction'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    ExportStatus:
      title: Status
      description: |2-

                Represents the status of an export.

                No action is required to move from one state or another; Buttondown
                internally handles the transitions, and exposing the status is for
                observability purposes only.
                
      enum:
        - error
        - in_progress
        - not_started
        - ready
      type: string
    Export:
      title: Export
      description: >-
        Some software applications may want programmatic access to their
        newsletter exports.

        This assists with a few niche use cases, such as regular backups or data
        ingestion

        (into a data warehouse), or post-publishing processes that hinge on
        email events.


        In general, you probably won't _need_ to use this endpoint unless you
         _absolutely_ need to use this endpoint.
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
        creation_date:
          title: Creation Date
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/ExportStatus'
        url:
          title: Url
          type: string
        completion_date:
          title: Completion Date
          type: string
          format: date-time
      required:
        - id
        - creation_date
        - status
    ErrorMessage:
      title: ErrorMessage
      type: object
      properties:
        code:
          title: Code
        detail:
          title: Detail
          type: string
        metadata:
          title: Metadata
          default: {}
          type: object
          additionalProperties:
            type: string
      required:
        - detail
    ExportCollection:
      title: Collection
      description: |2-

                A group of data that can be exported in an export.
                
      enum:
        - subscribers
        - emails
        - scheduled_emails
        - drafts
        - unsubscribers
        - events
        - referrals
      type: string
    ExportInput:
      title: ExportInput
      type: object
      properties:
        collections:
          type: array
          items:
            $ref: '#/components/schemas/ExportCollection'
      required:
        - collections
    Page_Export_:
      title: Page[Export]
      type: object
      properties:
        results:
          title: Results
          type: array
          items:
            $ref: '#/components/schemas/Export'
        next:
          title: Next
          type: string
        previous:
          title: Previous
          type: string
        count:
          title: Count
          type: integer
      required:
        - results
        - count
    Tag:
      title: Tag
      description: >-
        Tags are a way to organize your subscribers. You can create, update, and

        delete tags via the API. You can also list all tags for a given
        newsletter.


        Tags don't have any strict functionality on their own, but you can send
        emails

        to subscribers with a given tag (or to all subscribers _without_ a given
        tag.)
      type: object
      properties:
        description:
          title: Description
          type: string
        id:
          title: Id
          type: string
          format: uuid
        name:
          title: Name
          type: string
        color:
          title: Color
          type: string
        secondary_id:
          title: Secondary Id
          type: integer
        creation_date:
          title: Creation Date
          type: string
          format: date-time
      required:
        - id
        - name
        - color
        - secondary_id
        - creation_date
    TagInput:
      title: TagInput
      type: object
      properties:
        description:
          title: Description
          type: string
        name:
          title: Name
          type: string
        color:
          title: Color
          type: string
      required:
        - name
        - color
    Page_Tag_:
      title: Page[Tag]
      type: object
      properties:
        results:
          title: Results
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        next:
          title: Next
          type: string
        previous:
          title: Previous
          type: string
        count:
          title: Count
          type: integer
      required:
        - results
        - count
    UpdateTagErrorCode:
      title: UpdateTagErrorCode
      description: |2-

            A potential error code that can be returned when updating a tag.
            
      enum:
        - name_already_exists
      type: string
    ErrorMessage_UpdateTagErrorCode_:
      title: ErrorMessage[UpdateTagErrorCode]
      type: object
      properties:
        code:
          $ref: '#/components/schemas/UpdateTagErrorCode'
        detail:
          title: Detail
          type: string
        metadata:
          title: Metadata
          default: {}
          type: object
          additionalProperties:
            type: string
      required:
        - code
        - detail
    TagUpdateInput:
      title: TagUpdateInput
      type: object
      properties:
        description:
          title: Description
          type: string
        name:
          title: Name
          type: string
        color:
          title: Color
          type: string
    Image:
      title: Image
      description: >-
        Images are, well, images! Buttondown allows you to upload images to its
        secure

        S3 bucket and do with them what you will. This is sort of an odd duck of
        an

        API, to be sure, but if you want to be able to do things like draft

        and send emails completely on your iPad you need a surefire way of
        creating images.
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
        creation_date:
          title: Creation Date
          type: string
          format: date-time
        image:
          title: Image
          type: string
      required:
        - id
        - creation_date
        - image
    EmailType:
      title: Type
      description: |2-

                Represents the audience of an email, and to whom it is visible both in the initial
                email and in online archives.
                
      enum:
        - public
        - private
        - premium
        - free
        - archival
        - hidden
      type: string
    EmailStatus:
      title: Status
      description: |2-

                Represents the state of an email.

                No action is required to move from one state or another; Buttondown
                internally handles the transitions, and exposing the status is for
                observability purposes only.
                
      enum:
        - draft
        - about_to_send
        - scheduled
        - in_flight
        - deleted
        - errored
        - sent
        - imported
      type: string
    Email:
      title: Email
      description: >-
        Emails are what you're for here on Buttondown at the end of the day,
        right?

        Creating an email via the API is just like creating one in the
        interface;

        it will instantly trigger sending actual emails,

        based on the tags and email type you provide.
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
        included_tags:
          title: Included Tags
          type: array
          items:
            type: string
            format: uuid
        excluded_tags:
          title: Excluded Tags
          type: array
          items:
            type: string
            format: uuid
        publish_date:
          title: Publish Date
          type: string
          format: date-time
        subject:
          title: Subject
          type: string
        body:
          title: Body
          type: string
        secondary_id:
          title: Secondary Id
          type: integer
        email_type:
          $ref: '#/components/schemas/EmailType'
        slug:
          title: Slug
          type: string
        external_url:
          title: External Url
          type: string
        status:
          $ref: '#/components/schemas/EmailStatus'
        metadata:
          title: Metadata
          default: {}
          type: object
          additionalProperties:
            type: string
      required:
        - id
        - subject
        - body
        - email_type
        - slug
        - external_url
        - status
    EmailCreationErrorCode:
      title: EmailCreationErrorCode
      description: |2-

            Represents the type of error that occurred when creating an email.

            Human-readable error messages are provided in the `detail` field of the response;
            these values are meant to be parseable by code or client logic.
            
      enum:
        - subject_invalid
        - email_duplicate
        - email_invalid
      type: string
    ErrorMessage_EmailCreationErrorCode_:
      title: ErrorMessage[EmailCreationErrorCode]
      type: object
      properties:
        code:
          $ref: '#/components/schemas/EmailCreationErrorCode'
        detail:
          title: Detail
          type: string
        metadata:
          title: Metadata
          default: {}
          type: object
          additionalProperties:
            type: string
      required:
        - code
        - detail
    EmailInput:
      title: EmailInput
      type: object
      properties:
        included_tags:
          title: Included Tags
          default: []
          type: array
          items:
            anyOf:
              - type: string
                format: uuid
              - type: string
        excluded_tags:
          title: Excluded Tags
          default: []
          type: array
          items:
            anyOf:
              - type: string
                format: uuid
              - type: string
        publish_date:
          title: Publish Date
          type: string
          format: date-time
        subject:
          title: Subject
          type: string
        body:
          title: Body
          default: ''
          type: string
        email_type:
          $ref: '#/components/schemas/EmailType'
        status:
          $ref: '#/components/schemas/EmailStatus'
        metadata:
          title: Metadata
          default: {}
          type: object
          additionalProperties:
            type: string
      required:
        - subject
      x-konfig-properties:
        email_type:
          default: public
        status:
          default: about_to_send
    Page_Email_:
      title: Page[Email]
      type: object
      properties:
        results:
          title: Results
          type: array
          items:
            $ref: '#/components/schemas/Email'
        next:
          title: Next
          type: string
        previous:
          title: Previous
          type: string
        count:
          title: Count
          type: integer
      required:
        - results
        - count
    Analytics:
      title: Analytics
      type: object
      properties:
        recipients:
          title: Recipients
          type: integer
        deliveries:
          title: Deliveries
          type: integer
        opens:
          title: Opens
          type: integer
        clicks:
          title: Clicks
          type: integer
        temporary_failures:
          title: Temporary Failures
          type: integer
        permanent_failures:
          title: Permanent Failures
          type: integer
        unsubscriptions:
          title: Unsubscriptions
          type: integer
        complaints:
          title: Complaints
          type: integer
      required:
        - recipients
        - deliveries
        - opens
        - clicks
        - temporary_failures
        - permanent_failures
        - unsubscriptions
        - complaints
    SubscriberType:
      title: Type
      description: |2-

                Represents the state of a subscriber and what emails they
                should or should not be receiving. This type is meant to be fully expressive
                so as to consolidate the logic of determining what emails a subscriber should
                receive into a single place.
                
      enum:
        - regular
        - premium
        - churning
        - past_due
        - gifted
        - unpaid
        - unactivated
        - unsubscribed
        - spammy
        - removed
        - trialed
        - disabled
        - paused
      type: string
    SubscriberSource:
      title: Source
      description: |2-

                Represents the original provenance of a subscriber. This value is not exposed
                to subscribers; it's only used for internal tracking purposes and governs some
                of the behavior of the subscriber (i.e. whether or not to require double
                opt-in.)
                
      enum:
        - api
        - import
        - organic
        - user
        - admin
      type: string
    Subscriber:
      title: Subscriber
      description: |-
        Subscribers are the main way you collect email addresses and
        recipients on Buttondown. They're what you see on your
        [subscribers page](https://buttondown.email/subscribers).
      type: object
      properties:
        tags:
          title: Tags
          default: []
          type: array
          items:
            type: string
        id:
          title: Id
          type: string
          format: uuid
        email:
          title: Email
          type: string
        notes:
          title: Notes
          default: ''
          type: string
        metadata:
          title: Metadata
          default: {}
          type: object
        referrer_url:
          title: Referrer Url
          default: ''
          type: string
        creation_date:
          title: Creation Date
          type: string
          format: date-time
        secondary_id:
          title: Secondary Id
          type: integer
        subscriber_type:
          $ref: '#/components/schemas/SubscriberType'
        source:
          $ref: '#/components/schemas/SubscriberSource'
        utm_campaign:
          title: Utm Campaign
          type: string
        utm_medium:
          title: Utm Medium
          type: string
        utm_source:
          title: Utm Source
          type: string
      required:
        - id
        - email
        - creation_date
        - secondary_id
        - subscriber_type
        - source
        - utm_campaign
        - utm_medium
        - utm_source
    SubscriberInput:
      title: SubscriberInput
      type: object
      properties:
        tags:
          title: Tags
          default: []
          type: array
          items:
            type: string
        email:
          title: Email
          type: string
        notes:
          title: Notes
          default: ''
          type: string
        metadata:
          title: Metadata
          default: {}
          type: object
        referrer_url:
          title: Referrer Url
          default: ''
          type: string
      required:
        - email
    Page_Subscriber_:
      title: Page[Subscriber]
      type: object
      properties:
        results:
          title: Results
          type: array
          items:
            $ref: '#/components/schemas/Subscriber'
        next:
          title: Next
          type: string
        previous:
          title: Previous
          type: string
        count:
          title: Count
          type: integer
      required:
        - results
        - count
    ListSubscribersErrorCode:
      title: ListSubscribersErrorCode
      description: |2-

            Represents the type of error that occurred when listing subscribers.

            Human-readable error messages are provided in the `detail` field of the response;
            these values are meant to be parseable by code or client logic.
            
      enum:
        - invalid_tag
      type: string
    ErrorMessage_ListSubscribersErrorCode_:
      title: ErrorMessage[ListSubscribersErrorCode]
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ListSubscribersErrorCode'
        detail:
          title: Detail
          type: string
        metadata:
          title: Metadata
          default: {}
          type: object
          additionalProperties:
            type: string
      required:
        - code
        - detail
    UpdateSubscriberErrorCode:
      title: UpdateSubscriberErrorCode
      description: |2-

            Represents the type of error that occurred when updating a subscriber.

            Human-readable error messages are provided in the `detail` field of the response;
            these values are meant to be parseable by code or client logic.
            
      enum:
        - email_already_exists
        - email_invalid
        - subscriber_type_invalid
      type: string
    ErrorMessage_UpdateSubscriberErrorCode_:
      title: ErrorMessage[UpdateSubscriberErrorCode]
      type: object
      properties:
        code:
          $ref: '#/components/schemas/UpdateSubscriberErrorCode'
        detail:
          title: Detail
          type: string
        metadata:
          title: Metadata
          default: {}
          type: object
          additionalProperties:
            type: string
      required:
        - code
        - detail
    SubscriberUpdateInput:
      title: SubscriberUpdateInput
      type: object
      properties:
        tags:
          title: Tags
          type: array
          items:
            type: string
        email:
          title: Email
          type: string
        notes:
          title: Notes
          type: string
        metadata:
          title: Metadata
          type: object
        referrer_url:
          title: Referrer Url
          default: ''
          type: string
        subscriber_type:
          $ref: '#/components/schemas/SubscriberType'
    Newsletter:
      title: Newsletter
      description: |-
        You will likely not need to interact with your newsletter settings
        programmatically, but if you do, this is the endpoint for you. You can
        create, update, and list newsletters via the API; this is ideal for
        integrating with Buttondown as a headless email or newsletter provider
        (e.g. for a SaaS product.)
      type: object
      properties:
        description:
          title: Description
          type: string
        id:
          title: Id
          type: string
          format: uuid
        username:
          title: Username
          type: string
        name:
          title: Name
          type: string
        creation_date:
          title: Creation Date
          type: string
          format: date-time
        api_key:
          title: Api Key
          type: string
          format: uuid
      required:
        - id
        - username
        - name
        - description
        - creation_date
        - api_key
    Page_Newsletter_:
      title: Page[Newsletter]
      type: object
      properties:
        results:
          title: Results
          type: array
          items:
            $ref: '#/components/schemas/Newsletter'
        next:
          title: Next
          type: string
        previous:
          title: Previous
          type: string
        count:
          title: Count
          type: integer
      required:
        - results
        - count
    CreateNewsletterErrorCode:
      title: CreateNewsletterErrorCode
      description: |2-

            Represents the type of error that occurred when creating a newsletter.

            Human-readable error messages are provided in the `detail` field of the response;
            these values are meant to be parseable by code or client logic.
            
      enum:
        - username_already_exists
      type: string
    ErrorMessage_CreateNewsletterErrorCode_:
      title: ErrorMessage[CreateNewsletterErrorCode]
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CreateNewsletterErrorCode'
        detail:
          title: Detail
          type: string
        metadata:
          title: Metadata
          default: {}
          type: object
          additionalProperties:
            type: string
      required:
        - code
        - detail
    NewsletterInput:
      title: NewsletterInput
      type: object
      properties:
        description:
          title: Description
          type: string
        username:
          title: Username
          type: string
        name:
          title: Name
          type: string
      required:
        - username
        - name
        - description
    NewsletterUpdateInput:
      title: NewsletterUpdateInput
      type: object
      properties:
        description:
          title: Description
          type: string
        username:
          title: Username
          type: string
        name:
          title: Name
          type: string
    BulkActionStatus:
      title: Status
      description: |2-

                Represents the status of a bulk action.

                No action is required to move from one state or another; Buttondown
                internally handles the transitions, and exposing the status is for
                observability purposes only.
                
      enum:
        - not_started
        - in_progress
        - processed
        - failed
      type: string
    BulkActionType:
      title: Type
      description: |2-

                Represents the action being performed on a bulk of objects.

                (Not to be coy, but these names should be self-explanatory.)
                
      enum:
        - apply_tags
        - apply_metadata
        - ban_subscribers
        - delete_emails
        - delete_subscribers
        - delete_tags
        - reactivate_subscribers
        - replay_events
        - resubscribe_subscribers
        - send_emails
        - send_reminders
        - update_email_types
        - unsubscribe_subscribers
      type: string
    BulkAction:
      title: BulkAction
      description: >-
        A bulk action represents, well, a bulk action. It is used to perform

        actions on a large number of objects at once. For example, you can

        use it to delete a large number of emails, or to unsubscribe a large

        number of subscribers. The actions within a bulk action are processed

        serially by Buttondown; this should be considered an ergonomic way to

        batch API calls across the network rather than a net-new piece of
        functionality

        in of itself.
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
        creation_date:
          title: Creation Date
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/BulkActionStatus'
        type:
          $ref: '#/components/schemas/BulkActionType'
        completion_date:
          title: Completion Date
          type: string
          format: date-time
        metadata:
          title: Metadata
          type: object
          additionalProperties:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
              - type: object
      required:
        - id
        - creation_date
        - status
        - type
        - metadata
    BulkActionInput:
      title: BulkActionInput
      type: object
      properties:
        type:
          $ref: '#/components/schemas/BulkActionType'
        metadata:
          title: Metadata
          type: object
          additionalProperties:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
              - type: object
      required:
        - type
        - metadata
    ImageCreateNewImageRequest:
      title: FileParams
      type: object
      properties:
        image:
          title: Image
          type: string
          format: binary
      required:
        - image
  securitySchemes:
    GlobalAuth:
      type: http
      scheme: token