v4

latestOpenAPI 3.1.0MIT2026-08-02128224900.7 KB

Emails

Update Email

Update an email's properties

patch/emails/{id}

Path parameters

idstring required

Request body

attachmentsstring[] nullable

A list of attachment IDs present on the email. (See Attachments for more information.)

subjectstring nullable

The subject line for the email.

descriptionstring nullable

A human-readable description of the email, used for archives and SEO.

canonical_urlstring nullable

The URL of the original source of the content.

bodystring nullable

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:  or .

archival_mode'disabled' | 'enabled' | 'enabled_for_paid_subscribers' | 'enabled_for_subscribers'

Governs who can view this email in the archive.

Represents the audience of an email, and to whom it is visible both in the initial email and in online archives.

Represents the state of an email.

No action is required to move from one state or another; Buttondown internally handles the transitions, and exposing the status is for observability purposes only.

suppression_reason'law_enforcement' | 'internal_auditing'

Represents the reason an email was suppressed.

metadataobject nullable

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.)

imagestring

A primary image URL used when previewing the email on the web or in other contexts.

slugstring nullable

A short, human-readable identifier for the email, used in the archive URL.

secondary_idinteger nullable

An informal 'number' for the email, used in some templates (e.g. 'This was issue #123').

commenting_mode'disabled' | 'enabled' | 'enabled_for_paid_subscribers'

Governs who can comment on this email.

This enum replaces the is_comments_disabled field, which has been deprecated. (Also note that this field may be superseded by newsletter-level settings; for instance, "enabled" is an invalid and inert value if the newsletter itself has comments disabled.)

related_email_idsstring[] nullable

IDs of emails related to this one. Shown at the bottom of the email and archive pages.

featuredboolean nullable

Designated whether or not this email should be highlighted within the archives.

should_trigger_pay_per_email_billingboolean nullable

Whether this email should trigger pay-per-email billing for paid subscribers. Use this to differentiate between free updates and premium newsletters.

Response

idstring required

A unique TypeID associated with the object.

creation_datestring date-time required

The date and time at which the object was first created.

absolute_urlstring required

The canonical web URL of the email on the newsletter's archive.

calloutsCallout[]

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).

attachmentsstring[] nullable

A list of attachment IDs present on the email. (See Attachments for more information.)

bodystring required

canonical_urlstring required

The URL of the original source of the content.

commenting_mode'disabled' | 'enabled' | 'enabled_for_paid_subscribers' required

Governs who can comment on this email.

descriptionstring required

A human-readable description of the email, used for archives and SEO.

archival_mode'disabled' | 'enabled' | 'enabled_for_paid_subscribers' | 'enabled_for_subscribers' required

Governs who can view this email in the archive.

Represents the audience of an email, and to whom it is visible both in the initial email and in online archives.

featuredboolean required

Designated whether or not this email should be highlighted within the archives.

imagestring required

A primary image URL used when previewing the email on the web or in other contexts.

metadataobject

modification_datestring date-time required

The date and time at which the object was last modified.

publish_datestring date-time nullable

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).

related_email_idsstring[] required

A list of email IDs that are related to this email. Related emails are shown at the bottom of the email and archive pages.

secondary_idinteger nullable

An informal 'number' for the email, used in some templates ('This was issue #123').

should_trigger_pay_per_email_billingboolean required

Whether this email should trigger pay-per-email billing for paid subscribers. Use this to differentiate between free updates and premium newsletters.

slugstring nullable

A short, human-readable identifier for the email, used in the archive URL.

source'api' | 'import' | 'app' | 'external_feed' | 'smtp' required

Represents the original provenance of an email. This value is not exposed to subscribers, but does determine some behavior of the email (e.g. whether or not analytics can be calculated.)

Represents the state of an email.

No action is required to move from one state or another; Buttondown internally handles the transitions, and exposing the status is for observability purposes only.

subjectstring required

The subject line for the email.

suppression_reason'law_enforcement' | 'internal_auditing'

Represents the reason an email was suppressed.

template'classic' | 'custom' | 'modern' | 'plaintext' | 'naked'

Represents the template of an email.

Each template has a different layout/style; you can view screenshots and examples in the docs.