Buttondown logo

Publishing an email

Publishes and sends an email.

If you provide a publish_date, the email becomes scheduled to publish and send at that time. If you omit the publish_date, the email is set to publish immediately.

This endpoint accepts the same payload as updating an email, so any other fields you include are applied before the email is published.

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}/publish"
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("POST", 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.

attachments

Type
array
Description

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

Example
[ "att_01h8xg4j3k2m1n0p9q8r7s6t5v" ]

publish_date

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

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

archival_mode

Type
ArchivalMode
Description

Controls who can view this email in the archive.

email_type

Type
EmailType
Description

The type of email. Defaults to PUBLIC.

status

Type
EmailStatus
Description

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

suppression_reason

Type
EmailSuppressionReason
Description

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

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
Description

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

slug

Type
string
Description

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

Example
"hello-world"

secondary_id

Type
integer
Description

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

filters

Type
Description

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

template

Type
NewsletterEmailTemplate
Description

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

commenting_mode

Type
EmailCommentingMode
Description

Controls whether subscribers can comment on this email.

Type
array
Description

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

Example
[ "em_01h8xg4j3k2m1n0p9q8r7s6t5v" ]
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.