Buttondown

Buttondown API

The Buttondown API is a RESTful HTTP API that enables programmatic management of newsletters, subscribers, emails, drafts, tags, automations, surveys, and webhooks. Authentication is via API keys issued in the Buttondown dashboard, and the API powers both first-party and third-party tooling on the platform.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.buttondown.com/api

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/buttondown/refs/heads/main/openapi/buttondown-openapi.yml

Other Resources

🔗
Developer Portal
https://docs.buttondown.com/
🔗
API Keys
https://buttondown.com/requests
🔗
ChangeLog
https://docs.buttondown.com/changelog
🔗
StatusPage
https://buttondown.statuspage.io/

OpenAPI Specification

buttondown-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Buttondown API
  version: "1.0"
  description: >-
    Minimal OpenAPI 3.1 description of the Buttondown newsletter platform API.
    Covers core RESTful resources for subscribers, emails, tags, newsletters,
    and webhooks. Derived from the public Buttondown documentation.
  x-generated-from: https://docs.buttondown.com/api
  x-generated-by: claude-crawl-2026-05-08
servers:
  - url: https://api.buttondown.email/v1
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: Subscribers
  - name: Emails
  - name: Tags
  - name: Newsletters
  - name: Webhooks
paths:
  /subscribers:
    get:
      tags: [Subscribers]
      summary: List all subscribers
      operationId: listSubscribers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedList' }
    post:
      tags: [Subscribers]
      summary: Create a subscriber
      operationId: createSubscriber
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Resource' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Resource' }
  /subscribers/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    get:
      tags: [Subscribers]
      summary: Retrieve a subscriber
      operationId: getSubscriber
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Resource' }
    patch:
      tags: [Subscribers]
      summary: Update a subscriber
      operationId: updateSubscriber
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Resource' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Resource' }
    delete:
      tags: [Subscribers]
      summary: Delete a subscriber
      operationId: deleteSubscriber
      responses:
        '204':
          description: Deleted
  /emails:
    get:
      tags: [Emails]
      summary: List emails (drafts, scheduled, sent)
      operationId: listEmails
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedList' }
    post:
      tags: [Emails]
      summary: Create an email
      operationId: createEmail
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Resource' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Resource' }
  /emails/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    get:
      tags: [Emails]
      summary: Retrieve an email
      operationId: getEmail
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Resource' }
  /tags:
    get:
      tags: [Tags]
      summary: List all tags
      operationId: listTags
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedList' }
    post:
      tags: [Tags]
      summary: Create a tag
      operationId: createTag
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Resource' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Resource' }
  /tags/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    get:
      tags: [Tags]
      summary: Retrieve a tag
      operationId: getTag
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Resource' }
  /newsletters:
    get:
      tags: [Newsletters]
      summary: List all newsletters
      operationId: listNewsletters
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedList' }
  /webhooks:
    get:
      tags: [Webhooks]
      summary: List all webhooks
      operationId: listWebhooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedList' }
    post:
      tags: [Webhooks]
      summary: Create a webhook
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Resource' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Resource' }
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API token in the form `Token <api-key>`.
  parameters:
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
  schemas:
    Resource:
      type: object
      additionalProperties: true
    PaginatedList:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
      additionalProperties: true