Creating an email

When you create an email via the API, Buttondown automatically detects whether your content is plain text or formatted (HTML/Markdown) and handles it appropriately.

Plain text content is sent as-is, without any Markdown processing. This is ideal for simple, conversational emails.

Formatted content (HTML or Markdown) is processed and rendered. Buttondown detects formatted content by looking for:

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

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

<!-- buttondown-editor-mode: plaintext -->Your plain text content here...

or

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

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