Buttondown Release Notes

If you dropped a survey into a transactional email — your welcome email, say — and waited for the responses to roll in, you waited a while. The survey rendered fine in a regular email, but in a transactional one it quietly vanished: nothing in the preview, nothing in the sent email. (A reader hit exactly this and was kind enough to tell us about it.)

That's fixed. Surveys now render in your transactional emails and record responses just like they do everywhere else:

• Your welcome and confirmation emails, so you can ask new subscribers a question the moment they join — when they're most engaged.
• Gift, churn, and premium-confirmation emails, if you'd like to hear from subscribers at those moments too.

You add one the same way as in any email: in fancy mode, type /, search for your survey by its code or question, and Buttondown drops in the {{ survey.code }} tag for you. Responses are still recorded once per subscriber, so your results stay clean.

Nothing to turn on — this is live for every newsletter with surveys enabled.

Open up a team member and you'll find a new notes section waiting for you. It's the same notes you can already leave on a subscriber, a tag, or a survey — now pointed at the people you work with.

Use it for whatever context is worth keeping next to a name:

• What they handle — "runs the Friday digest," "owns paid subs," "here to proofread."
• Why they're here — who vouched for them, or when you brought them on.
• Anything future-you will want — the sort of thing you'd otherwise stash in a doc somewhere and lose track of.

Notes stay private to your team — your subscribers never see them — and they live right in the member's drawer, so there's no extra place to go check. If you've used notes anywhere else in Buttondown, this works exactly the same way.

It builds on team collaboration, and it's live now for every newsletter on a plan with teams. Nothing to turn on.

If you've ever gifted a subscription on someone's behalf, you'd expect the recipient to land on the portal and see, well, the gift — when it ends, who sent it, the note you wrote them. Unfortunately, they saw none of it. The portal treated gifted subscribers as if their gift didn't exist. Until today.

Now there's a dedicated gift section for them, with:

• When the gift ends, so they know whether they have a week left or a year.
• Who gifted them — pulled from the Stripe purchase when there is one, so the credit lands in the right place.
• The gift message itself, rendered with line breaks intact, whether it came from a Stripe checkout or a direct gift you sent from the dashboard.

The premium RSS link shows up there too, since gifted subscribers have premium access for the duration of the gift. And the section is independent of your paid-subscriptions status — turning paid subs off doesn't strand a recipient mid-gift.

Nothing to enable; this is live for every newsletter with gifting on.

Until today, the only way a subscriber could reach the portal was through the manage-subscription link at the bottom of an email. If they were already on your archive, they had no way in.

That link now lives in the archive nav too:

• Signed-in subscribers see an "Account" link that drops them into their per-newsletter portal — where they can edit their tags, update preferences, or unsubscribe.
• Everyone else sees a "Log in" link that points at the global portal sign-in page so they can pick up where they left off.

On mobile, it sits inside the existing menu alongside the other nav links. And it only shows up if you have the portal feature on — nothing changes if you don't.

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

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.