Buttondown logo

IntroductionStatusesSourcesAudiencesAnalyticsTemplatesCommenting modesSuppression reason

Audience filters

IntroductionFilteringOperators

Routes

Creating an emailListing emailsRetrieving emailUpdating an emailDeleting an emailRetrieving email analyticsSending a draft emailListing email eventsRetrieving email historyRetrieving an email's historical body

Buttondown logo

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 = {
  "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"
}

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.

{
    "absolute_url": "http://127.0.0.1:8000/sheinhardt/archive/welcome-to-the-newsletter/",
    "analytics": null,
    "attachments": [],
    "body": "I hope you really enjoy it!",
    "canonical_url": "",
    "commenting_mode": "enabled",
    "creation_date": "2000-01-01T00:00:00+00:00",
    "description": "",
    "email_type": "public",
    "featured": false,
    "filters": {
        "filters": [],
        "groups": [],
        "predicate": "and"
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "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.

attachments

Type
array
Description

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

publish_date

Type

subject

Type
string
Description

The subject line for the email.

Example
"The subject line for the email"

description

Type
string
Description

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

canonical_url

Type
string
Description

The URL of the original source of the content.

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

body

Type
string
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 -->.

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

email_type

Type
EmailType
Description

The type of email to create. Defaults to PUBLIC.

status

Type
EmailStatus

suppression_reason

Type
EmailSuppressionReason

metadata

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

image

Type
string

slug

Type
string
Example
"hello-world"

secondary_id

Type
integer

filters

Type
FilterGroup

template

Type
NewsletterEmailTemplate

commenting_mode

Type
EmailCommentingMode
Type
array
Type
boolean
Description

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

should_trigger_pay_per_email_billing

Type
boolean
Description

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