Following up on subscriber-editable tags

When subscribers see a list of tags they can toggle on or off, sometimes the tag name alone doesn't tell the whole story. "Weekly" is clear enough, but "Premium Content" or "Beta Access" might need a bit more context.

Now you can add a public_description to any tag. This shows up as helper text in the subscriber portal, right below the tag name — giving subscribers the context they need to make an informed choice.

The new field is available in the Tags API :

curl -X POST https://api.buttondown.com/v1/tags \
-H "Authorization: Token $API_KEY" \
-d name="Beta Access" \
-d public_description="Get early access to new features before they're released to everyone." \
-d subscriber_editable=true

You can also add it when updating existing tags:

curl -X PATCH https://api.buttondown.com/v1/tags/{id} \
-H "Authorization: Token $API_KEY" \
-d public_description="Weekly digest of the best links from the community."

The field is optional and only matters for subscriber-editable tags — if a tag isn't visible in the portal, the description won't show anywhere. But for tags that are subscriber-facing, a good description can make the difference between someone toggling it on or scrolling past.

Original source Report a problem

OpenAPI spec for template context

If you've built a custom theme or done anything programmatic with your archive pages, you've probably had to reverse-engineer the data that Buttondown passes to your templates. What fields are available? What types are they? What's nested where? The answer has mostly been "check the docs and hope for the best."

Now there's a proper OpenAPI spec describing the full shape of the template context — every field, every type, every nested object. It covers everything from newsletter metadata and email content to subscriber details and subscription URLs.

This matters if you're building on top of Buttondown's archives. If you're writing custom CSS themes, building integrations, or just want autocomplete in your editor, having a machine-readable schema makes all of that easier. And if you're not doing any of that — this doesn't change anything for you, your archives work exactly the same.

We're publishing this for the same reason we've been investing in archives more broadly this year. Between new themes, more customization options, and the larger archives overhaul we outlined at the start of the year, we've been making a lot of changes to how archives work. A formal spec is our way of being transparent about what the contract looks like — and being deliberate about not breaking it. If we change the shape of the data your templates rely on, we want that to be a conscious, documented decision, not an accident.

Original source Report a problem

Subscribers can now respond to surveys from the web archive, not just email.

Up until now, surveys only worked inside the email itself — if a subscriber clicked through to the web version of your email, they couldn't actually respond. That was annoying for a bunch of reasons: maybe they were forwarded the link, maybe they prefer reading in a browser, or maybe they just clicked "view in browser" out of habit.

Now surveys work on the web too. If your email has a survey, subscribers reading the web archive version can respond right there, no extra setup required.

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

This also means you can share a link to an email with a survey and actually collect responses from it — handy if you want to post a poll on social media or link to it from your site.

Original source Report a problem

Subscriber editable tags in the portal

Flip a toggle and subscribers can add or remove tags themselves in the portal.

A common request we've heard for years: "I want to let my subscribers pick which topics they're interested in." Maybe you've got separate tags for "weekly roundup" and "product updates" and want people to opt into what they care about. Or you run a local newsletter and want folks to choose their neighborhood.

This has always been possible in Buttondown, but it was clunky. You'd need to set up the subscribe form input, wire them to automations, and hope everything stayed in sync — we, to be honest, missed the ball by focusing on the easiest point solution instead of thinking hard about the right long-term solution.

Now it's simple: go to any tag, flip on "Subscriber editable" and you're done. Your subscribers will see it in their portal settings, where they can toggle it on or off whenever they want (as can you.)

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

This is the first of several improvements we're making to the portal. We're really happy with what the portal can do, but we know it's been confusing to understand how it fits with the rest of your setup — especially around paid subscriptions and comments. We're working on making all of that clearer. This was the easiest and most urgent fix, so we started here.

Original source Report a problem

API keys and permissions

If you use the Buttondown API, you've probably run into this: you've got one API key, and it can do everything. That's fine when it's just you tinkering around, but once you start building real integrations — a Zapier workflow here, a custom script there, maybe a third-party tool that only needs read access — sharing the same all-powerful key everywhere starts to feel a bit risky.

Now you can create multiple API keys, each with its own permissions. Head to API 12; Keys and you'll see a new management page where you can:

Feature Description Create as many keys as you need No more sharing a single key across all integrations Give each one a label So you remember what "api_key_7f3a" is actually for Set granular permissions Control exactly what each key can do

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

The permissions are pretty straightforward 12; for each category (subscribers, emails, automations, etc.) you can choose:

Level Access Write Full access to create, update, and delete Read Can view but not modify None No access at all

So if you're building a dashboard that just displays subscriber counts, give it a read-only key. If you're integrating with a third-party form tool, create a key that can only add subscribers. If something goes wrong with one integration, you can regenerate or delete that specific key without breaking everything else.

This is especially handy if you're working with contractors or external tools 12; you can give them exactly the access they need, nothing more.

Check out the API authentication docs for more details on how to use your keys.

Original source Report a problem

Automations with a delay: Re-evaluate filters after delay

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

Let's say you want to send a specific email to everyone tagged "prospects" four days after they sign up. What happens if that tag gets removed on day three—maybe they converted to a customer, or you cleaned up your tags?

Without this option, the automation would still fire on day four. The subscriber matched the filter when they first signed up, and that's all Buttondown checked.

With "Re-evaluate filters after delay" enabled, Buttondown checks your automation filters again right before the action runs. If the subscriber no longer has that "prospects" tag (or no longer matches whatever filters you've set), the automation skips them entirely.

You'll find this toggle in your automation settings whenever you have a delay configured. It's off by default, so your existing automations will keep working exactly as they do today.

If you're using the API, you can set this with the new should_evaluate_filter_after_delay parameter.

Original source Report a problem

Snippets

You can now create snippets — reusable chunks of content you can drop into any email with a few keystrokes.

demo.buttondown.com/settings/snippets

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

Think of snippets as your personal content library. Maybe you've got a promo block for your latest project — a poster, a trailer link, a quick blurb — that you want to drop into different emails without rebuilding it each time. Or a sign-off you use every week, or a disclaimer for sponsored posts. Instead of copying and pasting (and inevitably forgetting to update one of them), you can create a snippet once and insert it wherever you need it.

To get started, head to Settings → Snippets and create your first snippet. Give it a name and an identifier (that's what you'll use to insert it), then write whatever content you want.

demo.buttondown.com/settings/snippets/new

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

When you're writing an email in Fancy mode, type / to open the command menu and search for your snippet by name. Select it, and the content gets inserted right where your cursor is.

If you're writing in Markdown mode, you can insert a snippet using the tag:

<buttondown-snippet name="your-identifier"></buttondown-snippet>

Snippets can even include other snippets — useful if you want to build up modular content blocks. (We cap it at 4 levels deep to prevent infinite loops, but that should be plenty for most use cases.)

If you reference a snippet that doesn't exist, you'll see a warning in your draft so you can fix it before sending. No more accidentally sending emails with broken placeholders.

Original source Report a problem

Design settings page removal

We've removed the Design settings page in favor of separate settings for Archives and Emails.

A few months back we split apart the design settings page into two pages: one for Archives and one for Emails. This gave us the space we needed to add more Archives features and new themes.

But since then, we've been asking ourselves "What does the design page actually do?"

The answer is, "Not much" so we've removed it.

• Styling that's applied to the whole newsletter is now in Settings → General. This includes things like your share image, icon and tint color.
• All features/styling for your Archives are in Settings → Archive design
• And styling for your email template is in Settings → Email design

We've added these two pages to the left-hand navigation for easier access. (But you can star them too!)

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

If you run into any issues, just let us know — we're here to help!

Original source Report a problem

Star pages to pin to your sidebar

You know how you always end up navigating to the same handful of pages? Maybe it's your subscribers list filtered by a specific tag, or your emails sorted by draft status, or that one analytics view you check every morning.

Now you can star any page to pin it to your sidebar, right below Home.

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

Just click the star icon next to the page title. If you're starring a filtered view (like /subscribers?type=premium), you'll get to give it a custom name so you can tell your starred views apart at a glance.

A few ideas for how you might use this:

• Star your subscribers page filtered to show only premium subscribers
• Star your emails page filtered to drafts you're actively working on
• Star a specific automation you're tweaking frequently
• Star your inbox filtered to conversations that need a response

Starred views are stored locally in your browser, so they'll persist across sessions but won't sync between devices (because we, frankly, were a little too lazy to handle the myriad edge cases).

Original source Report a problem