Buttondown logo

Creating an email

Body format detection

When you create an email via the API, Buttondown automatically detects whether your content is Markdown or rich HTML and handles it appropriately.

Markdown mode (plaintext) is the default. Your content is treated as Markdown and rendered to HTML. This is ideal for most use cases — write in Markdown and Buttondown handles the formatting.

Fancy mode (fancy) treats your content as rich HTML, like the WYSIWYG editor in the web app.

Buttondown auto-detects the mode by looking for:

  • HTML tags (e.g., <div>, <p>, </h1>)
  • Markdown syntax (e.g., # headings, **bold**, [links](url), lists)

If none of these are found, the content is treated as Markdown mode (no rendering is applied since there's no markup to process).

If you want to explicitly control the format, prepend your body with an editor mode comment:

<!-- buttondown-editor-mode: plaintext -->Your **Markdown** content here...

or

<!-- buttondown-editor-mode: fancy --><p>Your <em>HTML</em> content here...</p>

Frontmatter detection

If your email body starts with a YAML frontmatter block (a line of --- followed by key-value pairs), the API will reject it with a 400 error and the code body_contains_frontmatter. This is because frontmatter is almost always a sign of a bug in your integration rather than intentional email content.

If you need to send an email whose body genuinely starts with ---, you can bypass this restriction with the X-Buttondown-Live-Dangerously header:

curl -X POST "https://api.buttondown.com/v1/emails" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "X-Buttondown-Live-Dangerously: true" \
  -H "Content-Type: application/json" \
  -d '{"subject": "My email", "body": "---\ncustom: content\n---\nBody"}'

Sample requests

These sample requests are autogenerated by the OpenAPI spec.

import requests

url = "https://api.buttondown.com/v1/emails"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "subject": "The subject line for the email",
  "body": "This is an example of the body of an email."
}

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,
    "attachments": [],
    "body": "I hope you really enjoy it!",
    "canonical_url": "",
    "commenting_mode": "enabled",
    "review_mode": "disabled",
    "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

publish_date

Type
string

subject

Type
string · required
Example
"The subject line for the email"

slug

Type
string

description

Type
string

canonical_url

Type
string

image

Type
string

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 to create. Defaults to PUBLIC.

status

Type
EmailStatus

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

secondary_id

Type
integer

filters

Type
FilterGroup

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.