Safer defaults for the email creation API

Buttondown's REST API has always tried to adhere to good RESTful conventions. A POST to /v1/emails creates a new email, and if you don't specify a status, we've historically assumed you want to send it — so the default has been about_to_send. Makes sense in theory, but in practice it catches people off guard. Nobody expects a quick test request to fire off an email to their entire subscriber base.

We've cut a new API version — 2026-04-01 — to make this a little safer. The endpoint behaves identically, with two exceptions:

1. The default status is now draft. If you POST to /v1/emails without specifying a status, your email is created as a draft instead of immediately queuing to send. No surprises.

2. Sending requires a one-time confirmation. If you explicitly set status to about_to_send, Buttondown returns a 400 with a sending_requires_confirmation error code — just to make sure that's really what you meant. To confirm, pass the X-Buttondown-Live-Dangerously: true header.

You only need to supply the header once per API key. After the first successful send, all subsequent POST requests with about_to_send will go through without it. Think of it as a "yes, I know what I'm doing" handshake.

# First time: include the header
curl -X POST https://api.buttondown.com/v1/emails \
  -H "Authorization: Token your-api-key" \
  -H "X-API-Version: 2026-04-01" \
  -H "X-Buttondown-Live-Dangerously: true" \
  -d '{"subject": "Hello!", "body": "...", "status": "about_to_send"}'

# After that: no header needed
curl -X POST https://api.buttondown.com/v1/emails \
  -H "Authorization: Token your-api-key" \
  -H "X-API-Version: 2026-04-01" \
  -d '{"subject": "Hello again!", "body": "...", "status": "about_to_send"}'

A few things to note:

• PATCH requests are unaffected. Updating an existing email's status to about_to_send works the same as before, no header required.
• Older API versions are unchanged. If you're on 2026-01-01 or earlier, everything works exactly as it always has.
• The confirmation is per API key, not per newsletter. If you have multiple API keys, each one needs to confirm independently.

If you're not sure which API version you're on, check your API keys page — it shows the version for each key.