Buttondown's engineers, writers, and biggest fans write about new features, and more.

Product updates

, complete with a slew of new content and improved API documentation!

Although our previous documentation site has served dutifully, it was starting to show its age:

However, we noticed that a lot of customers writing in to customer support were referencing having searched the docs for an answer. Sometimes we 

 have docs on what they were looking for, but the taxonomy and search were failing them. Other times, it was something we really 

Email newsletters are also a somewhat uniquely thorny prosumer product — there’s a lot of edge cases and varying setups, which warrant good documentation.

With a need and interest established, we started working on a new documentation site at the end of last year.

, both for engineers and non-engineers. That means:

, a wonderful tool from Thinkmill that bolts a content editing interface onto your website, which ultimately saves files back to your GitHub repository.

Keystatic is super customizable, which allowed us to extend the editor with custom components. Our previous site was written in MDX, so it was important that we had some way of porting over custom components (Keystatic stores its content in 

For example, some of our pages include a “Live Code Block,” which shows code alongside with a live preview of the code’s result:

In Keystatic it’s super simple to define this component:

liveCodeBlock: component({
  label: "Live Code Block",
  schema: {
    html: fields.text({ label: "HTML", multiline: true }),
  },
  preview(props) {
    return (
      <div
        dangerouslySetInnerHTML={{
          __html: props.fields.html.value,
        }}
      />
    );
  },
}),

And then we separately define how the component should render on the page as a React component:

Another goal was to make it easier for authors to determine where new pages should go.

Our old docs site had pages grouped into categories in the left sidebar, but the categories were created over time, leading to weasel-y categories like “Advanced Features”.

The URLs of the pages also contained the category, like 

, meaning that we couldn’t easily rearrange the categories without breaking links.

In the new docs site, every page is at the root — like 

. This means that we can continually rearrange the navigation hierarchy (using a custom Keystatic editing interface!) without breaking any links.

We’ve also split out separate sections of the docs: Guides, Reference, and API. It felt strange to mix long-form tutorials and guides (”How to collect metadata for your subscribers”) with more one-off pieces of reference material (”What happens if I edit an automation while it’s active?”).

With the taxonomy improved, we can feel better about creating mounds of documentation (big and small), knowing that it all has a reasonable place to go.

Also, we’re still not fully happy with the taxonomy we’ve ended up with and the content will grow over time, so this allows us to rearrange the taxonomy without breaking links in the future.

 documentation on certain topics, but that our search was a bit clunky.

In classic fashion, I did a bit of over-engineering, and we’re now using 

 to process every bit of writing on the site, and then matching it to search queries by comparing the distance from your query to every piece of writing.

It’s not perfect, but it’s noticeably better at finding results that are 

 similar (for example, “image” and “photo”).

There’s a ton of solutions off the shelf, but ultimately, documentation is a core part of Buttondown’s product. One way that we differentiate is by providing a superior customer support experience, and this documentation site paves the way for us to extract more knowledge out of one-off customer support replies and into reusable and into publicly searchable documentation.

We could have used something prebuilt, but our slightly quirky needs (custom components, a custom navigation hierarchy, improved API docs) plus room to grow (vector embeddings search, affordances for related documentation pages and FAQs) mean that we feel more confident and future-proof rolling our own site.

We're excited to share our brand new documentation site.

How we built Buttondown's new docs

A few months ago, Stripe launched Payment Links — the absolute easiest way to collect payments (both one-time and on a recurring basis) on the internet with absolutely no code required.

(A disclosure: I work for Stripe! We’re hiring.)

First, take a look at what one of these Payment Links look like (courtesy of a great Buttondown newsletter, 

Historically, the only way you’ve been able to collect paid subscribers for your Buttondown newsletter is by going through Buttondown’s official channels: funnel a subscriber onto your subscribe page (or a page with an embedded subscription widget), collect their email, and then prompt them to pay.

This is a good workflow, but it’s certainly not perfect for all use cases. Buttondown’s subscription paradigm is not perfectly portable, and doesn’t yet support things like Apple Pay or local payment methods common in European markets.

Because Buttondown integrates directly with your Stripe account, prospective paid subscribers no longer need to go through your Buttondown newsletter to collect payments or subscriptions. You can head over to your Stripe dashboard and generate a Payment Link for your Buttondown subscriptions and instantly get a URL to share with your Twitter followers or Twitch audience or whomever. Buttondown will automatically detect the new subscriptions and create paid subscribers as they come in.

(One thing that Buttondown doesn’t handle at the moment is the ability to generate a subscriber list for customers who have signed up through Stripe for subscriptions to serviced other than Buttondown. If you’re interested in exploring this world — for instance, being able to spin up an arbitrary newsletter based on the customers that are already in your Stripe account — please email me! I’d love to hear more.)

And, as always, if you have any questions, feature requests, or suggestions — I’m all ears. My aim is to make Buttondown as easy to use as possible, and you — yes, you! — probably have some great ideas on how to get there.

It's even easier to get paid subscribers with Stripe's new Payment Links

Support for Stripe Payment Links

, paving the way for their ability to 'reclaim' abandoned accounts that have been deemed inactive.

I'd like to take this opportunity to re-affirm Buttondown's policy on this subject:

(As always, these policies can be superseded by healthy judgment in cases of terms of use violations: if you're egregiously camping usernames or engaged in malicious activity on the platform, they may not apply. )

Here's the thing: digital life is hard enough. You should not have to spend any time worrying about someone stealing your digital identity, nor any time worrying about a URL you visited in 2023 having vanished in 2025.

Buttondown is, more than anything, committed to making your life a tiny bit easier in a number of ways. We hope this policy is one of those infinitesimal ways.

Maintaining a digital life is hard, so we're committed to making it easier.

Buttondown's username retention policy

If you log on to Buttondown today (or, I suppose, any date in the foreseeable future), you'll notice that the sidebar is a little smaller. Gone are the three separate links to 

, that has, well, all three of those things.

You'll notice that you can now actually sort this list by pretty much anything as well as filter it by status or audience.

 change than a new feature, I know. But there are important features for Buttondown (filtering emails by metadata or tags; sorting by number of opens; 

an edit interface that isn't, frankly, hot garbage

) that necessitate this change, and it's an easier way to get a sense of your entire writing corpus beside.

This is the first tranche of a number of exciting changes I'm landing over the next few weeks! If you have any thoughts or concerns or run into any issues, please — as always! — 

All your emails, in one place

One of the delights in watching Buttondown take off over the past few years has been seeing the proliferation of use cases that, frankly, I never really imagined when I started building it. Teachers & faculty are using Buttondown to send lesson plans to their students; a peer group of poets uses Buttondown ("round robin style", as I've been informed) to send over drafts to edit & critique; a food truck sends out weekly locations & specials.

One common thread that I sort of intentionally 

 This is not a particularly hard technical problem, nor is it a tricky UX problem - the core flow of dragging and dropping a file into an editing interface is all but solved!

The thing that gave me pause for so long was less the surface-level implementation and more the so-called "long tail" of choices and impacts that adding attachments would entail. Should Buttondown add tracking on downloads (so an author can see who's downloaded what?)? How many attachments are allowed for a given email? What happens to attachments after they've been removed from an email? And so on. At risk of turning this anodyne blog post into a bit of a therapy session - this is what building software is like. Even the "easy" things come with hundreds of little microdecisions along the way, and I want to make sure that I get as many of those microdecisions 

Anyhoo, after hemming and hawing for a fairly long time - 

 They are exactly what I think you might expect they are: drag and drop, no fuss or muss. There's no tracking or anything too-clever-by-half happening. Check it out:

And when you attach a file to your email, it's downloadable on the web archive version too.

So - send your emails, with great care and joy and now also with as many (well, up to three) attachments as you'd like.

Drag and drop has never been easier. (Just like Gmail.)

Attach files to your emails

This post is about a fairly nerdy part of Buttondown’s featureset — webhooks. If you’re a less technical user, this stuff probably doesn’t apply to you.

I’ll be honest with you — it is hard to keep track of the myriad ways folks use Buttondown’s events & webhooks. There are the standard ones: listen to 

 events and then publish the email to the CMS, listen to 

 events to update tags in an internal database, and so on. But the long tail is where I find it hard to keep track: I know of one newsletter, for instance, that is listening to 

 events to sync their Buttondown drafts with their local iPad storage in a way that I probably 

 advise as good engineering but I am still quite fascinated by.

 you’re using webhooks [^1], there’s one piece of feedback that you’ve probably given me: that the dinky little “events” table in the Programming page is… let’s say lackluster.

 that feedback. I have internalized it. And now I’ve built something better. Behold the new 

Gone is the amateurish limit of 100 events: now you can paginate to your heart’s content! (And yes, that pagination widget is… a little cumbersome at this point, and I will be replacing it with something that requires a little less horizontal scrolling.)

 to make it easier to pinpoint problematic events and replay them:

In fact, I’m so in love with this filtering component that I plan on backporting it to the subscribers page too to allow more in-depth filtering & sifting there!

Anyway, apologies for how long-overdue this page is. I tend to only hear about the webhooks & events side of things once-per-customer (as they’re setting things up) and then it goes back to being quiet, so I forget how annoying it can be. If there’s any part of the 

 side of Buttondown that you wish was better, please 

[^1]: And to be clear, per the “nerd alert” preamble at the top of this post — if you don’t even know what a webhook 

, that’s completely normal and fine and this post is probably not for you.

A better events view

I suspect that there are two groups of people who read the title of this blog post: those who are saying "oh 

!" and those who are unfamiliar with the term 'multi-factor authentication'.

 is necessary but inefficient in today's world to protect your account from malicious attackers. The most common family of approaches to defend your account is referred to as "multi-factor authentication", which is exactly what it sounds like: relying on additional pieces of evidence 

 just your username and password in order to authenticate that you are who you say you are. (Have you ever had to type in a six-digit code that was texted to you, or click a link sent to your email? That's multi-factor authentication, too!)

Buttondown now lets you protect your account with the help of a third-party authenticator app like 

. These apps exist as a remote fingerprint with a rotating code; when you log into Buttondown, you'll be prompted for the code from one of these apps.

If pictures are worth a thousand words, screenshares are worth at least fifteen hundred. Here's a 

 of what registering a QR code looks like and how to log in after doing so:

The support I've added for authenticator apps is one of many reasonable approaches that folks like to take when it comes to multi-factor authentication. I've already received requests for other avenues, such as 

 and SMS support. I plan on expanding coverage in the future; if you have a particular use case you'd like to have me know about, please 

Buttondown offers support for Google Authenticator (et al)

Secure your account with multi-factor authentication

My single favorite way to make Buttondown better is a simple two-step process:

If you're an author of a premium newsletter, you might be familiar with what is a pretty annoying process every time you write a paid-subscribers-only email: first you write the paid-subscribers-only email filled with lovely writing and send it off to your loyal subscriber base, 

 you take a truncated version of it and add a little teaser to send to your non-paying subscribers in order to incentivize them to sign up.

I am here to tell you that is no longer a thing! When choosing a cohort of subscribers to send to, you'll now see an optional toggle to also send a teaser to unpaid folks:

By default, Buttondown sends a "teaser" of the first three paragraphs of your newsletter and then prompts readers to subscribe for the rest, just like online:

If you'd rather supply your own copy, though, it's as easy as you'd otherwise expect. And the custom teaser is template-friendly, so you can add 

I want to invest more over the next few months in making it not just easy for authors to grow and nurture their subscriber base but to make sure the process of 

 those subscribers into paying readers is as easy as possible. This is a good first step, but there's more, like opt-in pageview & archive tracking, so you can analyze which emails are best at both bringing in new subscribers and converting those subscribers and tiered subscription levels.

But beyond all that, I'm just interested in making Buttondown 

. If you find yourself feeling like it's taking you twenty clicks to do what should take three, please 

 and tell me more — I can't wait to hear from you.

On the technical side of this feature, there were two particularly interesting challenges of note:

Introducing teaser emails for paid newsletters

Send teasers for paid newsletters

I’m getting tired of starting off all of these feature announcements with some variation of “this might have been the single most frequently requested feature of the past twenty-four months”, but… this might be the single most frequently requested feature of the past twenty-four months [^1]: 

you can now send previous emails to subscribers in your Subscribers page

First, though, a bit of background: Buttondown’s subscriber-email relationship has always been intentionally spartan. There are no clever knobs or automation sequences; I’ve intentionally optimized for ease of onboarding and conceptual simplicity over 

, meaning that all you can really do with an email after sending it is set it to be your ‘welcome email’ that greets new subscribers or use it as scaffolding to build a new email.

Folks have wanted the ability to send arbitrary emails 

 to new subscribers for a long time, and the reasons they gave have grown extensive:

, select a few subscribers (or just one), and click the 

 button as seen below — you’ll be prompted with your full list of emails to send to folks.

There are a couple caveats with this feature:

But beyond that, the world is your newsletter-y oyster! Please let me know if there’s anything else you’d like to see: as always, I 

[^1]: Modulo the ones that I had already implemented, that is.

You can now send past emails to your subscribers who didn't receive them!

Send archived emails to new subscribers

A long-standing request that I’ve never quite got to is the ability to throw in subscription forms in the middle of your emails, so that folks who are scrolling through your web archives are prompted to subscribe before the end of the email itself.

This approach is something that I’m sure has vigorous and impressive scientific impacts on your conversion funnel, but moreover it for a long time was my favorite type of feature request, the one that hits two constraints:

On that second bit, I haven’t taken full advantage of it yet, but Buttondown now renders every email twice — once for email clients and once for the web archive. This makes it much easier and cleaner to build features like this in the future!

Anyhoo, the magic incantation you’re looking for is:

As in, if you want a cute little interstitial in the middle of your email you can do something like:

Here’s a cute picture of a dog!

{{ subscribe_form }}

And then here’s an even cuter picture of a dog!

You can also check out the full list of magic codes (or to use the technical term, “template variables”) in Buttondown’s documentation 

. If you’re looking for anything else along these lines, let me know — I’m all ears!

Use {{ subscribe_form }} to let folks subscribe faster!

Embed your subscribe form in the middle of your writing

It's been almost a year since I switched 

tracking & analytics over to be off by default

, and the feedback has been unanimously positive, even for the folks who end up enabling it (by which, to be clear, I mean no shade — Buttondown's official newsletter has click tracking enabled!)

I've received a fairly common piece of feedback from privacy-conscious newsletters:

I love the commitment to less data collection. I wish I could just track open rates without actually tracking clicks, though: I don't personally care too much about either piece of data, but when I sell to advertisers they often request some rough percentage of opens. Would it be possible to just keep track of opens?

! If you head over to your settings page, you'll see the tracking setting replaced with four checkboxes:

The idea here is simple: rather than a binary state of "track stuff" or "don't track stuff", you as an author now have even more control over what information is important for you to keep track of. (And to state the obvious: everything remains off by default, and respects your original settings.)

Buttondown is probably going to shift even 

 in the data collection direction: I have plans this year to roll out bespoke page view counting, for instance, as well as to pull in some more payments-level data for paid newsletters. But rest assured: every step of the way, you get control over what you want Buttondown to hold onto, and that Buttondown's data is for all intents and purposes 

(As always, if you have any thoughts about this or anything else, 

Authors now have more control than ever over their data collection

Granular tracking settings

To be blunt, the upselling experience for paid subscribers has been…bad. This is entirely my fault!

When designing the paid subscriptions experience, I had a few blunders:

Both of these choices manifest in a number of less-than-ideal ways, but one particularly egregious one is the flow by which subscribers upgrade to premium subscriptions. Up until this week, they would have to go to the click a link in the footer of their email, re-input their email address, and then they were prompted to sign up. It was a confusing thing that spawned a lot of emails, and I get it. It was bad! No way around it.

Now, though, things are better. Rather than bore you with some of the technical details of how things are better, I’d like to just show you! This is the page that a subscriber is brought to when they’re prompted to upgrade their subscription in an email:

No fiddling with inputs or remembering what email address they used. Just a simple Stripe-powered checkout page. This has rolled out automatically, and you should see a healthy uplift in conversions!

And if you're interested in dynamically inserting this link at an opportune moment, you can! The magic template variable is 

Buttondown has an improved paid subscription flow!

Better upselling for premium subscriptions

For a long time (as in, up until today), Buttondown could only charge in dollars for paid newsletters. This is no longer the case!

I'm honestly not sure what else to write here. The code change was pretty boring (thanks, Stripe!). This was long overdue; the number of newsletters outside America outnumber the number of newsletters inside America. I'm happy I was able to make the change.

If you haven't set up a paid newsletter and you're interested in doing so, it's as painless as starting a business on the internet could be! Just go over to your 

(If you're interested in charging in a currency that isn't currently listed in the page, 

Accept whatever currency you want for your paid newsletter

Obligatory "this is not an April Fool's joke" disclaimer aside: excited to announce that support for pay-what-you-want* subscriptions are now live! You can give it a test run on 

Setting it up is fairly easy; you go to your 

, hit the ol’ checkbox, choose a cadence, and you’re off to the races.

There are a couple fast follows (to use a slightly obnoxious term) that I plan on adding:

That's it! These blog posts are getting shorter and sweeter as time goes on, it appears, but I'm excited to see how people use this — probably the single most common paid subscriptions feature request (after PayPal support. everyone wants PayPal support.)

Pay-what-you-want subscriptions

The single biggest pain point for me in 2020 was the fact that my email service provider did not support HTTPS tracking links. 

, this resulted in a truly awful onboarding experience in which people would onboard and send emails through their HTTPS-only domain, discovering in their first newsletter that all of their links were broken in some browsers. The worst thing! You can’t take back emails, and if folks didn’t catch it when drafting (which was sadly often) it meant their first-ever experience with Buttondown was marred.

I’ve been a huge fan of the folks over at 

 for a long time: Buttondown has been using them as a transactional email provider for years. When they launched support for non-transactional emails, I was itching for a reason to try them out — and lo and behold, here is the perfect one!

How to use it (if you’re not sending from any custom domain)

All you need to do to start sending from your custom HSTS domain is to go through the regular “sending from a custom domain” flow on your 

. Buttondown will automatically detect that you’re sending through an HTTPS-only domain and route your newsletter to use Postmark instead.

How to enable HTTPS tracking (if you are already sending from a custom domain)

This is... a little jankier. Go ahead and 

 your custom domain, and then re-add it — you should now see a new set of custom DNS records to use. Once you’ve added them, go ahead and re-enable analytics tracking and you’re good to go!

You can now send emails from your custom HSTS domain

Support for HTTPS tracking links

investments in something that existing users will probably not appreciate

 and it appears that this week I am continuing the trend by announcing a change that only affects new accounts going forward:

Buttondown is turning off analytics by default.

 accounts: I haven't changed any settings on existing accounts.)

This is something that a few folks have mentioned over the years: allowing newsletters to opt out of link and open tracking is nice but allowing an escape hatch is a little less opinionated than defaulting to do the right thing.

 this past week, and one of John's comments rekindled this notion:

Buttondown’s privacy “win” is that it at least allows you to turn tracking off with a simple checkbox. Most services don’t. I can’t find any hosted service that doesn’t offer tracking period, or even defaults to no tracking.

If you'll let me wax poetic about running a service for a second: it is tiring to make decisions, and it is easy to think from the outside that certain artifacts are deliberate as opposed to made from a lack of decision.

Analytics being opt-out wasn’t deliberate so much as it was an artifact of that being originally implemented as an opt-out and then me not changing anything or revisiting it in the past three years.

But that's how building things on a temporal budget goes, and "lack of decision" is not meaningfully better than a bad decision: it is useful to get the codebase viewed from a completely contextless lens, and to strip away a bit of the archaeological detritus that comes from remembering the Buttondown of 2021 and the Buttondown of 2019 and the Buttondown of 2017.

Anyhoo. Now it's opt-in, because opinionated defaults matter. And all it was was a single line of code:

As a reminder, if you want to opt out (or now 

) to analytics, all you have to do is go to your 

And stay tuned for more news on the privacy & sensible data front! My goal is to push out some changes that let you get information about your newsletter without having to go 

 on the tracking pixel front, like conditionally enabling clicks but not opens (or vice versa) and adding support for anonymized tracking (so you know 

 is opened or clicked on without knowing 

Buttondown is turning off analytics by default for all new users

Email tracking is now off by default

 is a simple, privacy-friendly alternative to Google Analytics. It's fully compliant with GDPR, CCPA, and PECR, and offers 

. It's a great way to learn more about your site and your subscribers & visitors while respecting their privacy.

I've been a huge fan of what Plausible has been doing, and I'm excited to partner with them and integrate our two services: their ethos is 

 account is simple and takes all of five minutes! You can integrate with your newsletter and track viewers of your archives, plus see what visitors are clicking on the most and which of your archive pages are most effective at getting folks to subscribe.

We're excited to partner with Plausible to bring you improved analytics.