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:

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

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