The Comments API from Buttondown — 5 operation(s) covering subscriber comments on emails, and their moderation state.
openapi: 3.1.0
info:
title: Buttondown Comments 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: Comments
paths:
/comments:
post:
operationId: create_comment
summary: Create Comment
parameters: []
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
links:
retrieve_comment:
operationId: retrieve_comment
parameters:
path.id: $response.body#/id
update_comment:
operationId: update_comment
parameters:
path.id: $response.body#/id
delete_comment:
operationId: delete_comment
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: Create a new comment or reply to an existing comment. If subscriber_id is provided, the comment is attributed
to that subscriber; otherwise it is attributed to the newsletter author.
tags:
- Comments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CommentInput'
required: true
security:
- ApiKeyAuth: []
get:
operationId: list_comments
summary: List Comments
parameters:
- in: query
name: email_id
schema:
description: If provided, only return comments for the given [email](https://docs.buttondown.com/api-emails-introduction).
example:
- em_01h8xg4j3k2m1n0p9q8r7s6t5v
title: Email Id
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
required: false
description: If provided, only return comments for the given [email](https://docs.buttondown.com/api-emails-introduction).
example:
- em_01h8xg4j3k2m1n0p9q8r7s6t5v
- in: query
name: subscriber_id
schema:
description: If provided, only return comments for the given [subscriber](https://docs.buttondown.com/api-subscribers-introduction).
example:
- sub_01h8xg4j3k2m1n0p9q8r7s6t5v
title: Subscriber Id
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}|(?:sub)_(?:[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
required: false
description: If provided, only return comments for the given [subscriber](https://docs.buttondown.com/api-subscribers-introduction).
example:
- sub_01h8xg4j3k2m1n0p9q8r7s6t5v
- in: query
name: parent_id
schema:
description: If provided, only return comments that are replies to the given parent comment.
example:
- com_01h8xg4j3k2m1n0p9q8r7s6t5v
title: Parent Id
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}|(?:com)_(?:[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
required: false
description: If provided, only return comments that are replies to the given parent comment.
example:
- com_01h8xg4j3k2m1n0p9q8r7s6t5v
- in: query
name: expand
schema:
description: 'If provided, expand the given field. (Only supported fields: ''subscriber'', ''email'').'
items:
enum:
- subscriber
- email
type: string
title: Expand
type: array
required: false
description: 'If provided, expand the given field. (Only supported fields: ''subscriber'', ''email'').'
- in: query
name: ordering
schema:
allOf:
- enum:
- creation_date
- -creation_date
- email
- -email
- subscriber
- -subscriber
title: Ordering
type: string
default: -creation_date
description: The ordering to apply to the results.
example: -creation_date
required: false
description: The ordering to apply to the results.
example: -creation_date
- in: query
name: status
schema:
description: If provided, only return comments with the given status. Only the newsletter owner can filter by status;
subscribers always see active comments.
$ref: '#/components/schemas/CommentStatus'
required: false
description: If provided, only return comments with the given status. Only the newsletter owner can filter by status;
subscribers always see active comments.
- 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/CommentPage'
'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
'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 comments
tags:
- Comments
security:
- ApiKeyAuth: []
/comments/{id}:
get:
operationId: retrieve_comment
summary: Retrieve Comment
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
links:
update_comment:
operationId: update_comment
parameters:
path.id: $response.body#/id
delete_comment:
operationId: delete_comment
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 comment by its ID
tags:
- Comments
security:
- ApiKeyAuth: []
patch:
operationId: update_comment
summary: Update Comment
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
links:
retrieve_comment:
operationId: retrieve_comment
parameters:
path.id: $response.body#/id
delete_comment:
operationId: delete_comment
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'
'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 a comment's status. Only the newsletter owner can call this.
tags:
- Comments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CommentUpdateInput'
required: true
security:
- ApiKeyAuth: []
delete:
operationId: delete_comment
summary: Delete Comment
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'
'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 a comment. Only the comment owner (subscriber) or the newsletter author can delete a comment.
tags:
- Comments
security:
- ApiKeyAuth: []
components:
schemas:
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
ArchivalMode:
description: 'Governs who can view this email in the archive.
`ARCHIVE_ONLY` is the odd one out: the email is publicly archived but
is not email content at all (e.g. an imported blog post), so it is
excluded from email-rendering contexts like "recent issues" widgets.'
enum:
- archive_only
- disabled
- enabled
- enabled_for_paid_subscribers
- enabled_for_subscribers
title: ArchivalMode
type: string
Callout:
description: 'Surfacing-time flags about an email that the UI uses to render contextual
callouts (e.g. in the analytics panel). Computed on read; not persisted.'
enum:
- first_send_on_sending_domain
title: Callout
type: string
Comment:
description: 'Comments are a way for subscribers to interact with newsletters. They''re a way to
provide feedback, ask questions, and generally engage with the content of an email.
Comments exist in a tree structure; comments that reply to other comments are
considered "children" of the parent comment.'
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
email_id:
description: The ID of the email this comment is attached to.
title: Email Id
type: string
subscriber_id:
anyOf:
- type: string
- type: 'null'
description: The ID of the subscriber who posted the comment, or null if posted by the newsletter author.
title: Subscriber Id
parent_id:
anyOf:
- type: string
- type: 'null'
description: The ID of the parent comment, if this comment is a reply to another comment.
title: Parent Id
text:
description: The text content of the comment.
title: Text
type: string
status:
$ref: '#/components/schemas/CommentStatus'
description: The moderation status of the comment (e.g. `active`, `spammy`).
subscriber:
anyOf:
- $ref: '#/components/schemas/Subscriber'
- type: 'null'
email:
anyOf:
- $ref: '#/components/schemas/Email'
- type: 'null'
required:
- id
- creation_date
- email_id
- text
- status
title: Comment
type: object
CommentInput:
additionalProperties: false
properties:
text:
description: The text content of the comment.
minLength: 1
pattern: '[\s\S]*\S[\s\S]*'
title: Text
type: string
parent_id:
anyOf:
- 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}|(?:com)_(?:[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
- type: 'null'
description: The ID of the parent comment, if this comment is a reply to another comment.
title: Parent Id
email_id:
anyOf:
- 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
- type: 'null'
description: The ID of the email this comment is for. Required if parent_id is not provided.
title: Email Id
subscriber_id:
anyOf:
- 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}|(?:sub)_(?:[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
- type: 'null'
description: The ID of the subscriber to attribute the comment to. If not provided, the comment is attributed to
the newsletter author.
title: Subscriber Id
required:
- text
title: CommentInput
type: object
CommentPage:
properties:
results:
description: The list of results for this page.
items:
$ref: '#/components/schemas/Comment'
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[Comment]
type: object
CommentStatus:
enum:
- pending
- active
- spammy
title: Status
type: string
description: An enumeration.
CommentUpdateInput:
additionalProperties: false
properties:
status:
description: The new status for the comment. Use 'active' to approve or 'spammy' to mark as spam.
enum:
- active
- spammy
title: Status
type: string
required:
- status
title: CommentUpdateInput
type: object
Email:
description: 'Emails are why you''re here on Buttondown, right?
Creating an email via the API is just like creating one in the interface;
it will instantly trigger sending actual emails,
based on the tags and email type you provide.
Relevant changes to the schema:
- [2024-08-15](https://docs.buttondown.com/api-changelog-2024-08-15): unshipped the `included_tags` and `excluded_tags`
fields.
- [2024-12-30](https://docs.buttondown.com/api-changelog-2024-12-30): unshipped the `is_comments_disabled` field,
and replaced it with a more flexible `commenting_mode` field.
- [2025-09-23](https://docs.buttondown.com/api-changelog-2025-09-23): increased the maximum length of the `subject`
field from 1000 to 2000 characters.'
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
absolute_url:
description: The canonical web URL of the email on the newsletter's archive.
title: Absolute Url
type: string
analytics:
anyOf:
- $ref: '#/components/schemas/Analytics'
- type: 'null'
description: Aggregate analytics for the email. Null until the email has been sent.
callouts:
description: A list of callouts that apply to this email — surfaced in the UI alongside analytics to flag context
the reader should know about (e.g., first send on a custom sending domain).
items:
$ref: '#/components/schemas/Callout'
title: Callouts
type: array
attachments:
anyOf:
- items:
type: string
type: array
- type: 'null'
description: A list of attachment IDs present on the email. (See [Attachments](https://docs.buttondown.com/api-attachments-introduction)
for more information.)
title: Attachments
body:
description: 'The body of the email, in either HTML or markdown format. Buttondown attempts to intelligently detect
the format of the body automatically, but you can also specify the format explicitly by prepending the text with
the `buttondown-editor-mode` comment: `<!-- buttondown-editor-mode: fancy -->` or `<!-- buttondown-editor-mode:
plaintext -->`.'
title: Body
type: string
canonical_url:
description: The URL of the original source of the content.
title: Canonical Url
type: string
commenting_mode:
$ref: '#/components/schemas/EmailCommentingMode'
description: Controls whether subscribers can comment on this email.
description:
description: A human-readable description of the email, used for archives and SEO.
title: Description
type: string
archival_mode:
$ref: '#/components/schemas/ArchivalMode'
description: Controls who can view this email in the archive.
email_type:
allOf:
- $ref: '#/components/schemas/EmailType'
default: public
deprecated: true
description: 'The type of email. Defaults to `PUBLIC`. Deprecated: this is a legacy single-axis view derived from
`archival_mode` (archive visibility) and `filters` (audience); prefer setting those directly. Because it is derived,
it does not always round-trip: writing it alongside an explicit `archival_mode` that disagrees will report the
value implied by the two underlying fields, and writing a value that already matches the derived one is a no-op.'
featured:
description: Designated whether or not this email should be highlighted within the archives.
title: Featured
type: boolean
filters:
$ref: '#/components/schemas/FilterGroup'
description: Tag-based filter rules determining which subscribers receive this email.
image:
description: A primary image URL used when previewing the email on the web or in other contexts.
title: Image
type: string
metadata:
additionalProperties: true
default: {}
description: A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be
nested — you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))
title: Metadata
type: object
modification_date:
description: The date and time at which the object was last modified.
format: date-time
title: Modification Date
type: string
publish_date:
anyOf:
- format: date-time
type: string
- type: 'null'
description: The date and time at which the email should be published in the future (for scheduled emails), or the
date and time at which the email was published (for sent emails).
title: Publish Date
related_email_ids:
description: A list of email IDs that are related to this email. Related emails are shown at the bottom of the email
and archive pages.
items:
type: string
title: Related Email Ids
type: array
secondary_id:
anyOf:
- type: integer
- type: 'null'
description: 'An informal ''number'' for the email, used in some templates (''This was issue #123'').'
title: Secondary Id
should_trigger_pay_per_email_billing:
description: Whether this email should trigger pay-per-email billing for paid subscribers. Use this to differentiate
between free updates and premium newsletters.
title: Should Trigger Pay Per Email Billing
type: boolean
slug:
anyOf:
- type: string
- type: 'null'
description: A short, human-readable identifier for the email, used in the archive URL.
example: welcome-to-the-newsletter
title: Slug
source:
$ref: '#/components/schemas/EmailSource'
description: The source of the email.
example: app
status:
$ref: '#/components/schemas/EmailStatus'
description: The current status of the email.
example: draft
subject:
description: The subject line for the email.
maxLength: 2000
title: Subject
type: string
suppression_reason:
anyOf:
- $ref: '#/components/schemas/EmailSuppressionReason'
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/buttondown/refs/heads/main/openapi/buttondown-comments-api-openapi.yml