Buttondown Release Notes

You can now gate content in your archives behind a subscription — without needing paid subscriptions or Stripe set up.

In Fancy mode, type /subscription wall to insert one into your email. Everything below it will be visible only to subscribers when someone views the post in your archives. Anyone who's subscribed — free, paid, gifted — can see the full post. Everyone else gets a teaser and a prompt to subscribe.

You can also set an email's archival mode to "Shown to subscribers" in the finalization drawer to gate the entire post without placing a wall in the body.

A few things worth noting:

• One wall per email. You can have either a paywall or a subscription wall, not both.
• Archives only. The full email is always delivered to subscribers' inboxes — the wall only affects the web archive view.
• RSS feeds exclude subscriber-gated emails for now, since there's no way to authenticate feed readers.

One of our most common support questions has always been some variation of: "What's the difference between my newsletter email address and my account email address?" And honestly? There wasn't a great answer, because it was a product decision from the very early days of Buttondown that never really made sense.

With our revamped sending and reply handling, the picture is a lot simpler now. All outgoing emails come from one of two places:

• Your username at buttondown.email (the default)
• The email address you've configured in your custom sending domain settings, if you have one set up

There's no separate "newsletter email address" to worry about anymore.

So we've moved the email address field entirely to your sending domain settings, and hidden it for folks who aren't sending from a custom domain. If you don't have a custom domain, you don't need to think about it. If you do, it's right where you'd expect it to be.

Hopefully this makes everyone's lives slightly easier. If you have any questions, don't hesitate to reach out or check out the docs.

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.