Buttondown Release Notes

Every subscriber in Buttondown carries a source — a little tag for where they came from, whether that's an embedded form on your site, a Stripe checkout, a Patreon import, a Zapier zap, or just you typing their email in by hand. We've shown that information on the subscriber page for ages, but until now it's been read-only.

Well, it's still read-only — but now it's a lot more useful. Starting today, source is a proper filter you can use in two places:

Audiences

When you're building a custom audience, you can now narrow on source the same way you'd narrow on tags or open rates. Want to send a thank-you to everyone who came in through your Stripe checkout last month? Filter on source contains stripe and go.

Automations

The same filter is available inside the new automations builder, so you can branch behavior based on how someone signed up. A welcome series can send one variant for organic signups and another for folks imported from Patreon, all from a single trigger.

A few practical examples newsletter authors have asked us about:

• Tag everyone who signed up via your embedded form so you can tell them apart from API-created subscribers down the line.
• Send a survey only to subscribers who came in organically (i.e. through your subscribe page), where the conversion intent is strongest.
• Skip the welcome email entirely for imported subscribers, since they've already heard from you somewhere else.

This is live for everyone, on every plan, with no setup on your end — your subscribers' sources have been recorded all along.

Our automations builder has been rebuilt from the ground up.

Before getting into the why of the work (and some of the design thinking behind it), here's the practical summary of what's changed for you:

• One trigger, many actions. A single automation can now fan out into any number of actions, each with its own timing, filters, and configuration. If you previously had four near-duplicate automations just to cross-post to four networks, those collapse into one.
• A dedicated settings page. Automations have graduated out of their cramped drawer into a full-page builder. Branching workflows, nested filters, and multi-step sequences have room to breathe — and are much easier to read at a glance.
• Redesigned analytics. You can now follow a trigger all the way through each filter, into each action, and down into per-action outcomes like open rates and link clicks. The same pattern powers the stats on individual emails, too.
• Previews against past events. Before you turn an automation on, you can see how it would have fired against the events already in your account — which subscribers it would have tagged, which emails it would have sent, how often the trigger actually hits. No more flipping the switch and hoping.
• Templates to start from. We've added welcome series and cross-posting templates to the docs so you don't need to build from a blank slate.

Want to skip ahead and click around? Here's the new builder, live: demo.buttondown.com/automations/new

This is a live demo. You can view this page on our live demo site, too.

If you were already getting by with the old one-to-one automations, nothing breaks — your existing automations keep working. The new shape just gives you a lot more room to grow into. With that out of the way, here's the longer story of how we got here.

One-to-one-to-one-to-many

During his time at Xerox PARC, Alan Kay coined the phrase "make simple things simple and complex things possible." He was building Smalltalk, a language that broke programs into structures that communicated like living organisms — intuitive enough for children, powerful enough to handle "50,000 kinds of things we hadn't thought of done by 50,000 programmers we hadn't met."

That phrase echoes in my head whenever I see the word "Automation" in software. Most tools pick a side: easy to set up but shallow, or deep and powerful but effectively an API. Buttondown had both — a simple automation builder for one-shot triggers, and a rich API surface for scripting complex workflows — but there was a huge gulf between the two, and our web app offered no bridges.

In the months since Justin asked me to wrestle with this problem, I've been shifting the pieces of our automations builder to click together more like Lego blocks than jigsaw pieces. Here's what we built and why.

One of the key constraints of Buttondown's previous automation builder was the shape of each automation: one event could cause one and only one action. To accomplish something like cross-posting an email to five social media networks, you'd need to create five separate automations. Not only does this take time and effort, but it's a pain to update later if you want to experiment with timing, wording, or tagging.

In hindsight, it's obvious that automations need to be one-to-many, not one-to-one. An event should be able to set off any number of actions, each with their own timing and unique configuration. For example: you should be able to cross-post to five networks from a single trigger, or send a welcome series that branches based on how a subscriber signed up. The shape of the automation should match the shape of the workflow; most workflows aren't straight lines.

Unfortunately, we had baked the one-to-one model deeply into our automations, from the data model, to the UI layout, to the way we tracked performance. Pulling the one-to-many thread unraveled those fundamental assumptions, cascading the work out across the codebase and interface. Filters that made sense gating a single action now needed to work across many. Timing that used to be set at the automation level had to drop down to every action. Our analytics components, which used to show a flow from trigger to action, needed to account for branching paths and parallel execution. It was like peeling an onion, but the onion was on fire.

A dedicated control surface

Given new superpowers and all the complexity that comes with them, one-to-many automations need a dedicated control surface. The previous interface was a stodgy drawer, which overflowed the instant we tested adding a second action to a simple automation. You can't stuff a branching, multi-action workflow into a settings drawer and expect anyone to build confidently inside it. So we built out an automations settings page to give you room to build and experiment.

By separating the building and testing of an automation from the understanding and auditing of one, we were able to push both interfaces even further than before. Now you can visualize all the actions an automation can take, and tune each in detail with custom timing and configurations.

This also gave us an opportunity to sand down the rough edges that are inevitable when you squeeze a complex feature into a small drawer. The flow of an event through filters to actions reads like a story. Buttons and selects nest neatly. Even when automations get complex, they're still easy to grok at a glance.

Drilling into the data

Before, tracking a simple automation's performance was a matter of checking how often it ran. In the old one-to-one world, it was easy to draw a line between triggers and actions. But with multiple cascading actions and stepped filters, the old audience and analytics tables got ugly fast.

Breaking the automation's configuration out into a dedicated view let us make the analytics panel even more powerful and intuitive. Now you can track the path of a trigger through each filter, through to each action, down into outcomes like email open rates and link clicks. This is one of my favorite things about software design: solving the hard case — nested, composable analytics — gave us a pattern that also simplified the easy ones, like stats on an individual email's page.

And like any good design process, building this analytics pattern showed us even more possibilities ahead. Justin put it succinctly: "maybe we should create the world's first vertical sankey diagram."

Time travel

One of the things that makes it hard to turn on an automation is just how wrong it can go. Not to scare you, but if you've spent enough time around automation, you've probably deleted a database or two.

In making complex automations more possible, we realized we'd need to give users a way to test them before turning them on. But how do you test something that hasn't happened yet? Simulating future events sounded fun but fragile. When it comes to automations (and, well, everything) the past has a lot more to say than the future.

So we designed automations previews to let you see how your automation would have performed if it had been running all along. By checking your automation against events that have already happened — subscribers you've gained, emails you've sent, tags you've added — we can give you a complete picture of how the automation works. Would the filters pass the right events? How often does the trigger actually fire? These questions are easy to answer when looking at your automation through the lens of the new preview feature.

Can we make complex things simple, too?

We've updated our documentation and landing pages with templates for welcome series and cross-posting automations to get you started. These updates lay the groundwork for you to build automations from the simplest to the most complex, all without needing to script against the API. Want to connect your Buttondown to your AI agent and power an email support system with rich data? Go for it. What about building an entire newsletter network with multiple membership entry points and subscriber-exclusive messaging, all with granular data reporting? You got it. A Turing machine that can compute any program using only email automations? I won't say I haven't considered it.

We want Buttondown to make the simple things simple and the complex things possible. And like Alan Kay's vision for Smalltalk, we want the complex things to be within reach of every user, regardless of technical background. Our work in rebuilding automations — moving from a strict one-to-one model into a one-to-many world of possibilities, and tackling the UI design that follows — takes us a few more steps in that direction. Happy building!

When your emails get "bounced" meaning that your subscriber's inbox politely says to try again later, due to low storage or rate limiting we've tracked and surfaced that for a while in the various email analytics views. Now, that data is surfaced on the subscribers page too: you can filter and view your subscribers by bounce_date and bounce_reason directly, both as filter options and as table columns.

"What's the difference between bouncing and undeliverability?", you ask. Oh, my sweet summer child.

Buttondown only marks a subscriber as undeliverable after we've seen enough deliverability problems to be confident the address is dead. A single bounce isn't enough sometimes inboxes are full, sometimes a server is misbehaving, and the subscriber's perfectly fine the next day. Tracking bounces separately means you can see those soft signals long before we make the call to stop sending.

A couple of ways this comes in handy:

• Catch trouble early. Filter for subscribers who bounced in the last week to see who's wobbling. If the same address keeps showing up there, you can decide to remove them yourself rather than waiting on us.
• Combine with engagement filters. Layer the bounce filter on top of open and click rate filters to find the subscribers who are technically reachable but not really engaging the kind of audit that's worth running once or twice a year.
• Resend or tag problematic cohorts. Want to resend yesterday's time-sensitive missive to folks who didn't get it? We won't do that for you for obvious reasons but you can, now more easily than ever!

Both filters live in the existing filter menu on the subscribers page, and you can flip them on as columns via the table customization menu. Reach out if anything's confusing.

What changes for you

A quick heads-up: we've moved three features behind the paywall, which means new accounts will need to be on a paid plan to use them. Those features are metadata, the ability to customize transactional emails, and integrations.

First, the most important thing. If you're reading this and feeling a little pang of "wait, did Buttondown just take away something I rely on?" — no, we didn't. If you find that's not the case for you, please email support and we'll get it sorted out.

Why we're doing this

Rather than walking through each of these three features one by one, I think it's more honest to talk about them as a group, because the reasoning is the same for all three. All of them are what I'd perhaps inelegantly describe as power user functionality. If you care about customizing the exact copy of your confirmation emails, or piping subscriber data into a Zapier workflow, or storing arbitrary metadata to segment your subscribers — you're someone who cares deeply about the experience of your newsletter, and you're probably trying to accomplish something non-trivial with it rather than just sending updates to friends and family.

That's genuinely great, and we want to keep building things for folks who care at that level. But these features come with a real cost on our end: not just the engineering labor to build them, but the ongoing upkeep in the form of infrastructure, support tickets, and documentation. If these specific features are valuable to you (and I agree — they are!), then hopefully Buttondown itself feels valuable enough to warrant being on a paid plan.

Feedback? Angst? Questions?

As always, if any of this is confusing or you think we've made a mistake in how we've drawn the line, just reach out.

Depending on your perspective, it's either very boring or very interesting to read about changes to how we do firewalling. Ideally, of course, you would need to know nothing about the firewall — we would simply always do the correct thing at all points in time, invisibly and imperceptibly.

But different people want different things, and especially where subscribers are concerned, we try to err on the side of transparency and customizability so any author can get the exact setup that works for them. With that context, I'd like to walk through a handful of new additions to bolster your newsletter against incoming spam.

Attack mode

Attack mode, which is enabled for all accounts by default, automatically and temporarily turns on our strongest set of firewall functionality if we detect a surge of spam traffic headed your way. We send you an email whenever this happens.

While you can disable attack mode, I highly encourage you to keep it on even if you want lower firewall settings: few things can cause more serious long-term damage to your deliverability than a spate of a couple hundred or thousand bad email addresses getting associated with your newsletter or domain.

Embedded fingerprinting

If enabled (it's disabled by default), this setting will heavily penalize any incoming subscribers who subscribe through one of your embedded forms but don't have a fingerprint. This is a bit convoluted, so it's best explained in the context of what it catches: a particular genre of attacker that loads your subscription form in an iframe and then mass signs up to it programmatically.

If all of these words are meaningless to you and you don't know what an iframe even is, you likely don't have to worry about this one.

Denied user agents

If you've set up a custom hosting domain, you can now supply a list of user agents to block — things like GPTBot or Facebook's crawler. We'll automatically turn this into a robots.txt file for you, as well as inject tags to (ideally) protect your content from unwanted traffic. It pairs nicely with our custom click tracking domains if you're already being thoughtful about how your newsletter shows up on the web.

As always, head to your firewall settings to configure any of this, and don't hesitate to reach out if you have questions.

Frequently asked questions

Why do I need a custom domain to use denied user agents?

Because robots.txt is domain-wide, you can't have a customized one unless you're on your own specialized domain.

This is a lot of stuff. What do I actually need to do?

In all honesty, very little. If you're reading this, you're likely one of the 99.7% of Buttondown customers who are not targeted by very annoying adversarial spammers. And if all of this stuff seems completely irrelevant to your life, then that is, trust me, a good thing.

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.