openapi: 3.1.0
info:
  title: Buttondown Automations API
  version: 1.0.0
  description: The Buttondown API lets you manage newsletters, subscribers, emails, and more. See [the documentation](https://docs.buttondown.com/api-introduction)
    for guides and examples.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.buttondown.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Automations
paths:
  /automations:
    get:
      operationId: list_automations
      summary: List Automations
      parameters:
      - in: query
        name: page
        required: false
        description: The page number of the paginated response.
        schema:
          type: integer
          title: Page
          description: The page number of the paginated response.
          default: 1
          example: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationPage'
              examples:
                list_automations:
                  summary: List automations
                  value:
                    results:
                    - id: '{{ id }}'
                      creation_date: '2020-01-01T00:00:00Z'
                      name: Forward replies to support
                      status: inactive
                      trigger: subscriber.replied
                      actions:
                      - type: forward_reply
                        metadata:
                          recipient: support@example.com
                        timing: null
                      filters:
                        filters: []
                        groups: []
                        predicate: and
                      metadata: {}
                      should_evaluate_filter_after_delay: false
                    next: null
                    previous: null
                    count: 1
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: List all automations
      tags:
      - Automations
      security:
      - ApiKeyAuth: []
    post:
      operationId: create_automation
      summary: Create Automation
      parameters: []
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Automation'
              examples:
                create_automation:
                  summary: Create an automation
                  value:
                    id: '{{ id }}'
                    creation_date: '2020-01-01T00:00:00Z'
                    name: Forward replies to support
                    status: inactive
                    trigger: subscriber.replied
                    actions:
                    - type: forward_reply
                      metadata:
                        recipient: support@example.com
                      timing: null
                    filters:
                      filters: []
                      groups: []
                      predicate: and
                    metadata: {}
                    should_evaluate_filter_after_delay: false
                create_send_email_automation:
                  summary: Create an automation that sends an existing draft
                  value:
                    id: '{{ id }}'
                    creation_date: '2020-01-01T00:00:00Z'
                    name: Send welcome email on confirmation
                    status: inactive
                    trigger: subscriber.confirmed
                    actions:
                    - type: send_email
                      metadata:
                        email_id: '{{ email.id }}'
                      timing: null
                    filters:
                      filters: []
                      groups: []
                      predicate: and
                    metadata: {}
                    should_evaluate_filter_after_delay: false
          links:
            retrieve_automation:
              operationId: retrieve_automation
              parameters:
                path.id: $response.body#/id
            update_automation:
              operationId: update_automation
              parameters:
                path.id: $response.body#/id
            delete_automation:
              operationId: delete_automation
              parameters:
                path.id: $response.body#/id
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_AutomationCreationErrorCode_'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: Create a new automation
      tags:
      - Automations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationInput'
            examples:
              create_automation:
                summary: Create an automation
                value:
                  name: Forward replies to support
                  trigger: subscriber.replied
                  filters:
                    filters: []
                    groups: []
                    predicate: and
                  actions:
                  - type: forward_reply
                    metadata:
                      recipient: support@example.com
              create_send_email_automation:
                summary: Create an automation that sends an existing draft
                value:
                  name: Send welcome email on confirmation
                  trigger: subscriber.confirmed
                  filters:
                    filters: []
                    groups: []
                    predicate: and
                  actions:
                  - type: send_email
                    metadata:
                      email_id: '{{ email.id }}'
        required: true
      security:
      - ApiKeyAuth: []
  /automations/{id}:
    get:
      operationId: retrieve_automation
      summary: Retrieve Automation
      parameters:
      - in: path
        name: id
        schema:
          title: Id
          type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Automation'
              examples:
                retrieve_automation:
                  summary: Retrieve an automation
                  value:
                    id: '{{ id }}'
                    creation_date: '2020-01-01T00:00:00Z'
                    name: Forward replies to support
                    status: inactive
                    trigger: subscriber.replied
                    actions:
                    - type: forward_reply
                      metadata:
                        recipient: support@example.com
                      timing: null
                    filters:
                      filters: []
                      groups: []
                      predicate: and
                    metadata: {}
                    should_evaluate_filter_after_delay: false
          links:
            update_automation:
              operationId: update_automation
              parameters:
                path.id: $response.body#/id
            delete_automation:
              operationId: delete_automation
              parameters:
                path.id: $response.body#/id
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: Retrieve a specific automation by its ID
      tags:
      - Automations
      security:
      - ApiKeyAuth: []
    patch:
      operationId: update_automation
      summary: Update Automation
      parameters:
      - in: path
        name: id
        schema:
          title: Id
          type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Automation'
          links:
            retrieve_automation:
              operationId: retrieve_automation
              parameters:
                path.id: $response.body#/id
            delete_automation:
              operationId: delete_automation
              parameters:
                path.id: $response.body#/id
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: Update an automation's properties
      tags:
      - Automations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationUpdateInput'
        required: true
      security:
      - ApiKeyAuth: []
    delete:
      operationId: delete_automation
      summary: Delete Automation
      parameters:
      - in: path
        name: id
        schema:
          title: Id
          type: string
        required: true
      responses:
        '204':
          description: No Content
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: Delete an automation
      tags:
      - Automations
      security:
      - ApiKeyAuth: []
  /automations/{id}/invoke:
    post:
      operationId: invoke_automation
      summary: Invoke Automation
      parameters:
      - in: path
        name: id
        schema:
          title: Id
          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'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: Manually trigger an automation
      tags:
      - Automations
      security:
      - ApiKeyAuth: []
  /automations/{id}/analytics:
    get:
      operationId: retrieve_automation_analytics
      summary: Retrieve Automation Analytics
      parameters:
      - in: path
        name: id
        schema:
          title: Id
          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'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: Retrieve analytics data for an automation
      tags:
      - Automations
      security:
      - ApiKeyAuth: []
components:
  schemas:
    Action:
      description: An action to perform when the automation's trigger fires.
      properties:
        type:
          $ref: '#/components/schemas/AutomationActionType'
          description: The type of action to perform.
        metadata:
          additionalProperties: true
          description: Configuration specific to the action type.
          title: Metadata
          type: object
        timing:
          anyOf:
          - $ref: '#/components/schemas/Timing'
          - type: 'null'
          description: When to execute this action. Defaults to immediate if not specified.
      required:
      - type
      - metadata
      title: Action
      type: object
    ActionInput:
      additionalProperties: false
      description: Request payload for an action to perform when the automation's trigger fires.
      properties:
        type:
          $ref: '#/components/schemas/AutomationActionType'
          description: The type of action to perform.
        metadata:
          additionalProperties: true
          description: Configuration specific to the action type.
          maxProperties: 100
          title: Metadata
          type: object
        timing:
          anyOf:
          - $ref: '#/components/schemas/TimingInput'
          - type: 'null'
          description: When to execute this action. Defaults to immediate if not specified.
      required:
      - type
      title: ActionInput
      type: object
    Analytics:
      properties:
        recipients:
          default: 0
          description: The number of subscribers the email was dispatched to.
          title: Recipients
          type: integer
        deliveries:
          default: 0
          description: The number of successful deliveries (recipients minus failures).
          title: Deliveries
          type: integer
        opens:
          default: 0
          description: The number of unique opens recorded.
          title: Opens
          type: integer
        clicks:
          default: 0
          description: The number of unique link clicks recorded.
          title: Clicks
          type: integer
        temporary_failures:
          default: 0
          description: The number of temporary delivery failures (e.g. soft bounces).
          title: Temporary Failures
          type: integer
        permanent_failures:
          default: 0
          description: The number of permanent delivery failures (e.g. hard bounces).
          title: Permanent Failures
          type: integer
        unsubscriptions:
          default: 0
          description: The number of subscribers who unsubscribed after receiving this email.
          title: Unsubscriptions
          type: integer
        complaints:
          default: 0
          description: The number of spam complaints recorded against this email.
          title: Complaints
          type: integer
        survey_responses:
          default: 0
          description: The number of survey responses submitted from this email.
          title: Survey Responses
          type: integer
        webmentions:
          default: 0
          description: The number of inbound webmentions received for this email.
          title: Webmentions
          type: integer
        page_views_lifetime:
          default: 0
          description: The total number of archive page views for this email since publication.
          title: Page Views Lifetime
          type: integer
        page_views_30:
          default: 0
          description: The number of archive page views in the last 30 days.
          title: Page Views 30
          type: integer
        page_views_7:
          default: 0
          description: The number of archive page views in the last 7 days.
          title: Page Views 7
          type: integer
        subscriptions:
          default: 0
          description: The number of new subscribers attributed to this email.
          title: Subscriptions
          type: integer
        paid_subscriptions:
          default: 0
          description: The number of new paid subscribers attributed to this email.
          title: Paid Subscriptions
          type: integer
        replies:
          default: 0
          description: The number of reply emails received from subscribers.
          title: Replies
          type: integer
        comments:
          default: 0
          description: The number of comments posted on this email.
          title: Comments
          type: integer
        social_mentions:
          default: 0
          description: The number of social media mentions of this email.
          title: Social Mentions
          type: integer
        temporary_failure_breakdown:
          description: Breakdown of temporary failures by reason code, sorted by count descending.
          items:
            $ref: '#/components/schemas/FailureBreakdownItem'
          title: Temporary Failure Breakdown
          type: array
        permanent_failure_breakdown:
          description: Breakdown of permanent failures by reason code, sorted by count descending.
          items:
            $ref: '#/components/schemas/FailureBreakdownItem'
          title: Permanent Failure Breakdown
          type: array
      title: Analytics
      type: object
    Automation:
      description: A rule that automatically performs actions in response to events.
      properties:
        id:
          description: A unique TypeID associated with the object.
          title: Id
          type: string
        creation_date:
          description: The date and time at which the object was first created.
          format: date-time
          title: Creation Date
          type: string
        name:
          description: The name of the automation.
          title: Name
          type: string
        status:
          $ref: '#/components/schemas/AutomationStatus'
          description: Whether the automation is enabled or disabled.
        trigger:
          $ref: '#/components/schemas/ExternalEventType'
          description: The event that causes this automation to run.
        actions:
          description: The actions to perform when the trigger fires.
          items:
            $ref: '#/components/schemas/Action'
          title: Actions
          type: array
        filters:
          $ref: '#/components/schemas/FilterGroup'
          description: Conditions that must be met for the automation to run.
        metadata:
          additionalProperties: true
          description: Additional metadata for the automation.
          title: Metadata
          type: object
        should_evaluate_filter_after_delay:
          description: If true, filters are re-evaluated after the delay has passed.
          title: Should Evaluate Filter After Delay
          type: boolean
      required:
      - id
      - creation_date
      - name
      - status
      - trigger
      - actions
      - filters
      - metadata
      - should_evaluate_filter_after_delay
      title: Automation
      type: object
    AutomationActionType:
      description: The action that is triggered when the automation is successfully run.
      enum:
      - add_tags
      - remove_tags
      - send_email
      - add_metadata
      - remove_metadata
      - change_email_address
      - gift_premium_subscription
      - ungift_premium_subscription
      - send_discord_invitation
      - send_github_invitation
      - create_subscriber
      - unsubscribe_subscriber
      - shopify_unsubscribe
      - shopify_resubscribe
      - shopify_set_tags
      - shopify_create_customer
      - send_notification
      - forward_reply
      - create_arena_post
      - create_bluesky_post
      - create_linkedin_post
      - create_mastodon_post
      - create_tumblr_post
      - create_twitter_post
      - create_export
      - create_gift_subscriber
      - send_post_request
      - send_confirmation_reminder
      - update_email_type
      title: ActionType
      type: string
    AutomationCreationErrorCode:
      description: 'Represents the type of error that occurred when creating an automation.


        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:
      - delay_invalid
      - filter_invalid__tag
      - filter_invalid
      - action_invalid
      - filter_invalid__field
      - invalid_newsletter_id
      - trigger_action_invalid
      - action_invalid__missing_body_or_subject
      title: AutomationCreationErrorCode
      type: string
    AutomationInput:
      additionalProperties: false
      properties:
        name:
          description: The name of the automation.
          maxLength: 100
          minLength: 1
          pattern: ^[^\x00-\x1f\x7f-\x9f]*[^\W_][^\x00-\x1f\x7f-\x9f]*$
          title: Name
          type: string
        trigger:
          $ref: '#/components/schemas/ExternalEventType'
          description: The event that causes this automation to run.
        actions:
          description: The actions to perform when the trigger fires.
          items:
            $ref: '#/components/schemas/ActionInput'
          maxItems: 25
          title: Actions
          type: array
        filters:
          anyOf:
          - $ref: '#/components/schemas/FilterGroup'
            description: Tag-based filtering rules used to decide which subscribers receive feed-generated emails.
          - type: 'null'
          description: Conditions that must be met for the automation to run. Omit or pass null for no filter.
        metadata:
          additionalProperties: true
          description: Additional metadata for the automation.
          maxProperties: 100
          propertyNames:
            maxLength: 100
          title: Metadata
          type: object
        should_evaluate_filter_after_delay:
          default: false
          description: If true, filters are re-evaluated after the delay has passed.
          title: Should Evaluate Filter After Delay
          type: boolean
      required:
      - name
      - trigger
      - actions
      title: AutomationInput
      type: object
    AutomationPage:
      properties:
        results:
          description: The list of results for this page.
          items:
            $ref: '#/components/schemas/Automation'
          title: Results
          type: array
        next:
          anyOf:
          - type: string
          - type: 'null'
          description: The URL to the next page of results, if any.
          title: Next
        previous:
          anyOf:
          - type: string
          - type: 'null'
          description: The URL to the previous page of results, if any.
          title: Previous
        count:
          description: The total number of results across all pages.
          title: Count
          type: integer
      required:
      - results
      - count
      title: Page[Automation]
      type: object
    AutomationStatus:
      enum:
      - active
      - inactive
      title: Status
      type: string
      description: An enumeration.
    AutomationUpdateInput:
      additionalProperties: false
      properties:
        name:
          anyOf:
          - maxLength: 100
            minLength: 1
            pattern: ^[^\x00-\x1f\x7f-\x9f]*[^\W_][^\x00-\x1f\x7f-\x9f]*$
            type: string
          - type: 'null'
          description: The name of the automation.
          title: Name
        status:
          anyOf:
          - $ref: '#/components/schemas/AutomationStatus'
          - type: 'null'
          description: Whether the automation is enabled or disabled.
        trigger:
          anyOf:
          - $ref: '#/components/schemas/ExternalEventType'
          - type: 'null'
          description: The event that causes this automation to run.
        timing:
          anyOf:
          - $ref: '#/components/schemas/TimingInput'
          - type: 'null'
          description: When to execute the automation's actions.
        actions:
          anyOf:
          - items:
              $ref: '#/components/schemas/ActionInput'
            maxItems: 25
            type: array
          - type: 'null'
          description: The actions to perform when the trigger fires.
          title: Actions
        filters:
          anyOf:
          - $ref: '#/components/schemas/FilterGroup'
            description: Tag-based filtering rules used to decide which subscribers receive feed-generated emails.
          - type: 'null'
          description: Conditions that must be met for the automation to run.
        metadata:
          anyOf:
          - additionalProperties: true
            maxProperties: 100
            propertyNames:
              maxLength: 100
            type: object
          - type: 'null'
          description: Additional metadata for the automation.
          title: Metadata
        should_evaluate_filter_after_delay:
          anyOf:
          - type: boolean
          - type: 'null'
          description: If true, filters are re-evaluated after the delay has passed.
          title: Should Evaluate Filter After Delay
      title: AutomationUpdateInput
      type: object
    Delay:
      description: Configuration for how long to wait before executing the automation's action.
      properties:
        value:
          description: The number of time units to delay.
          title: Value
          type: string
        unit:
          description: The unit of time for the delay.
          enum:
          - minutes
          - hours
          - days
          - weeks
          title: Unit
          type: string
        time_of_day:
          anyOf:
          - enum:
            - morning
            - evening
            - ''
            type: string
          - type: 'null'
          description: If set, the action will be executed at this time of day after the delay has passed.
          title: Time Of Day
      required:
      - value
      - unit
      title: Delay
      type: object
    DelayInput:
      additionalProperties: false
      description: Request payload configuration for delaying an automation action.
      properties:
        value:
          description: The number of time units to delay.
          maxLength: 16
          minLength: 1
          title: Value
          type: string
        unit:
          description: The unit of time for the delay.
          enum:
          - minutes
          - hours
          - days
          - weeks
          title: Unit
          type: string
        time_of_day:
          anyOf:
          - enum:
            - morning
            - evening
            - ''
            type: string
          - type: 'null'
          description: If set, the action will be executed at this time of day after the delay has passed.
          title: Time Of Day
      required:
      - value
      - unit
      title: DelayInput
      type: object
    ErrorMessage:
      properties:
        code:
          description: The error code.
          title: Code
          type: string
        detail:
          description: A human-readable description of the error.
          title: Detail
          type: string
        metadata:
          additionalProperties:
            type: string
          default: {}
          description: Additional context about the error. When present, a `documentation_url` key links to docs explaining
            how to resolve it.
          title: Metadata
          type: object
      required:
      - detail
      title: ErrorMessage
      type: object
    ErrorMessage_AutomationCreationErrorCode_:
      properties:
        code:
          allOf:
          - $ref: '#/components/schemas/AutomationCreationErrorCode'
          description: The error code.
        detail:
          description: A human-readable description of the error.
          title: Detail
          type: string
        metadata:
          additionalProperties:
            type: string
          default: {}
          description: Additional context about the error. When present, a `documentation_url` key links to docs explaining
            how to resolve it.
          title: Metadata
          type: object
      required:
      - detail
      title: ErrorMessage[AutomationCreationErrorCode]
      type: object
    ExternalEventType:
      description: 'Various types of events that are recorded by Buttondown, both in terms of exogenous systems

        like Stripe and Memberful, and endogenous ones like email opens and clicks. (In general, if anything

        important ever happens that could be relevant to your newsletter, we have an event type for it!)


        These event types power lots of things within Buttondown. They''re used to trigger automations, webhooks,

        and analytics.


        (Note that the `/v1/events` API speaks an older, shorter vocabulary for subscriber engagement —

        `clicked` rather than `subscriber.clicked` — a relic of a previous events system. Each of those

        names maps onto one of the `subscriber.*` types below.)


        In general, our event namespacing tries to hew to the following pattern:


        `<source>.<object>.<action>`


        When wondering which object we are referring to, default to the _more granular_ object.


        For instance, an email being sent to a subscriber is `subscriber.delivered`, not `email.sent`.'
      enum:
      - advertising_slot.inquiry
      - advertising_slot.purchased
      - automation.invoked
      - date.day.started
      - date.month.started
      - date.week.started
      - date.year.started
      - bigcommerce.customer.created
      - bigcommerce.customer.updated
      - bigcommerce.order.created
      - bigcommerce.order.updated
      - email.created
      - email.deleted
      - email.send.started
      - email.sent
      - email.status.changed
      - email.updated
      - external_feed_item.created
      - export.completed
      - export.created
      - export.failed
      - firewall.blocked
      - mention.created
      - memberful.member.updated
      - memberful.subscription.created
      - memberful.subscription.deleted
      - note.created
      - note.deleted
      - patreon.member.updated
      - patreon.membership.created
      - patreon.membership.deleted
      - shopify.customer.created
      - shopify.customer.updated
      - social_mention.created
      - stripe.checkout.session.completed
      - stripe.customer.updated
      - stripe.invoice.upcoming
      - stripe.subscription.activated
      - stripe.subscription.churning
      - stripe.subscription.deactivated
      - subscriber.activation_bounced
      - subscriber.activation_clicked
      - subscriber.activation_complained
      - subscriber.activation_deferred
      - subscriber.activation_delivered
      - subscriber.activation_opened
      - subscriber.activation_rejected
      - subscriber.bounced
      - subscriber.changed_email
      - subscriber.churned
      - subscriber.clicked
      - subscriber.commented
      - subscriber.complained
      - subscriber.confirmed
      - subscriber.created
      - subscriber.deferred
      - subscriber.deleted
      - subscriber.delivered
      - subscriber.opened
      - subscriber.paid
      - subscriber.paused
      - subscriber.resumed
      - subscriber.referred
      - subscriber.referred.paid
      - subscriber.rejected
      - subscriber.replied
      - subscriber.sent
      - subscriber.responded_to_survey
      - subscriber.tags.changed
      - subscriber.trial_ended
      - subscriber.trial_started
      - subscriber.type.changed
      - subscriber.unsubscribed
      - subscriber.updated
      - subscriber.viewed_checkout_page
      - survey.cleared_responses
      - survey.created
      - survey.deleted
      - survey.updated
      - form.created
      - form.deleted
      - form.updated
      title: Type
      type: string
    FailureBreakdownItem:
      description: A single failure reason with its count.
      properties:
        code:
          description: The failure reason code (e.g. 'hard_bounce', 'spam')
          title: Code
          type: string
        count:
          description: Number of failures with this reason
          title: Count
          type: integer
      required:
      - code
      - count
      title: FailureBreakdownItem
      type: object
    Filter:
      description: "A filter is a single condition that can be evaluated against a [Subscriber](/api-subscribers-retrieve).\
        \ It has a field, an operator, and a value:\n\n```json\n{\n    \"field\": \"subscriber.tags\",\n    \"operator\":\
        \ \"contains\",\n    \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40j\"\n}\n```\n\nThe field is the path to the field\
        \ on the subscriber to evaluate. The operator is the operator to use when evaluating the filter. The value is the\
        \ value to compare the field to. Tag filters require the tag's ID (either a UUID or TypeID), not its name."
      properties:
        field:
          title: Field
          type: string
        operator:
          $ref: '#/components/schemas/Operator'
        value:
          title: Value
          type: string
      required:
      - field
      - operator
      - value
      title: Filter
      type: object
    FilterGroup:
      description: "Buttondown's filtering schema can be used for multiple things:\n\n- Filtering [the audience of an email](/api-emails-create)\
        \ to a specific subset\n- Creating [finely-tuned automations](/api-automation-introduction)\n\nFilters are fractal;\
        \ they can be nested in groups, and groups can be nested in other groups. This is accomplished through a tree-like\
        \ structure. Every \"FilterGroup\" has a \"predicate\" field, which is either \"and\" or \"or\", which determines\
        \ how the filters and groups within the group are combined, a \"groups\" field, which is a list of \"FilterGroup\"\
        \ objects (that's that recursive bit!), and a \"filters\" field, which are the leaf-level filters themselves.\n\n\
        Let's say you want a simple filter: all subscribers who have a tag whose ID is `sub_tag_0j6hb7h40j6hb7h40j6hb7h40j`.\
        \ You can do that like this:\n\n```json\n{\n    \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\"\
        , \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40j\"}],\n    \"groups\": [],\n    \"predicate\": \"and\"\n}\n```\n\n\
        Now, let's say you want to filter for subscribers who have that tag and a tag whose ID is `sub_tag_0j6hb7h40j6hb7h40j6hb7h40k`.\
        \ You can do that like this:\n\n```json\n{\n    \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\"\
        , \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40j\"}, {\"field\": \"subscriber.tags\", \"operator\": \"contains\"\
        , \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40k\"}],\n    \"groups\": [],\n    \"predicate\": \"and\"\n}\n```\n\n\
        If you wanted to change that `and` to an `or`, you can do that like this:\n\n```json\n{\n    \"filters\": [{\"field\"\
        : \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40j\"}, {\"field\"\
        : \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40k\"}],\n    \"groups\"\
        : [],\n    \"predicate\": \"or\"\n}\n```\n\nNow, let's say you want to filter for subscribers who have the first tag\
        \ _or_ both the second tag and a third tag whose ID is `sub_tag_0j6hb7h40j6hb7h40j6hb7h40m`. This is where the whole\
        \ nested thing comes in handy. You can do that like this:\n\n```json\n{\n    \"filters\": [{\"field\": \"subscriber.tags\"\
        , \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40j\"}],\n    \"groups\": [\n        {\n\
        \            \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40k\"\
        }, {\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40m\"\
        }],\n            \"groups\": [],\n            \"predicate\": \"and\"\n        }\n    ],\n    \"predicate\": \"or\"\
        \n}\n```\n\nYou can read more about the specific filter construction in the [Filter documentation](/api-emails-filter)."
      properties:
        filters:
          description: The leaf-level filters to apply to the audience.
          items:
            $ref: '#/components/schemas/Filter'
          title: Filters
          type: array
        groups:
          description: The nested groups to apply to the audience.
          items:
            $ref: '#/components/schemas/FilterGroup'
          title: Groups
          type: array
        predicate:
          description: The logical operator to use when combining filters (either 'and' or 'or').
          enum:
          - and
          - or
          title: Predicate
          type: string
      required:
      - filters
      - groups
      - predicate
      title: FilterGroup
      type: object
    Operator:
      enum:
      - equals
      - not_equals
      - contains
      - not_contains
      - is_empty
      - is_not_empty
      - greater_than
      - less_than
      title: Operator
      type: string
      description: An enumeration.
    Timing:
      description: Controls when an automation's action executes after the trigger fires.
      properties:
        time:
          description: Whether the action should execute immediately or after a delay.
          enum:
          - immediate
          - delay
          title: Time
          type: string
        delay:
          anyOf:
          - $ref: '#/components/schemas/Delay'
          - type: 'null'
          description: The delay configuration. Required when `time` is `delay`; null when `time` is `immediate`.
      required:
      - time
      title: Timing
      type: object
    TimingInput:
      additionalProperties: false
      description: Request payload controls for when an automation action executes.
      properties:
        time:
          description: Whether the action should execute immediately or after a delay.
          enum:
          - immediate
          - delay
          title: Time
          type: string
        delay:
          anyOf:
          - $ref: '#/components/schemas/DelayInput'
          - type: 'null'
          description: The delay configuration. Required when `time` is `delay`; null when `time` is `immediate`.
      required:
      - time
      title: TimingInput
      type: object
    ValidationErrorDetail:
      properties:
        type:
          description: The type of validation error.
          title: Type
          type: string
        loc:
          description: The location of the error in the request.
          items:
            anyOf:
            - type: string
            - type: integer
          title: Loc
          type: array
        msg:
          description: A human-readable error message.
          title: Msg
          type: string
      required:
      - type
      - loc
      - msg
      title: ValidationErrorDetail
      type: object
    ValidationErrorMessage:
      properties:
        detail:
          description: A list of validation errors.
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
          title: Detail
          type: array
      required:
      - detail
      title: ValidationErrorMessage
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key passed as 'Token <your-api-key>' in the Authorization header.