Buttondown Release Notes

If you write about books in your newsletter, this one's for you: Buttondown now supports Bookshop.org embeds.

Paste a Bookshop.org link into your email on its own line and Buttondown will automatically render it as a rich embed with the book's cover art, title, and author. No configuration, no shortcodes — just drop in the URL.

On the web (like in your archives), we use Bookshop's official widget so readers can browse and buy right from your page. In email (because, well, email sometimes sucks), we pull metadata from the Open Library API to render a clean card with the cover image and details.

Bookshop.org supports independent bookstores with every purchase, so your readers get a nice reading experience and local bookshops get a little love too.

To get started, just paste a Bookshop.org URL next time you're drafting an email. (Looking for something to test with? Try out Lessons in Magic and Disaster).

When we shipped passkey support last week, passkeys worked as a second factor — you'd still type your password first, then verify with your fingerprint or security key. That's great for security, but it's an extra step.

Now you can skip the password entirely. If you have a passkey registered on your account, you'll see a "Log in with a passkey" button right on the login page. Tap it, verify with your device, and you're in.

If you've already registered a passkey in Settings → Sign in & security, it just works — no need to set up anything new.

Rename metadata

If you've ever realized that half your subscribers have a name key and the other half have first_name, you know the pain of inconsistent metadata. Up until now, fixing that meant exporting, editing, and re-importing — or writing a script against the API, neither of which are exactly ergonomic options.

Now you can rename metadata keys in bulk, right from the subscribers page.

Select the subscribers you want to update (or all of them), open the Rename metadata menu, and you're opff to the races. Enter the old key and the new key — you can add multiple rename mappings at once if you've got a few to clean up — and hit Rename Metadata. Done.

(This works through the bulk actions API too, using the rename_metadata action type. Pass a rename_mapping object with your old-to-new key pairs, and Buttondown handles the rest.)

Passkeys

If you've set up two-factor authentication on your account, you now have another option for verifying your sign-in: passkeys. Instead of typing in a code from an authenticator app, you can use your device's fingerprint sensor, face recognition, or a hardware security key.

Head to Settings → Sign in & security and click "Add another way to sign in or verify." You'll see a new Passkey option alongside the existing authenticator app setup. Give it a name (like "MacBook Touch ID" or "YubiKey"), and your browser will walk you through the rest.

Once registered, your passkeys show up right next to your authenticator devices on the security page. You can rename or delete them anytime. At sign-in, after entering your password, you'll be prompted to verify with your passkey.

A few things worth noting:

• You can register up to 10 passkeys, so you can cover multiple devices and keep a backup key in a drawer somewhere.

• Passkeys work alongside authenticator apps. If you have both set up, you can choose which method to use at login.

• Recovery codes still work as a fallback. If you lose access to both your authenticator app and your passkeys, recovery codes will get you back in.

Buttondown's REST API changes

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:

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

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

Recovery codes

If you've set up two-factor authentication on your account, you can now generate recovery codes as a backup way to sign in. These are handy if you ever lose access to your authenticator app — no need to email support to get back in.

Head to Settings → Sign in & security and you'll see a new "Recovery options" section underneath your authenticator devices. Click Generate to create a set of ten one-time codes. Each code can only be used once, and you can see how many you have left at any time.

If you run low or think your codes have been compromised, you can regenerate a fresh set — this replaces all existing codes, so any old ones stop working immediately.

Store your codes somewhere safe, like a password manager.

New: Sort and filter subscribers by open and click rate

We recently added the ability to sort and filter subscribers by open and click rate. Now we've brought that same functionality over to the other side of the house: you can filter your sent emails by open rate, click rate, and delivery rate.

Instead of scanning through a long list of past sends, you can jump straight to the ones that performed the way you're looking for. Each filter lets you set a minimum and maximum range, or pick from preset buckets (0–25%, 25–50%, 50–75%, 75–100%). Want to pull up every email that cracked a 50% open rate? Two clicks. Want to find the ones where barely anyone clicked through? Same deal.

A few ways this helps:

• Find what's working: Filter by high open rate to see which subject lines and topics resonated most. Great for figuring out what to write more of.
• Spot deliverability issues: Filter by low delivery rate to catch emails that may have bounced more than expected — a useful early warning sign if something's off with your list hygiene.
• Combine with other filters: Stack rate filters with audience, source, or date range filters to get really specific. For example, find all emails sent to a particular tag in the last quarter with an open rate above 40%.

If you want to dig deeper into how Buttondown tracks these metrics, check out our analytics documentation.

Newsletter metadata in your emails

You've been able to use subscriber metadata in your emails for a while now — things like {{ subscriber.metadata.first_name }} to personalize greetings, or {{ subscriber.metadata.company }} to tailor content per reader. That's great for per-subscriber personalization, but what about values that are the same across your entire newsletter?

Now you can use {{ newsletter.metadata }} in your email templates. It works exactly the same way: set key-value pairs on your newsletter, then reference them in any email, automation, or template.

How it works

Head to the API and set metadata on your newsletter:

PATCH /v1/newsletters
{
  "metadata": {
    "podcast_url": "https://pod.example.com",
    "current_sponsor": "Acme Corp",
    "issue_season": "Spring 2026"
  }
}

Then use those values anywhere you write email content:

This issue is brought to you by {{ newsletter.metadata.current_sponsor }}.

Listen to our latest episode: {{ newsletter.metadata.podcast_url }}

A few ideas

• Sponsorship info: Store your current sponsor's name and URL in newsletter metadata, then reference it in your footer template. When the sponsor changes, update the metadata once instead of editing every template.
• Seasonal or rotating content: Keep a current_theme or issue_season value that you swap out periodically, and reference it in your subject lines or headers.
• Global links: Store URLs that appear across many emails — your podcast, your community forum, your latest lead magnet — so you can update them in one place.

The key difference from subscriber metadata is scope: subscriber metadata varies per reader, newsletter metadata is the same for everyone. Think of it as global variables for your newsletter.

Open and click rate filtering on Subscribers

You were already able to see open and click rates for individual subscribers, but finding patterns across your entire list meant a lot of scrolling and squinting. Now you can sort and filter your subscribers page by email open rate and link click rate, making it easy to zero in on the subscribers you're looking for.

Want to find your most engaged readers? Sort by open rate, descending. Curious who's clicking through to your links? Sort by click rate. You can also filter by range: say, everyone with an open rate above 50%, or subscribers who haven't clicked a single link.

You can now also use this metrics to filter the audience you're sending an email to. Just select "Custom..." in the "Publish this email" drawer to add open/click rate filters.

A few ways this comes in handy:

• Sort by click rate to find the readers who are actually acting on your content. Great candidates for a survey, a referral ask, or early access to something new
• See at a glance whether your list skews highly engaged or if there's a long tail of subscribers who signed up and disappeared

These rates are also now available in the Subscribers API, so you can sort and filter programmatically too -- handy if you're building automations or syncing subscriber data with other tools.

If you have click tracking enabled, your links get rewritten to point through a tracking proxy — something like track.buttondown.email — so we can record when a subscriber clicks. (You can read more about how all of this works in our post on insourcing analytics.)

We've now added the ability to use your own custom sending domain as the click tracking proxy instead of our shared one. In our testing, this improves both deliverability and the general trustworthiness of links in your emails: subscribers see your domain in the link, not ours.

If you're using our managed domain setup, this is already rolling out for you automatically. If you're using a manual DNS configuration, head to your sending domain settings to add the additional CNAME record.

Frequently asked questions

What if I don't want this on my custom sending domain?

This behavior is required for all new sending domains. Routing click tracking through your own domain isolates your reputation from our shared click tracking infrastructure, which is a net positive for everyone — so we're enforcing it across the board.