Buttondown Automations API

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'
         

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/buttondown/refs/heads/main/openapi/buttondown-automations-api-openapi.yml