Creating an email

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>

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"}'