Buttondown Release Notes

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.

Today we're launching the ability to save and reuse custom segments

And before I explain what those are, I have to share the trials and tribulations of naming this feature.

You've always been able to build and apply tag and metadata filters when sending an email or examining your audience — but simply calling this "filters" didn't quite feel right. Because then we'd have to distinguish between the filters we hand you by default, like premium subscribers, and the ones you set up yourself, like churning subscribers tagged high-value. And I bring that up as an example because there's genuinely no difference in functionality between the two. We haven't made filters any more or less powerful, or any more or less complicated. We've just added a way to save a filter so you don't have to spend quite as much time mucking around in the filter builder.

But none of the other nouns felt right either. "Audiences" felt a little prescriptive. "Saved filters" felt too gross. "Subscriber groups" added a bit of conceptual overhead: do I now have to assign a group to every subscriber when I create them? So we landed on the abstract and hitherto-untainted-by-prior-knowledge "segments," and we hope not to regret it.

As I mentioned up top, segments are more of a nicety than genuinely new functionality. There's nothing you can technically do today with a segment that you couldn't do yesterday. What they give you is a bit of unification: you no longer have to dig back through old emails or bounce between tabs to make sure you're sending to exactly the group you mean to. And crucially, they're available in the API, so if you'd like to manage them programmatically, you can.

Why ship segments now is a reasonable question. The honest answer is that three people asked me for them in the same week, which is the kind of thing I take as a sign from the gods — like seeing five ravens fly over a town's gate.

One note on availability: segments are only available on the $79/month plan and above. More than anything else, this is meant to reflect who they're useful for. If you balk at that price point, our mental model is that you probably don't need segments and are overcomplicating things. If you take umbrage with that statement, please do let me know — I'm genuinely curious to hear about your use case.

For the fuller picture of every way to slice your list — tags, metadata, paid versus free — see segmenting your audience.

Sometimes complexity is fractal in interesting ways, and other times it is honestly kind of boring.

We've long offered the ability to tether your RSS-to-email send to the first of the month, or the first (say) Wednesday of the month, or of course the last day of the month.

But we neglected to offer the ability to send on, say, the 29th, for the simple reason of laziness. I figured the effort of explaining and documenting what should happen when the 29th of a given month doesn't exist outweighed the theoretical return.

The way such an assumption gets invalidated is by enough people telling me that they want such a thing. So here I am. I sat down and dealt with some calendar logic to bring you the ability to send on any arbitrary day of the month.

Note that, as part of this, we technically "unshipped" the ability to choose the first or last day of the month. If that's what you want, just choose the 1st or the 31st and we'll do the right thing 1 and for any day a given month doesn't have (the 29th of a short February, the 31st of April), we quietly fall back to that month's last day.

Head to your feed's cadence settings to pick your day. As always, let us know if you run into any snags.

Buttondown already allowed you to gate the tail end of an email behind a wall based on subscriber type or reading location (email versus web archive).

Now, we've added a more granular tool for making portions of your email visible to just one type of audience: filtered blocks.

Today, Filtered blocks come in four varieties which determine the visibility of their content:

• Email only: visible in emails (hidden from the web archive)
• Web only: visible on the web archive
• Subscribers only: visible to subscribers of your newsletter (free, paid, or gifted) across both email and web
• Paid only: visible to premium subscribers

Filtered blocks are perfect for thanking paid subscribers, nudging unpaid ones to upgrade, or fine-tuning your content across email and the web.

Try them out in the editor today by typing / and scrolling down to the new filtered blocks section.

As always, let us know if you have any feedback or encounter any snags.

When you share a Buttondown archive link on Bluesky, it can now render as an enhanced link card carrying your publication's name, avatar, and a themed cover, instead of the plain title-and-snippet Bluesky shows by default.

This is powered by standard.site, a community-built standard for describing publications on the AT Protocol (the network underneath Bluesky). Buttondown publishes a small record to your own Bluesky account describing your publication, plus one for each publicly-archived email — and Bluesky uses those to render the nicer card.

To turn it on, head to Settings Integrations, open the Bluesky integration, and click Create publication under "Enhanced link cards." From then on, both the links Buttondown auto-posts to Bluesky and the ones you (or your readers) paste in by hand will render as enhanced cards.

A couple of things worth knowing:

• You'll need your Bluesky account connected and your archive set to public enhanced cards describe your public archive, so they only apply to emails that are publicly archived.
• Bluesky pins a card's contents when it's posted, so this applies to future posts and shares. Links you've already shared keep the card they had.
• The records live in your own Bluesky account and carry only enough to identify each article and link back to it never your email's content. Disconnect any time and the cards you've already posted keep working.

Check out the full documentation for the details. Happy posting!

A few years back, we launched LaTeX support: LaTeX in the archives and in the emails themselves. This was, objectively speaking, not a good use of time or energy. It continues to be a poorly adopted feature, largely for the reason that most people don't know what LaTeX is and have no use case for it.

But you know what? I really liked doing it, even though I knew at the time that both of those things would be true. And I have no regrets about having done so, because it's great for the tiny subset of people who use it.

In that same spirit, I'm delighted to announce an equally esoteric and ill-advised addition to our bespoke rendering pipeline: Mermaid charts.

Mermaid is, for lack of a better metaphor, a Markdown-shaped dialect for generating things like flowcharts or architectural diagrams. We use it all over our own docs. It's handy because the process of authoring one is pretty simple and feels natural alongside your other Markdown content — you just write a fenced mermaid block and describe the diagram:

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

And as you might have surmised from the embed just above, Buttondown now renders these for you automatically.

We've done this in a similar manner to our support for LaTeX. On the website, we render diagrams dynamically with JavaScript, so your archives get crisp, live SVGs. On the email side — since email clients don't support SVG or <canvas> — we capture each diagram via a headless browser and then aggressively cache it as an image that we store and serve. No setup required.

Will most of you ever use this? Almost certainly not. But if you're the kind of person who thinks in flowcharts, this one's for you.