The Emails API from Buttondown — 11 operation(s) covering drafting, scheduling, publishing, rendering and analyzing newsletter emails.
openapi: 3.1.0
info:
title: Buttondown Emails 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: Emails
paths:
/emails:
post:
operationId: create_email
summary: Create Email
parameters: []
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Email'
links:
retrieve_email:
operationId: retrieve_email
parameters:
path.id: $response.body#/id
update_email:
operationId: update_email
parameters:
path.id: $response.body#/id
delete_email:
operationId: delete_email
parameters:
path.id: $response.body#/id
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_EmailCreationErrorCode_'
'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 email
tags:
- Emails
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmailInput'
required: true
security:
- ApiKeyAuth: []
get:
operationId: list_emails
summary: List Emails
parameters:
- in: query
name: status
schema:
description: If provided, only return [emails](https://docs.buttondown.com/api-emails-introduction) with the given
status.
items:
$ref: '#/components/schemas/EmailStatus'
title: Status
type: array
required: false
description: If provided, only return [emails](https://docs.buttondown.com/api-emails-introduction) with the given
status.
- in: query
name: -status
schema:
description: If provided, only return [emails](https://docs.buttondown.com/api-emails-introduction) without the
given status.
example:
- draft
items:
$ref: '#/components/schemas/EmailStatus'
title: -Status
type: array
required: false
description: If provided, only return [emails](https://docs.buttondown.com/api-emails-introduction) without the given
status.
example:
- draft
- in: query
name: ids
schema:
description: If provided, only return emails with the given IDs.
items:
pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:em)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
type: string
title: Ids
type: array
required: false
description: If provided, only return emails with the given IDs.
- in: query
name: ordering
schema:
allOf:
- enum:
- creation_date
- -creation_date
- status
- -status
- publish_date
- -publish_date
- subject
- -subject
- email_type
- -email_type
- modification_date
- -modification_date
- clicks
- -clicks
- opens
- -opens
- click_rate
- -click_rate
- open_rate
- -open_rate
- page_views_lifetime
- -page_views_lifetime
- page_views_30
- -page_views_30
- page_views_7
- -page_views_7
- webmentions
- -webmentions
- subscriptions
- -subscriptions
- paid_subscriptions
- -paid_subscriptions
- unsubscriptions
- -unsubscriptions
- replies
- -replies
- comments
- -comments
- social_mentions
- -social_mentions
- permanent_failure_rate
- -permanent_failure_rate
- complaint_rate
- -complaint_rate
title: Ordering
type: string
default: creation_date
description: The ordering to apply to the results.
example: -publish_date
required: false
description: The ordering to apply to the results.
example: -publish_date
- in: query
name: creation_date__start
schema:
description: If provided, only return emails created after the given date.
title: Creation Date Start
format: date
type: string
required: false
description: If provided, only return emails created after the given date.
- in: query
name: creation_date__end
schema:
description: If provided, only return emails created before the given date.
title: Creation Date End
format: date
type: string
required: false
description: If provided, only return emails created before the given date.
- in: query
name: publish_date__start
schema:
description: If provided, only return emails published after the given date.
title: Publish Date Start
format: date
type: string
required: false
description: If provided, only return emails published after the given date.
- in: query
name: publish_date__end
schema:
description: If provided, only return emails published before the given date.
title: Publish Date End
format: date
type: string
required: false
description: If provided, only return emails published before the given date.
- in: query
name: excluded_fields
schema:
description: If provided, exclude the given field(s) from the response. This can improve performance for large responses.
example:
- body
items:
$ref: '#/components/schemas/EmailExcludableField'
title: Excluded Fields
type: array
required: false
description: If provided, exclude the given field(s) from the response. This can improve performance for large responses.
example:
- body
- in: query
name: source
schema:
description: If provided, only return emails from the given source(s).
example:
- api
items:
$ref: '#/components/schemas/EmailSource'
title: Source
type: array
required: false
description: If provided, only return emails from the given source(s).
example:
- api
- in: query
name: archival_mode
schema:
description: If provided, only return emails with the given archival mode.
items:
$ref: '#/components/schemas/ArchivalMode'
title: Archival Mode
type: array
required: false
description: If provided, only return emails with the given archival mode.
- in: query
name: email_type
schema:
deprecated: true
description: The type of emails to return. Defaults to all types.
items:
$ref: '#/components/schemas/EmailType'
title: Email Type
type: array
required: false
description: The type of emails to return. Defaults to all types.
deprecated: true
- in: query
name: subject
schema:
description: If provided, only return emails with a subject that contains the given string.
title: Subject
type: string
required: false
description: If provided, only return emails with a subject that contains the given string.
- in: query
name: attachments
schema:
description: If provided, only return emails with the given attachments.
items:
pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:att)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
type: string
title: Attachments
type: array
required: false
description: If provided, only return emails with the given attachments.
- in: query
name: snippet_id
schema:
description: If provided, only return emails that reference the given [snippets](https://docs.buttondown.com/api-snippets-introduction).
items:
pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:snip)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
type: string
title: Snippet Id
type: array
required: false
description: If provided, only return emails that reference the given [snippets](https://docs.buttondown.com/api-snippets-introduction).
- in: query
name: deliveries__start
schema:
description: If provided, only return emails with at least this many deliveries.
example: 100
title: Deliveries Start
type: integer
required: false
description: If provided, only return emails with at least this many deliveries.
example: 100
- in: query
name: deliveries__end
schema:
description: If provided, only return emails with at most this many deliveries.
example: 1000
title: Deliveries End
type: integer
required: false
description: If provided, only return emails with at most this many deliveries.
example: 1000
- in: query
name: click_rate__start
schema:
description: If provided, only return emails with a click rate greater than or equal to the given value.
example: 0.1
title: Click Rate Start
type: number
required: false
description: If provided, only return emails with a click rate greater than or equal to the given value.
example: 0.1
- in: query
name: click_rate__end
schema:
description: If provided, only return emails with a click rate less than or equal to the given value.
example: 0.5
title: Click Rate End
type: number
required: false
description: If provided, only return emails with a click rate less than or equal to the given value.
example: 0.5
- in: query
name: open_rate__start
schema:
description: If provided, only return emails with an open rate greater than or equal to the given value.
example: 0.2
title: Open Rate Start
type: number
required: false
description: If provided, only return emails with an open rate greater than or equal to the given value.
example: 0.2
- in: query
name: open_rate__end
schema:
description: If provided, only return emails with an open rate less than or equal to the given value.
example: 0.8
title: Open Rate End
type: number
required: false
description: If provided, only return emails with an open rate less than or equal to the given value.
example: 0.8
- 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/EmailPage'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_EmailListErrorCode_'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: Not Found
'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: List all emails
tags:
- Emails
security:
- ApiKeyAuth: []
/emails/{id}:
patch:
operationId: update_email
summary: Update Email
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Email'
links:
retrieve_email:
operationId: retrieve_email
parameters:
path.id: $response.body#/id
delete_email:
operationId: delete_email
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 email's properties
tags:
- Emails
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmailUpdateInput'
required: true
security:
- ApiKeyAuth: []
get:
operationId: retrieve_email
summary: Retrieve Email
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Email'
links:
update_email:
operationId: update_email
parameters:
path.id: $response.body#/id
delete_email:
operationId: delete_email
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
'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: Retrieve a specific email by its ID
tags:
- Emails
security:
- ApiKeyAuth: []
delete:
operationId: delete_email
summary: Delete Email
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
'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: Delete an email
tags:
- Emails
security:
- ApiKeyAuth: []
/emails/{id}/history:
get:
operationId: retrieve_email_history
summary: Retrieve Email History
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
- in: query
name: expand
schema:
description: If provided, expand the given field.
items:
const: user
type: string
title: Expand
type: array
required: false
description: If provided, expand the given field.
- in: query
name: field
schema:
description: The field to retrieve history for.
minLength: 1
title: Field
type: string
required: true
description: The field to retrieve history for.
- in: query
name: page
schema:
description: The page number of the paginated response.
example: 1
title: Page
type: integer
required: false
description: The page number of the paginated response.
example: 1
- in: query
name: ordering
schema:
default: creation_date
description: The ordering to apply to the results.
enum:
- creation_date
- -creation_date
title: Ordering
type: string
required: false
description: The ordering to apply to the results.
- in: query
name: query
schema:
description: If provided, only return history entries matching the given query.
title: Query
type: string
required: false
description: If provided, only return history entries matching the given query.
- in: query
name: page_size
schema:
default: 100
description: The number of results per page.
title: Page Size
type: integer
required: false
description: The number of results per page.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/HistoryPage'
'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: Retrieve the edit history for a specific email
tags:
- Emails
security:
- ApiKeyAuth: []
/emails/{id}/history/body/{history_id}:
get:
operationId: retrieve_email_history_by_id
summary: Retrieve Email History By Id
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
- in: path
name: history_id
schema:
title: History Id
type: integer
required: true
- in: query
name: expand
schema:
description: If provided, expand the given field.
items:
const: user
type: string
title: Expand
type: array
required: false
description: If provided, expand the given field.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/History'
'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: Retrieve a specific historical version of an email's body
tags:
- Emails
security:
- ApiKeyAuth: []
/emails/{id}/analytics:
get:
operationId: retrieve_email_analytics
summary: Retrieve Email 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
'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: Retrieve analytics for a specific email
tags:
- Emails
security:
- ApiKeyAuth: []
/emails/{id}/renders:
get:
operationId: retrieve_email_renders
summary: Retrieve Email Renders
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
- in: query
name: target
schema:
description: The target format for the rendered HTML. Use 'email' for rendered_html_for_email or 'html' for rendered_html_for_web.
enum:
- email
- html
title: Target
type: string
required: true
description: The target format for the rendered HTML. Use 'email' for rendered_html_for_email or 'html' for rendered_html_for_web.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Render'
'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 Fo
# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/buttondown/refs/heads/main/openapi/buttondown-emails-api-openapi.yml