Updating an email

Sample requests

These sample requests are autogenerated by the OpenAPI spec. This endpoint requires one or more parameters in the URL: those are offset in curly-braces.

import requests

url = "https://api.buttondown.com/v1/emails/{id}"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "attachments": [
    "att_01h8xg4j3k2m1n0p9q8r7s6t5v"
  ],
  "subject": "The subject line for the email",
  "canonical_url": "https://sheinhardtwig.com/2025/01/17/our-nbc-partnership",
  "body": "This is an example of the body of an email.",
  "slug": "hello-world",
  "related_email_ids": [
    "em_01h8xg4j3k2m1n0p9q8r7s6t5v"
  ]
}

response = requests.request("PATCH", url, headers=headers, json=data)
print(response.text)

Sample responses

The IDs and values referenced in these responses are fake; please only rely on these responses for overall structure.

{
    "id": "em_29fxqcmrkp969vzttksexvmvr8",
    "creation_date": "2000-01-01T00:00:00+00:00",
    "absolute_url": "http://127.0.0.1:8000/sheinhardt/archive/welcome-to-the-newsletter/",
    "analytics": null,
    "callouts": [],
    "attachments": [],
    "body": "I hope you really enjoy it!",
    "canonical_url": "",
    "commenting_mode": "enabled",
    "description": "",
    "archival_mode": "enabled",
    "email_type": "public",
    "featured": false,
    "filters": {
        "filters": [],
        "groups": [],
        "predicate": "and"
    },
    "image": "",
    "metadata": {},
    "modification_date": "2000-01-01T00:00:00+00:00",
    "publish_date": "2000-01-01T00:00:00+00:00",
    "related_email_ids": [],
    "secondary_id": null,
    "should_trigger_pay_per_email_billing": false,
    "slug": "welcome-to-the-newsletter",
    "source": "app",
    "status": "sent",
    "subject": "Welcome to the newsletter",
    "suppression_reason": null,
    "template": null
}

Body parameters

All parameters are optional unless explicitly specified.

attachmentsarray

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

example

[
  "att_01h8xg4j3k2m1n0p9q8r7s6t5v"
]

publish_datestring

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). Pass "none" to clear a scheduled date.

subjectstring

The subject line for the email.

example

"The subject line for the email"

descriptionstring

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

canonical_urlstring

The URL of the original source of the content.

example

"https://sheinhardtwig.com/2025/01/17/our-nbc-partnership"

bodystring

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 .

example

"This is an example of the body of an email."

archival_modestring · enum

Controls who can view this email in the archive.

values

archive_only
This email is visible in the archive to everyone, but is not email content (e.g. an imported blog post) and is never sent or shown in email-rendering contexts.
disabled
This email is not visible in the archive.
enabled
This email is visible in the archive to everyone.
enabled_for_paid_subscribers
This email is visible in the archive to paid subscribers only.
enabled_for_subscribers
This email is visible in the archive to subscribers only.

email_typestring · enum

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.

values

public
Public emails are sent out to all of your subscribers and are available in your web archives.
private
Private emails are sent out to all of your subscribers but are not viewable in your web archives.
premium
Premium emails are sent out to only paying subscribers (including those with gift subscriptions or on a free trial), and only premium subscribers can view them in online archives.
free
Free emails are sent out only to subscribers who are not paying for your newsletter (so you can send specific emails to convince them to pay, for instance!)
churned
Emails sent specifically to subscribers who were previously premium but have since churned.
archival
Emails that are only available in the archive and not sent to subscribers.

statusstring · enum

The status of the email (e.g. draft, about_to_send, sent, scheduled).

values

draft
Draft emails are only visible to you and are not sent out to subscribers.
managed_by_rss
This email was created by an external feed, and has not yet been finalized and sent out by Buttondown.
about_to_send
This email has been queued to send out to subscribers, and will be sent automatically within a few minutes.

If you're seeing that an email you just sent out is 'stuck' here, worry not — Buttondown sometimes takes a little bit longer to send out emails to ensure deliverability, but once it's marked as 'about to send' it will get sent out.
scheduled
This email has been scheduled to send out to subscribers at a specific time. This specific time is available on the email as its publish_date.
in_flight
This email is currently being sent out to subscribers, and is visible in your web archives if enabled.

Some emails, especially those with large subscriber lists, may take a while to send out — Buttondown sends emails out in batches to ensure deliverability, so if you're seeing an email 'stuck' here, it's because our systems have detected that that's the optimal way to reach your subscribers.
paused
This email has been paused, and is not visible in your web archives. If it is not resumed within seven days, it becomes a draft, sent, or partially sent email.
deleted
This email has been deleted, and is no longer visible in your web archives.
errored
This email has encountered an error while sending out to subscribers, and is not visible in your web archives.
sent
This email has been sent out to subscribers, and is visible in your web archives if enabled.
partially_sent
This email was paused while sending and was not resumed within seven days, so only some subscribers received it. It is not visible in your web archives.
imported
This email was imported from another service, and is visible in your web archives if enabled.
throttled
This email is in the process of being sent out, but is being intentionally sent slowly to ensure deliverability.
resending
This email is in the process of automatically being resent to subscribers by Buttondown's systems in order to make sure all subscribers have received it.
transactional
This email is a transactional email used by a core workflow in your newsletter or Automations, and is not visible in your web archives nor sent out to subscribers.
suppressed
This email has been suppressed and is not visible to subscribers.

suppression_reasonstring · enum

If the email has been suppressed from sending, the reason why.

values

law_enforcement
Used for communications with law enforcement agencies regarding legal inquiries or data requests.
internal_auditing
Used for internal auditing and compliance-related communications.

metadataobject

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

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

example

"hello-world"

secondary_idinteger

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

filters

Tag-based filter rules determining which subscribers receive this email.

templatestring · enum

If present, this template overrides your newsletter's default email template. Pass "none" to clear an override.

values

classic
A plaintext template that puts emphasis on your content.
custom
Your own HTML template, wrapped around every email's content.
modern
The default email template.
plaintext
A plaintext (like, literally plaintext, no HTML at all) template for the truly minimalist.
naked
The email body itself is used as the template, with no outside scaffolding provided by Buttondown.

commenting_modestring · enum

Controls whether subscribers can comment on this email.

values

disabled
Commenting is disabled for this email.
enabled
Commenting is enabled for this email.
enabled_for_paid_subscribers
Commenting is enabled for paid subscribers only.

related_email_idsarray

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

example

[
  "em_01h8xg4j3k2m1n0p9q8r7s6t5v"
]

featuredboolean

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

should_trigger_pay_per_email_billingboolean

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

Core concepts

Common workflows

Accounts

API Requests

Attachments

Automations

Bulk actions

Comments

Coupons

Emails

Events

Exports

Images

Imports

Newsletters

Notes

Ping

Prices

RSS feeds

Segments

Snippets

Sponsorships

Subscribers

Surveys

Tags

Webhooks

Sample requests

Sample responses

Body parameters

attachmentsarray

publish_datestring

subjectstring

descriptionstring

canonical_urlstring

bodystring

archival_modestring · enum

email_typestring · enum

statusstring · enum

suppression_reasonstring · enum

metadataobject

imagestring

slugstring

secondary_idinteger

filters

templatestring · enum

commenting_modestring · enum

related_email_idsarray

featuredboolean

should_trigger_pay_per_email_billingboolean