Buttondown Updates & Release Notes

Add chevrons, polka dots, graph paper, and more to the background of your website.

If you're a web developer of a certain age, the URL subtlepatterns.com might hold a special place in your heart. It certainly does in mine.

Getting to mess around with its hundreds of chevrons and spirals and halfway open doors to fun but ultimately disastrous aesthetic choices wasn't just a way for my younger self to explore and mature a sense of design. It taught me a lot about the web and graphics in its own meager way. It's how I learned about tiling and SVG backgrounds and a whole host of other things aside.

It also showed me the value of texture in a literal sense. Aesthetic preferences are cyclical, but being able to pepper in a few skeuomorphic affordances here and there forced me to think hard about what the intent of some of my designs were, what elements I wanted to spotlight versus what ones I wanted to recede, and so on.

Mostly though, they were and are just fun and neat, which is the overriding reason why we have brought them, or at least a very small subset, to Buttondown. You can now add patterns to the background of your website. Go ahead, give it a spin:

You'll find it under Background in your Web settings if you're using the Modern theme. Pick one of eight patterns, then a background color and a pattern color. If you've turned on dark mode, you can set separate colors for it too.

Extra big thanks to Jim Raptis of Magic Pattern for inspiring many of these!

Enjoy yourself responsibly.

It's now easier to create and edit surveys and snippets right from the email editor.

We've made it easier to work with surveys and snippets without interrupting your writing flow.

To create a new survey in the fancy editor, just type "/new survey". That places an interactive block in your email where you can set the question and answers. You can still dig into our more advanced survey options by clicking the settings button.

You can also add your existing surveys to an email. Type "/survey" on a new line to go to the surveys section of the command menu. From there you can select one of your existing surveys. You can also search for a specific survey with the command menu, like "/my awesome survey about dogs".

If you're fond of our code-based survey syntax: it still works! Feel free to keep including surveys like {{ survey.tabs_versus_spaces }} — no changes to your workflow necessary.

We've also made it possible to create and edit shared snippets from the fancy editor. Type "/new snippet" to create one, or edit an existing snippet right in its block.

Easily link to your past emails from the editor

We've made it easier to link to your existing emails from the fancy editor.

Now when you add a link via the formatting bar (or with the new /link and ⌘K shortcuts), you can select and search from your newsletter's past emails.

Behind the scenes, these get inserted as special buttondown-email links, which keep working even if you change your newsletter domain or email slug.

While we were at it, we also made it simple to find and link to variables, such as your newsletter's manage subscription page (manage_subscription_url).

We hope this makes your drafting process even easier. And thanks, Mark, for the suggestion!

Skip the sidebar, hear what changed, and navigate tables with arrow keys.

We've written before about making your newsletter accessible to your readers. This time, we turned that lens on ourselves: the app you use to write, send, and manage your newsletter.

Here’s what we fixed.

Screen readers

• A "Skip to content" link comes first when you press Tab, so you can skip the sidebar.
• You can jump between the sidebar and main content using landmarks. The sidebar marks your current section, including on pages within it, like a subscriber's page.
• Screen readers announce page titles when you navigate and "Changes saved" when you save settings.
• Tables, inputs, and about 25 icon-only buttons now have accessible names. Buttons previously read out as just "button" now say what they do.

Keyboard navigation

You no longer need to Tab through every row in a table. Tab enters the table, ↑ and ↓ move between rows, and Home and End jump to the first or last row. Tab still moves between controls within a row.

File rows, sponsorship slots, sortable analytics columns, import checklist steps, and collapsible sections now work with a keyboard. File rows also support middle-click and "open in new tab". Chart bars and slices are only buttons when they have an action.

We've also added code checks to catch clickable elements that lack keyboard support.

What's next

Still on our list:

• Making text easier to read in light and dark mode, starting with muted text, badges, and buttons.
• Making sure every control shows a clear focus outline when you reach it with a keyboard.
• Support for Windows' high-contrast mode.
• Checking against WCAG 2.2, which our first pass didn't cover.

If anything in Buttondown gets in your way, whether you use a screen reader, a keyboard, a magnifier, or anything else, let us know. We'd love to hear about it.

The archive redirect has graduated from a hidden setting into a Redirect add-on in your Web settings.

Behind the scenes, we've been on a bit of a whack-a-mole mission over the past few months to unship or make public as many of our "hidden" settings as possible.

Some of these hidden settings turned out to be used by only a handful of active users (or, in some cases, literally zero), and we've generally opted to just remove these and contact the affected few folks. In other cases, though, we've gone in the other direction and graduated the hidden setting into something publicly accessible.

Here's a feature that doesn't get talked about much, because it only gets used when (and if) you sadly decide to leave Buttondown: our ability to redirect your archives to a custom domain of your choice. Note that this is not hosting on a custom domain. We're merely redirecting any inbound requests we receive to a new destination.

You'll find it as the Redirect add-on in your Web settings. Turn it on, paste in your new URL, and save; visitors to your subscribe page and archive will land there instead. (Individual emails stay put.)

This feels like a weird feature to support, and yet it seems like an honorable one. For one thing, we're always grateful when other services offer this. And for another, perhaps more important reason, it's a good demonstration of our commitment to helping you, even at some oblique cost to ourselves, by making it as easy as possible for you to leave Buttondown.

We hope to justify your desire to stay, not by locking you in, but by making your decision as easy as possible one way or another.

On rare occasions, we get to be simultaneously selfish and selfless. For instance, the single most common reason why someone stops using Buttondown is writer's block.

Everything we know about building a successful newsletter (we even wrote a book about it) is downstream of the discipline and patience to keep writing week after week after week. And for lots of folks, the thing that stops them is not an issue of time or energy, but a blank screen staring expectantly at them.

We, of course, cannot solve writer's block. But if there is something we can do to make it easier for even one author to put digital pen to digital paper and send something on a week where they otherwise felt like they had nothing to write about, it's a pretty good use of our time and energy. And as such, we've added a cute little list of writing prompts that you can toggle on when you're otherwise looking at a completely empty screen. You'll find it in the editor's actions menu under Preferences, right next to scroll sync. Take a look below:

Settings pages mirror product debt, and as such tend to accrete in painful ways. Every new feature wants a toggle, every toggle wants a home, and every so often you look up and realize that you've organized things in a sensible way that has led you to madness. Here are two small ways we're cleaning things up.

The Tracking page is gone

That page was a grab bag: some of its toggles changed your emails, and one changed your archive. Nobody went looking for them there (we have the support emails to prove it).

So each toggle now lives next to the thing it actually changes:

• Email settings has a new Tracking section for click tracking and open tracking, plus a UTM information add-on that tags your outgoing links with UTM parameters.
• Archive settings has a Web analytics add-on that tracks visits to your archive pages.

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

The Design folder is gone, too

The sidebar had a Design folder holding exactly two pages: Email and Archives (or Web, depending on who you ask). That was a leftover from when we split up the old design settings back in January, and it meant one more click to reach two of the most important settings pages.

Email and Archives now sit directly under Settings, alongside everything else.

The analytics that we sent over email used to be sloppy & weird. As a result, we redesigned them. This is only the first iteration. Please give us feedback on them.

That’s the summary. Here is the long answer!

The analytics that we sent over email used to be sloppy & weird

Right now, Buttondown's authors get data in a few places:

• In a dedicated analytics section on the app
• In an individual email view, after the email has been sent
• Over email, in the form of weekly & monthly digests

In the long run, we'd like our analytics to look & perform better in all of these places. We decided to start with overhauling our emails, since that allows us to start small & figure out a few first principles most easily.

We decided to begin with a small research project to figure out what you need and how we currently fall short. I talked to 10 Buttondown authors over the course of a month to figure it out. As a customer myself, I also have opinions – but mine are specific to my own needs, and Buttondown has a lot of varying use cases.

I learned a lot! For example:

• Some people send emails daily, others monthly, others sporadically.
• Some people check their analytics exclusively through our email digests, others on our website.
• Some people have automations turned on.
• Or paid subscriptions.
• Or they get lots of comments with everything they send.
• Some people have lists of <100 readers. Others are >100,000.
• Lists will go dormant for periods of time: vacation, hiatus, etc.

Analytics need to address all of these cases, in any permutation you can think of. We ended up building out a corpus of relevant scenarios and edge cases, a (very heavily truncated and simplified) version of which you can see below:

As a result, we redesigned them

From our interviews, we learned what matters to people:

• Larger lists care a lot about growth & engagement.
• Smaller lists care a lot about how a given email did.
• Everybody wants to know how emails did relative to their norm. Did this one do numbers? Great, let’s write more of that.

And so I tried to follow the Tuftean principle of clarifying by adding detail. We offer a bunch of side quest-y additions to analytics based on what features you have turned on, which will hopefully not overwhelm you with data or bore you with blank states. We try to put our numbers in context, showing you how your growth is doing or how your email fared relative to the baseline of your list.

We’re also trying to send you as a few emails as possible, because everybody gets too many emails. We want you to actually get value from what we’re showing you, and we want to be careful about when we’re showing it.

This is only the first iteration

Next, I’m going to work on a more general design system for all of our analytics across both web & email. Expect a few improvements & adaptations as we incorporate that system into our existing work.

In the long run, we’re hoping to improve our web analytics as well – but we wanted to start with email since it’s a little easier to do and it gives us a fast way to validate our thinking before we tackle the larger project.

Please give us feedback on them

Again, we’re new to reworking these, and we know that there are many different use cases. If something looks off, please let us know. If you’re looking for specific numbers that we’re not yet showing you, let us know that, too.

We’d be grateful for your input, as we’re only getting started here and we know there’s room to continue improving this.

Some folks want their archives available so they can link to them, but don't want them to come up in Google results.

Some folks want to prohibit LLMs and other scrapers from crawling their archives.

Both of these are eminently reasonable! We tried to handle a lot of this with a very engineer-brained approach: give you a big ol' textarea where you can type user agent strings to block.

People do not know or care about user agent strings, we realized. So we replaced all of it with a Crawling add-on in Settings → Archives, holding one toggle per kind of crawler.

We looked at usage (and our support volume) and found the two biggest reasons/avenues that y'all care about, plus a catch-all for everyone else:

1. Search engines. Turn it off and every subscribe and archive page tells Google, Bing, and friends not to index it, and your sitemap goes dark. Links you share still unfurl nicely on social media, because we keep the OpenGraph tags around.

2. AI crawlers. Turn it off and we block a curated list of AI training and assistant crawlers (GPTBot, ClaudeBot, CCBot, Google-Extended, PerplexityBot, and a few dozen more) in your robots.txt, tag every page for them, and refuse any subscription attempts they make.

3. Everything else. Every other crawler: scrapers, SEO tools, archivers, and the long tail of bots that don't say who they are. Turn it off and your robots.txt tells all of them to go away, with an explicit carve-out for the search engines and AI crawlers you've left on.

One honest caveat: robots.txt lives at the root of a domain, so on buttondown.com/your-newsletter we can't write per-newsletter rules into it. The AI crawlers toggle is fully enforced on a custom hosting domain, and advisory everywhere else. Search engine blocking works the same on both, since it rides on per-page tags rather than robots.txt.

The docs have the full rundown of what each toggle does under the hood.

Frequently asked questions

What actually changed for me?

For almost everyone, nothing. All three toggles default to on, which matches how your archive already behaved: search engines could index it and AI crawlers could read it. The only newsletters whose behavior changed are the few dozen that had set one of the old hidden noindex flags or typed entries into the blocked user agents box; those were migrated to the matching toggle so they keep doing what they did before.

What happened to blocked user agents?

If you had entries in the old blocked user agents textarea, we migrated you. A list that named AI crawlers becomes "AI crawlers: off". A list that named Googlebot or Bingbot becomes "Search engines: off". A list that named anything else — vulnerability scanners, SEO bots, a stray archiver — becomes "Everything else: off", which disallows every crawler outside the two named buckets. If you were relying on very fine-grained per-agent rules, the firewall is a better home for them than robots.txt.

Is this paywalled?

No. The whole add-on is available on every plan, including the free one. The only wrinkle is that fully enforcing the AI crawlers and everything else toggles through robots.txt needs a custom hosting domain, which is a paid feature; without one, those toggles still block sign-ups from AI crawlers and tag every response, but can't write to robots.txt.

A few weeks ago, I ranted in a very technical manner about our work to consolidate analytics and events onto a single source of truth. I framed it as a behind-the-scenes post rather than something user-facing, because it was one of those boring and necessary efforts where you spend a huge amount of time wrangling internal machinery, legacy code, and bizarre historical data, only to have nothing particularly concrete to show for it except some long-awaited data reconciliation bugs that had finally been squashed. But I ended that post with a promise: that it would let us do useful things much more easily than we could before.

This is one such thing! Open any sent email, click the export icon in the analytics pane, and you now get a choice. You can download the aggregate export you could already get (the number of opens, clicks, deliveries, and so on), or you can download an itemized export: every specific event that rolls up into those numbers.

I know, I know. That is a pretty boring feature to get this excited about. But the reason I'm excited is that it is barely a feature at all, from our perspective. It is a single export that is definitionally equivalent to paging through that email's events in the API. Take a look at these two snippets:

One export, scoped to a single email

curl -X POST https://api.buttondown.com/v1/exports \
-H "Authorization: Token your-api-key" \
-d '{
"collections": ["events"],
"parameters": {"email_ids": ["em_01j8x9v2q7f3k4m5n6p7r8s9t0"]},
"format": "json"
}'

Or page through the same events yourself

curl "https://api.buttondown.com/v1/events?email_id=em_01j8x9v2q7f3k4m5n6p7r8s9t0&page=1" \
-H "Authorization: Token your-api-key"

They return the exact same set of events, because they read from the exact same source of truth. There is no separate "export pipeline" that could drift out of sync with the analytics you see in the app, or with the events API. The export is just a filter over the events log, handed to you as a file. Which also means the same machinery works for anything else you can filter events by: a subscriber, an automation, an event type, a date range. Pass those as parameters on the exports API today, if so you dare.

Okay, I might have veered a little bit into overselling the technical side, because the user experience is, once again, boring: you click a button and get a file. But at least we got a little bit more of the former this time!

TL;DR

We consolidated two separate analytics pipelines into a single data store. Nothing is required on your part; some numbers might look slightly different, but they're more consistent now. The rest of this post is the author nerding out about technical esoterica.

First, a brief inquiry into changelogs

Generally speaking, we like to reserve changelog entries for meaningfully observable improvements. Anything that's visible but relatively trivial 1 tiny feature, an esoteric bug fix 1 gets relegated to the longer changelog. And anything that doesn't even clear that bar doesn't merit a public accounting at all.

This makes infrastructural changes tricky to talk about. Sometimes we cover them as behind-the-scenes posts pitched more at engineers than users, like our recent one on migrating our database to PlanetScale.

But what do you do about a massive architectural change that has an imperceptible-but-non-trivial user impact? And how can an impact be simultaneously imperceptible and non-trivial?

Let me stop dancing around the point. We have standardized and consolidated our events. Where we once had two distinct sources of truth for things like opens, clicks, and deliveries, now we have one. Everything downstream of them 1 automations, analytics, webhooks, and so on 1 works off that single source: the events log, which has been around for a while.

Until very recently, those two data sources overlapped almost identically. And if you've ever been cursed with the knowledge of maintaining two similar datasets, you know that "almost identical" is worse than "wildly divergent." So we painstakingly unshipped the dataset we internally called email events and replaced it entirely with external events, which are clearer, more constrained, and well-documented.

Stop navel-gazing! Tell me what changed!

Very specifically: the last remaining places we exposed the old source were in email-related roll-ups 1 looking at click rate over time in your analytics, or drilling into the analytics pane inside a sent email.

We've backfilled all of that data, and it's now keyed off external events. No data has been lost, but you might see some small changes, because the new source enforces stricter idempotency. If you see wildly divergent numbers, please write to support and let us know.

Why does this matter to me?

Honestly, the average user probably doesn't care about any of this, so thank you for being a trooper and getting this far. But if you've ever bashed your head against our analytics, you might appreciate some of the second-order effects:

1. Consistency. Our numbers now add up across disparate views in the app and the API.
2. Performance. It's much easier to optimize one data pipeline than to keep two of them in lockstep.
3. Access. This entire dataset is already available in the UI as the events page. Later this month, we'll expose it via the API too, so you can grab whatever aggregations or pivots you want without stooping to the UI.

A plea for understanding

Analytics are really tricky, both architecturally and from a customer-experience perspective. This is one of several work streams aimed at making our analytics better in some ineffable sense 1 a task made harder by the fact that half of our users don't care about analytics whatsoever while the other half treat them as being of utmost importance. Harder still because "analytics" isn't really a single feature, and the data people care about varies wildly.

We want to move toward a world where we're very opinionated about what we think the majority of users will find useful, while offering programmatic access and exploratory tools for the long tail of more esoteric use cases. In that respect our philosophy mirrors how we've evolved templates: bake out the design tokens everyone cares about, while still leaving custom CSS as a backdoor.

As we do, we want to hear from you! If you have analytics-related woes, email Nick who is working on a redesign of the whole shebang.

POST /v1/subscribers with X-Buttondown-Collision-Behavior: add will now respect passing type: unactivated and will send a confirmation email instead of going directly to type: regular when passing an unsubscribed email address.

See Creating a subscriber for the full add vs overwrite distinction.

Breaking API change

This is a backwards-incompatible change to Buttondown's API. Pinning your newsletter or request to an older API version keeps the previous behavior where a version was cut for it.

We've added segments to the API: saved, reusable audiences — a named set of tag and metadata filters that you can apply as the audience of an email instead of rebuilding the same rules every send.

Five new endpoints:

• GET /v1/segments
• POST /v1/segments
• GET /v1/segments/{id}
• PATCH /v1/segments/{id}
• DELETE /v1/segments/{id}

Note that an email's audience is a snapshot: applying a segment copies its filters onto the email, so editing or deleting a segment never changes emails you've already sent or scheduled. Emails continue to accept filters directly; segments are purely additive, and no existing endpoints change behavior.

Breaking API change

This is a backwards-incompatible change to Buttondown's API. Pinning your newsletter or request to an older API version keeps the previous behavior where a version was cut for it.

POST /v1/subscribers with X-Buttondown-Collision-Behavior: overwrite no longer returns a 201 while leaving an unsubscribed subscriber unchanged. Overwrite cannot change terminal types (unsubscribed, blocked, complained, undeliverable) and returns 400 with subscriber_suppressed instead.

To resubscribe, use X-Buttondown-Collision-Behavior: add (which still flips unsubscribed → regular) or PATCH with {"type": "regular"}.

See Creating a subscriber for the full add vs overwrite distinction.

Today we're launching forms

Today we're launching forms: an easy way to add standalone pages to your newsletter whose whole job is to get you new subscribers.

The rest of the industry would call these landing pages. We're probably leaving money on the table by not calling them that too — but it just doesn't feel like the right vibe for us.

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

Why you'd want one

Say you're running a promotion for your new book, and you want to drum up subscribers who'll follow along as it gets released. You want to offer them a sneak peek of the first few chapters, and you want to tag them specifically so you can reach out again when the sequel lands.

You could already do a version of this today, but neither path is great. You could add a custom input to your main subscribe form — but then you'd have to rewrite your newsletter description to explain what it's all about. Or you could hand-write a standalone HTML page — a curse I'd wish on nobody.

With forms, you spin up a standalone page dedicated just to the book, with styling and content unique to it. Anyone who subscribes through that path gets tagged automatically by Buttondown — no hoops to jump through — so you can build an automation that targets them specifically. You can give the form a custom URL that's snappy and easy to remember, and you can watch the conversion rate for that form alone.

The docs walk through building your first one.

How it fits into the bigger picture

One of the things I'm always mindful of is not adding functionality for the sake of adding functionality — and not adding power-user features that serve complex use cases while making the experience subtly worse for everyone else.

I'm really happy with where we landed, because forms are a genuinely new abstraction we can offer without sequestering functionality behind them or demanding extra effort from the paths you already use.

I had two goals in mind as we designed this:

1. Build it so that the majority of users can simply not use it.
2. Set up the abstractions to minimize conceptual overhead.

On that second point, stick with me: the main subscribe page you've always had is, in effect, just a form — one that happens to always take the style of your newsletter and its description. Forms don't bolt a new concept onto Buttondown; they generalize one that was quietly there the whole time.

Availability

Forms are available on the $29/month Standard plan and above. That's where most of the functionality that unlocks their potential — animations and the like — already lives.

As always, if you have any questions or thoughts, email me.