Buttondown Release Notes

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.

Original source

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.

Original source

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.

Original source

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.

Original source

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.

Original source

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!

Original source

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.

Original source

We've changed how drilling down into opens and clicks works on an email's analytics page. Gone is the clumsy and slow modal of yesteryear; arrived is a quicker and more ergonomic nested drilldown. Click into opens, clicks, replies, bounces — whatever you're curious about — and the details unfold right where you are, instead of in a dialog floating on top of everything.

This all comes from the same data source as before (the same open tracking and click tracking you already have), which means we got to unship a bunch of bad UX and make it easier for you to poke around and understand at a glance how subscribers engage with your emails. It pairs nicely with sorting and filtering your sent emails by open and click rate: find the outlier from the list, then drill into it without ever losing your place.

There is exactly one casualty of this change: you can no longer view the number of times a given subscriber has opened or clicked an email from within the email's view. That count now lives on the individual subscriber's details page instead. I'll be honest — I don't think anyone is relying on that functionality particularly heavily. But if you secretly are, and this change has broken your workflow in some way, please do write in so we can learn more and potentially get you situated some other way.

Original source

Ever since we launched comments, Buttondown has emailed you when a subscriber comments on one of your posts, and emailed your subscribers when someone replies to their comment. But those notifications were read-only: to actually respond, you had to click through to the archives and type your reply there.

Such hoops of indirection are a thing of the past! Every comment notification now accepts replies. Hit reply in your email client of choice, write what you have to say, and send — your response threads right back into the discussion, attributed to you, and the other party gets notified just as if you'd written it on the web. This works for you as the author and for your subscribers alike, on every plan with comments enabled, with no setup required.

I could tell you something lofty and business-brained about how this makes it easier and more wonderful for you and your subscribers to continue conversations on the go, or whatever. But mostly I just think it's neat when email is used as an interface and not just a broadcast mechanism, and this felt like an obvious such example where we could improve.

Original source

Earlier this year, we shipped several changes allowing customers to manage archive visibility based on subscription status.

While we were very happy to accommodate a growing body of different use cases, numerous ad hoc tweaks led us to find just as many edge-case bugs and inconsistencies.

So we decided to go back to first principles to design the hierarchy of settings:

1. Archive settings are the default for all new posts

Your archive settings are the default for all new posts in your archive.

2. Per-email visibility overrides the default

Archived visibility settings on each email allow you to override the default archive settings.

You can manage archive visibility in the Publish modal of each email (or Details, if the email has already been sent).

You can also edit visibility in bulk from the emails page by selecting emails and then choosing the "change visibility" option.

We also added a column called Archive visibility that you can add to the emails page, so you can quickly skim through web visibility for your existing emails.

3. Subscription walls and paywalls

For even finer tuning of content visibility, you can block parts of content within a post with paywalls (visible to paid subscribers only) or a subscription wall (visible to subscribers only) through Fancy mode in our editor — type / and pick the function you want.

Original source

Earlier this year, we shipped several changes allowing customers to manage archive visibility based on subscription status.

While we were very happy to accommodate a growing body of different use cases, numerous ad hoc tweaks led us to find just as many edge-case bugs and inconsistencies.

So we decided to go back to first principles to design the hierarchy of settings:

1. Archive settings are the default for all new posts

Your archive settings are the default for all new posts in your archive.

2. Per-email visibility overrides the default

Archived visibility settings on each email allow you to override the default archive settings.

You can manage archive visibility in the Publish modal of each email (or Details, if the email has already been sent).

You can also edit visibility in bulk from the emails page by selecting emails and then choosing the "change visibility" option.

We also added a column called Archive visibility that you can add to the emails page, so you can quickly skim through web visibility for your existing emails.

3. Subscription walls and paywalls

For even finer tuning of content visibility, you can block parts of content within a post with paywalls (visible to paid subscribers only) or a subscription wall (visible to subscribers only) through Fancy mode in our editor — type / and pick the function you want.

Original source

Your Inbox replies can carry files now, not just text. So when a subscriber asks for a PDF, an image, or your media kit, you can send it without ever leaving the conversation.

It's a new paperclip in the reply composer: click it, pick a file, and it rides along with your reply — the same attachments you can already add to your emails. Once the reply sends, the file shows up as a download chip in the thread, so you can always see what you sent.

Reach for it whenever the conversation calls for more than words — a media kit for a prospective sponsor, a corrected PDF for the reader who flagged a typo, a quick screenshot to settle a question.

It builds on replying to conversations from your Inbox, and it's live now on every plan that includes attachments — open a conversation and give it a try.

Original source

Your Inbox replies can carry files now, not just text. So when a subscriber asks for a PDF, an image, or your media kit, you can send it without ever leaving the conversation.

It's a new paperclip in the reply composer: click it, pick a file, and it rides along with your reply — the same attachments you can already add to your emails. Once the reply sends, the file shows up as a download chip in the thread, so you can always see what you sent.

Reach for it whenever the conversation calls for more than words — a media kit for a prospective sponsor, a corrected PDF for the reader who flagged a typo, a quick screenshot to settle a question.

It builds on replying to conversations from your Inbox, and it's live now on every plan that includes attachments — open a conversation and give it a try.

Original source

We launched a revamped reply tracking back in February, and it's gone over very well in many respects. However, the passage of time has revealed, as it always does, a few warts and errors in our thinking, and we're changing how we do things as a result. Thanks, everyone, for providing your feedback and in some cases your patience. We knew we were being a little prescriptive and heavy-handed with how we rolled this out, and did so largely in order to simplify the setup process — but it's clear that the edge cases were more common than we had anticipated.

First, to lead with the changes themselves:

1. For manual custom sending domains (i.e., you are not delegating a subdomain to us), we will never set an MX record on your behalf. You must provide your own.
2. Additionally, on manual custom sending domains, reply tracking now defaults to off — replies flow straight to your own inbox — though you can turn it back on yourself any time under Settings → Sending domain → Add-ons.
3. If you're using a managed custom domain (i.e., delegating the sending domain to us), the reply-to address — which has been hitherto hidden, requiring you to write to support to enable it — is now generally available under the Domain Settings page.

Here's a table walking through the three paths as a result:

Shared domain Managed custom domain Manual custom domain MX record MX record is irrelevant We set an MX record for you. Reply tracking You cannot opt out of reply tracking. You cannot opt out of reply tracking. Reply-to You cannot set a custom reply-to. You can set a custom reply-to, and this is generally available.*

Hopefully this clarifies the three options you have when setting up your newsletter a bit:

1. You can use our shared domain, which requires no setup but also begets little customization;
2. Use a custom domain in managed mode, which makes it easy to send from your own domain though limits your customization slightly;
3. Or use a completely manual custom domain, which affords you ultimate flexibility, but now you have to deal with DNS records.

None of these changes require any work on your part. If you've already set up a custom domain, then it will continue working just fine as is.

• These defaults apply to manual domains set up from here on out. If you're already on a manual setup, your replies keep working exactly as they do today — and whichever way you'd prefer, reply tracking is now a self-serve toggle under Settings → Sending domain → Add-ons, so you can take over your own replies (or hand them back to us) without writing in.

Original source

We launched a revamped reply tracking back in February, and it's gone over very well in many respects. However, the passage of time has revealed, as it always does, a few warts and errors in our thinking, and we're changing how we do things as a result. Thanks, everyone, for providing your feedback and in some cases your patience. We knew we were being a little prescriptive and heavy-handed with how we rolled this out, and did so largely in order to simplify the setup process — but it's clear that the edge cases were more common than we had anticipated.

First, to lead with the changes themselves:

1. For manual custom sending domains (i.e., you are not delegating a subdomain to us), we will never set an MX record on your behalf. You must provide your own.
2. Additionally, on manual custom sending domains, reply tracking now defaults to off — replies flow straight to your own inbox — though you can turn it back on yourself any time under Settings → Sending domain → Add-ons.
3. If you're using a managed custom domain (i.e., delegating the sending domain to us), the reply-to address — which has been hitherto hidden, requiring you to write to support to enable it — is now generally available under the Domain Settings page.

Here's a table walking through the three paths as a result:

Shared domain Managed custom domain Manual custom domain MX record MX record is irrelevant We set an MX record for you. Reply tracking You cannot opt out of reply tracking. You cannot opt out of reply tracking. Reply-to You cannot set a custom reply-to. You can set a custom reply-to, and this is generally available.*

Hopefully this clarifies the three options you have when setting up your newsletter a bit:

1. You can use our shared domain, which requires no setup but also begets little customization;
2. Use a custom domain in managed mode, which makes it easy to send from your own domain though limits your customization slightly;
3. Or use a completely manual custom domain, which affords you ultimate flexibility, but now you have to deal with DNS records.

None of these changes require any work on your part. If you've already set up a custom domain, then it will continue working just fine as is.

• These defaults apply to manual domains set up from here on out. If you're already on a manual setup, your replies keep working exactly as they do today — and whichever way you'd prefer, reply tracking is now a self-serve toggle under Settings → Sending domain → Add-ons, so you can take over your own replies (or hand them back to us) without writing in.

Original source