Tips and tricks from Buttondown's engineers, writers, and fans.

Guides and tips

Jane Friedman tries to send an issue of her author newsletter every two weeks or so. And after 15 years of watching the numbers, she's found even that is sometimes infrequent enough for people who just signed up to forget who she is by the time her next issue lands in their inboxes. Her solution is what she calls an autoresponder.

Others might call it an “email automation,” “drip campaign,” or “welcome sequence,” but they’re all (horribly named, for one, but also) the same thing. In 

, it’s three emails sent to new subscribers over 10 days to “introduce people to some of the most key posts and information I make available for free.” 

, and you’ll see something similar. Her signup confirmation tells you to expect “a quick series of getting-to-know-me emails over the next week or so, starting tomorrow.” 

There are many different ways to design a series of emails that are automatically sent in response to specific events. You might 

 to new signups or celebrate when subscribers hit their one-year anniversaries. All that matters is that you create automated campaigns that further your relationships with readers and minimize marketing busywork.

Most newsletter platforms include an option to send a welcome email after someone signs up or confirms a subscription. But that’s a single email that goes out immediately. Like Friedman, you may want multiple welcome emails sent out over days or weeks to familiarize people with your writing.

Another reason to create a multi-message welcome sequence might be a “graduation series” similar to the one 

indie sci-fi author Matthew Buza describes

 as “a way to move a person from [my autoresponder] into my main list, but only people who have graduated through my autoresponder.” That way, subscribers only start receiving your regular newsletter after more important introduction emails. For Buza, “The sole goal of the autoresponder is to get the new reader to buy one of my books, leave a review, and opt into my Advanced Review Copy team.”

You could build that in Buttondown in a few minutes (or, if you aren’t on Buttondown’s $29/month tier, play with automations at 

). First, make sure to turn off any default welcome email. Then, open your automations builder and set the trigger to any time a subscriber confirms their subscription. Choose whether you want the action to take place immediately or after a delay, set the action to send an email, and write your first message.

Using the same trigger but with longer delay times, you might draft a graduation series with emails on days one, four, and nine after someone confirms their subscription. 

You'd need a way to differentiate subscribers who have and haven't gone through the graduation series. Tags are perfect for this. After the final welcome email on day nine, create an automation that's triggered by a signup confirmation, waits 10 days, and then applies a tag (e.g., Graduated) as the action. When you want to send newsletters that only go to people who've gone through the entire series, send only to subscribers with the Graduated tag.

That’s only the beginning (literally). You can create similar campaigns where templated emails “drip” out at predetermined intervals for anything that fits within the triggers and actions available to you.

Now, let’s say you have a few hundred subscribers who had signed up before you set up your welcome series. All you have are their email addresses and, if you’re lucky, their first names. Whomp whomp. The best way to start (ethically!) gathering more data on subscribers in this situation might be an automation triggered when readers click a link or 

Professional writers, for example, might poll readers about their favorite fiction genre or non-fiction topic. Assuming you have 

 turned on, you’d set up an automation triggered by a subscriber clicking a link or a survey in your newsletter and set the action to add tag (e.g., reads-urban-fantasy or likes-popscience).

Adding the details to subscriber profiles alone would be enough to inform more targeted launch emails and promotions. But you could take it even further by putting together sequences that fire off whenever a specific tag is added. Maybe you want to automatically send a list of your favorite books in a subgenre (possibly mentioning a fellow author as part of a 

) or link to all your articles and books relevant to a subscriber’s favorite non-fiction topic. 

Using automations to segment your list is a fantastic way to make newsletters more personal and valuable for individual readers without a ton of manual work on your part. What’s more, you can use the same basic flow to keep your newsletter’s performance stats above average and your monthly costs low.

Spammers have made newslettering much harder for the rest of us. They spend so much time finding ways to get around blockers and filters that email providers like Google are constantly upping the threshold for what they deem a good-faith sender. If you want to avoid your subscribers’ spam folders, your open and click rates need to be high, and your unsubscribes need to be low. 

One way to be proactive about that is with a re-engagement series. Once or twice a year, you’d filter your subscribers list to only show people who have been subscribed for at least three months but haven’t opened anything during that time. These are the people at risk of hurting your stats.

 a “List cull every six months. No good paying for subscribers on your list who don’t add value—but you need to give it a few months for them to demonstrate a clear pattern of not interacting with your content.”

With the sorted and filtered, you could create an Unengaged tag, and bulk add it to anyone who stopped engaging. 

At this point, you set a trigger for any time the unengaged tag is added, with an action to send an email. The first message would say something along the lines of “Hey, it looks like you haven’t been opening the newsletter recently, although that may be because you’re blocking trackers, which I totally respect. Since I don’t want to clog up people’s inboxes with emails they’re not opening, I periodically remove anyone from my list who is unengaged. So, if you want to keep receiving my emails, click this link or reply to this email, and I’ll keep you on the list and respect your tracking preferences going forward. Thanks!”

Next up, an automation that removes the unengaged tag from anyone who clicks the link or replies directly. And two more time-delayed reminders sent to anyone with the unengaged tag who didn’t click the link or reply, capped off with a final automation that ends in the 

 action for anyone who never engaged with the series. Bingo, bango, bongo, cleaner, higher-performing lists after a few minutes of bulk tagging.

marketing yourself is a marathon, not a sprint

. It should be challenging but not unbearable; uncomfortable but never all-encompassing. One of the best ways to manage that balance as more and more people begin following your work is with a newsletter that expands your reach without dehumanizing your brand. 

Autoresponders are as helpful for that as their moniker is off-putting, especially for professional writers and solopreneurs. They help you deliver timely, relevant welcome messages, personalized recommendations and offers, and polite-as-can-be breakup emails–all while you focus entirely on your novel, blog, journalism, or whatever wonderful thing you’re drafting.

Welcome, segment, and unsubscribe readers with email sequences personalized to subscriber actions

Where to start with newsletter automations

A newsletter subscriber is worth 10x more than a website visitor. You have no way to tell a website visitor anything after they've left your site. No way to show them your newest project or announce a special discount. Unless you use (shudder) retargeting ads. When someone gives you their email address, though, that’s a commitment to listen.

Years before Ryan Holiday published his first bestseller, he had a newsletter. It started with 50 friends before exploding to 250,000 subscribers a few years later. Writing about that journey, 

 “Building an email list is the single best way to communicate with your audience, period. Better than Facebook, better than Twitter, better than ads. Because you own it. …no one can get in the way.”

Some of the list’s growth was thanks to a single line at the bottom of emails encouraging people to forward to them their friends. But signups through Holiday’s website were always the best way to establish “a relationship of mutual trust and opt-ins.” And as long as you have something worth saying or selling, the same goes for your site.

Everyone with a website and an email newsletter needs a signup form for the latter on every page of the former. Full stop. On the homepage, the form should be above the fold, visible before visitors begin scrolling. This is true for anyone with a personal website, from software developers to self-published authors to 

“Hi! I’m Cassidy, and I like to make memes and dreams and software! I’m a startup advisor and investor, developer experience expert, open source-er, and meme-maker on the internet. I enjoy building mechanical keyboards, playing music, hanging out with my family and friends, and teaching in my free time. You should subscribe to my newsletter.”

The signup invitation is high on the page but, crucially, after she introduces herself.

, describing his expertise before asking for the signup:

*“Hello, I’m Elliot—a designer, author, and typography enthusiast. You might know my work with Google Fonts & Adobe Fonts, or the magazines 8 Faces & Lagom. Sign up to my newsletter.”

He doesn’t stop there. Elliot also has a newsletter signup form above the fold on 

 page of his website. His portfolio page. Blog. Contact and About me pages. The page dedicated to his podcast and his masterclass. Every one of them.

The goal isn’t so much to get people to sign up as soon as possible. Not many folks would sign up for 

 (I’m down if you are, Netflix). They first want to vet creators before giving them a coveted spot in their inbox. Instead, the idea of Ask Early, Ask Often is making sure that there’s always a signup form in sight, no matter what page they’re on, the moment they’re ready.

Make the forms on your homepage and elsewhere small and unobtrusive. A single email field if you can manage it, 

 including spots for first and last names. That should be low-profile enough to avoid annoying site visitors jumping around from page to page.

Ideally, each form would also have its own ID, allowing you to track where each signup came from. You might find that one page is responsible for the lion’s share of submissions and replicate whatever makes it better than the rest.

If website visitors are worried that your emails are all desperate pleas to buybuybuy or navel-gazing introspections, they’re not going to sign up via the minimalist forms on your homepage et al. They need assurances (and corgi photos).

Ryan Holiday always had a page on his site outlining the newsletter. But it wasn’t doing much heavy lifting until he gave it a facelift, adding “a clear explanation of what the list was, why people should sign up and what they’d get out of it. It [did] wonders for the number of new subscribers.” All it took was a few lines about the newsletter cadence, contents, and commitments to readers.

For instance, every email from Cassidy Williams includes an 

, which she explains on her newsletter details page. Below that she promises not to spam subscribers’ inboxes and links to an archive of previous newsletters. In less than 100 words, she gives website visitors everything they need to decide whether or not to join the list.

Below the context and details of what to expect, you might include a nod to the people who love your emails. On author and photographer 

 section does double duty as evidence of the newsletter’s popularity and descriptions of Mod’s style and tone. It’s often called “social proof” and can also come in the form of subscriber totals or average subscription length. Anything that establishes credibility and makes a signup feel less risky.

Then, a newsletter details page needs a signup form. Although not necessarily the same one you use elsewhere. Visitors who made it to this page are less likely to be put off by a form (what else did they think they’d find?). So you might add fields that ask subscribers to indicate their preferences and 

automatically add tags based on their answers

. That would help you segment your list, sure, but also reinforce the personalization and specificity of what’s on offer.

An author, for example, might ask subscribers if they want bi-weekly book updates or less frequent book launch emails. Or if they only want emails about a specific series, genre, or character. Seeing the thing they want listed as an option makes the form that much easier to fill out.

At the end of the day, every page of your website should carefully encourage visitors to sign up for your newsletter. For the people who are interested but unconvinced, you have a newsletter landing page with all of the details they might want.

Now matter how much urgency you inject into your website’s language, some people just aren’t ready to “Sign up now” or “Join today”. So give them an option with less commitment. Link to a video or PDF excerpt from a course or a book you’re selling, no email signup required, with a reminder about the newsletter tagged onto the end. Or invite visitors to sign up for a series of five automated weekly emails with a promise to stop there unless they opt for more. They aren’t committing to anything long term, and yet they haven’t walked away entirely. Something for everyone!

Like most self-promotion projects, “get more newsletter signups from website,” can seem pretty straightforward before unraveling into an open-ended, neverending mess. There are countless ways you could go about it. First, focus solely on making sure every page of your site has a signup form. Nothing fancy, just Name, Email, and a Subscribe button.

On the homepage and anywhere else that makes sense, toss in a 1-2 sentence pitch just above the form.

Next, create a dedicated newsletter page with 100-200 words worth of details about the newsletter, and a form that has a few get-to-know-you questions.

Finally, add some free ungated (i.e., not behind a form) resources (book excerpts, video explainers, infographic cheatsheets, etc.) and slap a link to your newsletter on the final pages.

All that, plus a few pictures of your dog, will almost certainly move the needle.

Image Credit: Header photo by Bri Tucker via

Provide more opportunities to sign up, more details for people who want them, and reminders for folks who aren't ready to sign up

Your first fifty subscribers

45 emails are sent, every day, for every human alive on earth (that is, if Statista’s email stats and the UN’s population stats are accurate). Nearly two emails, per hour, per person, per day. Activation emails, newsletters, receipts, shipping notices, mentions and comments (and spam. Far too much spam.).

You can minimize your email footprint and trim down how many messages your company sends. Odds are, you’ll boost your open rates and general customer happiness that way. But some emails are expected, required even. There are more of them than you might expect when you first start your business. Shopify’s settings include 45 different email notifications that you can customize, everything from order confirmation and shipping notifications to password reset and payment error emails. Software (like Buttondown) and digital products come with their own email requirements to account for, from account verification to collaboration invitation messages.

What emails should you send? Where should you send them from? Here’s a list of the most common emails your team should be sending—and how to send them.

Marketing Emails: Waitlist, Newsletters, Onboarding, and Updates

Let’s start with the emails that likely came to mind first when you started your business: Newsletters.

You’re building pre-launch excitement for your product, and need a way to keep building that excitement and to let people know when your product is launched. A waitlist paired with a newsletter is perfect for that.

We’re biased, but we think Buttondown is perfect for those emails, plus all of the other marketing emails you’ll need to send over time.

Start with a sign up form. Build your own, add a 3rd party form and connect it with 

Ideally, you’ll want to offer a waitlist form, with an opt-in to your newsletter.

For people who only join the waitlist, send them an 

 thanking them for joining. Then send a newsletter to the full list once when your product launches—which should be the same as a normal email newsletter, unless your product needs a unique invite code in which case you’ll need to either add a code to each subscriber’s Buttondown profile then include it in the email with a 

Waitlist subscribers who don’t sign up should at most get one more, a bit later, as a reminder (if so, have your app use Buttondown’s API to take people off the waitlist when they sign up for your app). And if subscribers don’t convert, that’s ok; don’t overdo emails at this stage, and maybe they’ll eventually come back and rediscover your product.

For everyone else who opts in, here’s your chance to kick off your newsletter. Keep it simple and personal, with Buttondown’s default, Gmail-like theme, to share behind-the-scenes glimpses at your build process and how your team’s thinking through important product decisions. Or, add your logo and colors to emphasize your company’s branding pre-launch. Post-launch, repurpose this list into your company’s default marketing channel.

Pre-launch, you’ll also want to add onboarding emails. Buttondown’s automations can work for that, too. List out the things you’ll need to teach users, and the feedback you’d like to receive from them. Work them into 3-5 emails, add them to Buttondown’s Automations, and schedule them a few days apart.

Over time, you’ll want to add more marketing emails. Perhaps a product update blog where you share new features, a dev blog where you write more technical newsletters and share changelogs, and more. You might even want one-off lists for special events—a signup form followed by regular email updates for a conference, say. Run all of those through Buttondown, as normal.

People will have questions. Comments. Ideas. They’ll reply to your onboarding emails and newsletters, if you’re lucky.

When you first start out, your normal email account is all you need. Set up a new company email account, the same way you manage team emails (in Google Workspace or another email service), add it as a Contact Us email on your site, and use it as the reply address in your Buttondown automated emails and newsletters. Add an auto-reply, if you’d like, to let people know you got their message and will get back to them ASAP. Then reply as normal, just as you would with any other email.

Long-term, as your team grows, migrate that to a customer support app, something like Help Scout or Zendesk, Front or Intercom. You need a shared inbox, where your team can reply to customers together in the same place. Keep the emails simple; a plain, Gmail-style email is still likely best for a personal touch. And add automations that help your team—auto-replies with suggested documentations, or pre-written snippets to save time—but try to keep your emails human and friendly.

Support emails are emails you’ll keep tweaking over time, but they’d never make sense to handle through anything other than a personal email client for small volume, then a dedicated support app at scale.

Not directly from your app, per se. Buttondown uses Postmark and Amazon SES to send emails; your app should use those or other transactional email services to actually send the emails via API calls.

Then build out triggers in your app, add HTML email templates with your company’s branding and style, and send them through your email API.

You’ll need account verification emails, plus a verification reminder a few days later if users don’t activate. Login emails, if you want to use Slack-style Magic Link emails instead of passwords. Password reset emails, for accounts with passwords. Activity messages, like when DigitalOcean tells you a server is ready, your credit card says you’ve made a purchase, or Buttondown tells you someone joined your email list. Inactivity messages, to bring users back when they’ve fallen away. Shipping notifications, if you’re selling physical products.

Each of those emails require a relatively simple email template, paired perhaps with the customer’s name, unique links for their account, and activity details if needed. More complex emails that are a deeper part of your product offering—such as Google Maps’ email with details about your location’s reviews, or Ahrefs report of new and lost keywords and search rankings—will require similarly advanced templates and instrumentation.

Collaboration and notification emails will similarly require templates paired with more detailed instrumentation. If your app offers collaboration features, you’ll need invitation emails—for the invitee, and for the inviter once the invitation has been accepted (emails that could do double-duty with light tweaks for a referral program, if you offer one). You might need variants of those emails for individual and team accounts. And you’ll need emails for any other parts of collaboration: Edit requests, comments, suggested edits, and the like.

Same for notification emails for follows, likes, mentions, and more—or, perhaps, for estimated arrival dates and tracking info for physical products. Each requires both thinking through the data needs, and the logic of when and where to send the message. If your app supports in-app notifications, default to that ideally, and only email when users aren’t online. It’s worth digging in and building detailed notification logic, 

, to keep from having your customers’ apps and email inbox dinging with notifications at the same time. Or, offer options for a digest email that shows all notifications once a day or so; it’s a bit harder to build, for something that will make your users appreciate the emails and be less likely to automatically delete everything they receive from your company.

Some emails could be sent on your behalf, from other services, especially for the finance side of your business. Stripe, for example, could email your customers when they pay—with additional email reminders about ending trials, failed payments, subscription renewals, and more.

Or, you could take over them all yourself. If so, first note every email you need to send about billing and payments. End of trial, subscription confirmation, payment receipt or invoice, renewal notification, upgrade or downgrade notices, or shipping updates for physical products.

You also may need usage notices for metered billing or limited features. Dropbox, for example, emails when your storage is almost full, while Twilio emails if your account balance is running low. You’ll need to build internal triggers that fire whenever users hit those thresholds paired with email templates that share details about the metric and what users need to do, and send them via your transactional email service.

One finance-adjacent email you could send via Buttondown automations, if you want, is download reminders. Selling non-online digital products like eBooks and other downloadable items? Whenever a sale comes in, add that user with a tag to Buttondown, with an automation that sends everyone with that tag the download link. Or, if the download needs to be customized per-user, send it in-app like notification emails.

Another finance email perfect for newsletters: Pricing changes. If you’re changing pricing for everyone, you could use Buttondown to update your entire user base about the changes. Or, if you’re only updating specific account types, tag those users and send them a one-off message the same way.

Then come the emails that could come from Buttondown or another newsletter service, if you’d like. Things where you’ll need to write more text and send messages occasionally, as needed. These are worth keeping a full list of all of your users’ email addresses—even though you 

 should send your standard newsletter to them, unless they’ve opted in.

When your terms of service or privacy policy changes, you’ll need to notify customers. Same for GDPR-type changes; when new regulations affect your business, they may also require updates. Or, if there’s a breaking change—if all users need to update their app or add info to continue using your product, or if there’s a significant outage coming up, or (hopefully not) there’s a security issue, that’s worth telling every customer about, even if they didn’t sign up for your newsletter.

Sometimes there will be notices that only some people need, but could still make sense to send via Buttondown. Issues with integration and 3rd party add-ons should be sent to people who use those items (or, possibly, your whole user base for popular integrations). Same for changes to core features; let the people who use those features know, or just go ahead and email everyone.

And some will be one-off emails that you’ll send once in a blue moon. Holiday messages, sent sparingly. Company milestones and anniversaries, perhaps. Acquisition news, or anything else that means a major change for your users.

These and anything else that’s one-off and text-heavy are perfect for a newsletter. No need to think about templates and sending services. Just keep a spare email list with your entire customer base, and when something comes up, fire up the email list for that one-time email. Include a note in the email’s footer about why you’re emailing and include an option to opt out of even these infrequent emails, just in case. Or, one other option: Keep the list around, and use an automation tool like Zapier to send one-off emails as needed, if you’d rather use something other than your newsletter tool.

Then leave that list dormant until you really need to send an email again. For all the more frequent updates, rely on your core newsletters to stay in touch.

Buttondown covers your newsletter, and onboarding messages. Things your marketing team will want to send and tweak over time. But don’t forget about the rest of the emails you’ll need to send. Some—like terms of service updates—you can build in Buttondown, if you’d like. Others—password reset emails, for example—are best sent directly from your app.

The good thing is, most of the emails you’ll want to tweak are great to be sent from Buttondown. The ones you need to build-in? Odds are you’ll only change them whenever you refresh your app’s design.

There is more to company email than onboarding drips and newsletters

Every email your company needs to send, and how to send them

Remember opening the App Store regularly to install updates? Quaint today, but for the first five years of the App Store—from 2008’s iOS 2 until iOS 7’s launch in 2013—you had to manually install new versions of apps.

That pushed release notes into the mainstream. Suddenly everyone noticed the best changes while waiting on apps to install.

Plenty of apps took the easy way out, listing just “Enhancements and bug fixes.” Others grabbed the opportunity to have fun.

“Oh happy day: A tricksy bug was finally squished,” 

 in an early release. They’ve kept it up, over the years. “The app is objectively better today than it was yesterday. This is a scientifically verifiable fact that cannot be challenged or undermined,” read a July 2024 update.

Just enough fun copy to get you to take notice and read what’s changed.

Automatic updates simplified everything at the cost of programmer humor. “Release notes on apps feel like a relic from 2008-2015 when most apps did maybe 2-3 updates per year at most,” as 

Yet I’d argue you should still have release notes. Changelogs. Patch notes, if you’ve built a game. Product updates, or just plain updates, or a Notion-style What’s New. Whatever you call them, they’re a way to share what’s new or changed, and why you built it, and have a bit of fun as you do so.

Your product needs a changelog. And an email list might be the best way to build it.

Odds are your product has a blog and an email newsletter. Perfect for sharing your largest releases and their headline-grabbing features. Not so much for the minutiae of new minor features, bug fixes, and breaking changes like an updated API call or modified keyboard shortcuts.

The common strategy is to build multiple blogs. Have your core blog for marketing updates, stuff everyone will read. Then a developer blog that lists API and SDK changes. And, for the most dedicated, yet another changelog blog with release notes from every new version.

Or not. Your changelog blog could simply be an email newsletter.

Folks aren’t reading your changelogs on the App Store. It’d take a special level of dedication to open your changelog blog regularly just to see what’s new. Push the updates to their inbox, though, and your most engaged users will know what’s new with your app without any extra effort–almost as good as App Store’s early years.

“Having a good changelog means having a consistently updated changelog,” advises Olivier Lacan’s 

 site. Anything you can do to make writing and publishing changes easy makes it more likely you’ll actually do it. Emails are easy to write and send; there’s less to futz with than a blog post.

So start a new newsletter. Write an email message every time your team ships something new and substantial, detailing the changes. Make it as formulaic or human as you want—it’s your changelog. Then hit send.

Best of all, your newsletter’s archive is a bonus changelog blog for your product, for zero extra effort, with your email newsletter’s archive. Nothing else to maintain, just an easy way to write updates, push them out to everyone, and save them for posterity. There’s even the tiny bonus that it’s hosted separately from your app, so just like an uptime site it won’t go down if you accidentally push a breaking change to main and customers are looking for answers to what happened. Win/win.

Changelogs and release notes have been with us for as long as we’ve been coding (or, at least, since 1971, say 

). They’re a record of truth that lists what’s old, what’s new, and how we got here.

And for just as long, they’ve merged in humor and humanity. “Are you finding it frustrating when everything works on minix?,” 

, tongue-in-cheek, in the second Linux changelog from October 5, 1991.

It’s right there in the name: A changelog should list changes. “Focus on what was changed — who, how and when are usually less important,” 

. GNU coding standards call for detail: Change logs (two words, to GNU) exist “so that people investigating bugs in the future will know about the changes that might have introduced the bug,” 

Yet that detail should be moderated for the sake of brevity. A self-depreciating story of why it took you so long to ship a bug fix might get read. A changelog detailing every push in excruciating detail won’t.

“Changelogs are for humans, not machines,” reminds Oliver Lacan. Which is why Debian moderates GNU’s strictures, advising to use common English, to not “elaborate the trivial and obvious changes,” and to “be polite, don’t swear” (which is good advice—though, I wouldn’t begrudge you an occasional, well-earned swear for especially pesky bugs).

Especially when sending changelogs via email. Have a bit of fun, be human, all in service of writing something people will want to read. “Spending a modest amount of time on writing a changelog saves every reader twice as much time,” says 

With that in mind, work in the actual details. Generally, you’ll want to ship one changelog for every meaningful version. No need to push a changelog update for a tiny fix that no one would otherwise notice; too many of those, and readers will tune you out or unsubscribe. It’s not the App Store where you have to write release notes with every push. Instead, write up the bigger, headline features, and roll up smaller updates into single, larger posts, something I try to do with 

. Don’t just ship your GitHub log; use that as a baseline, and edit it into something more human-friendly.

Then think about the release note’s title. Make updates sound interesting, but also make it easy to find a specific version. List the actual version number, if you use semantic versioning. Include the release date in ISO standard, year-month-date. Buttondown tags your email archives with an ISO date by default—that might cover it, too. Your changelog should also always show the current, most up-to-date version first—exactly the way most blogs and Buttondown’s email archive works, with the most recent post first.

. Good practice for writing portable text, great for turning your writing into email-ready HTML especially with Markdown-powered tools (like Buttondown, ahem).

Building an email-powered changelog in Buttondown

The broad idea of using email newsletters to publish your changelog could work in any email service that includes archives. Buttondown, though, has some dev-friendly features that make it an even better fit for changelogs.

Start with the email itself. You can write updates in Markdown (complete with code samples, if you’re writing about API and SDK changes), paste them into the Buttondown editor, and send. You could 

, to schedule your changelog update directly from your dev environment. Or, you could also write your changelog in Gmail or your favorite email app, send it to 

, and Buttondown will send it on to your subscribers and add it to your archives.

Your archives will be your long-term changelog record. You could stick with Buttondown’s defaults, or customize the CSS to match your company’s branding. You could also add a custom domain, to keep your archives at 

 (with Facebook and Twitter/X coming soon, something you could automate in the meantime with 

). Share updates with your team, too, and have Buttondown post new updates to your 

You could publish the exact same content in your email and your web archive. Or, if you want to include some email-specific copy, perhaps opening with a “Hi”, wrap that in 

, replacing “Hi everyone!” with your copy reserved for emails:

{% if medium == "email" %}
Hi everyone!
{% endif %}

Your product needs a changelog with notifications. An email newsletter is the easiest way to build it.

Start with a changelog

You live and breathe Visual Studio Code (or Sublime Text, or VI, or Emacs). You’ve got strong opinions about code editors, at least. A favorite monospaced font.

Your codebase is a few key-taps away. You type 

And once you’ve coded new features, refactored until everything’s just right, pushed to origin, and deployed the new build, it’s time to tell the world. Open your blog CMS to share details on your dev blog. Open your email newsletter tool in another tab to send the details to your dev list.

Or, that could wait for tomorrow—or you could outsource it to the marketing team. You shipped the features; job done. One more win for 

, as you quickly become one more step removed from your users.

When you could have tweaked your changelog into an email and sent the newsletter from terminal as part of your build process. It's a lot harder to be salesy in the terminal.

Buttondown’s built for developers. Markdown, webhooks, RSS-to-email, in-app automations, and 3rd party integrations. And a robust REST API to do everything you’d do from Buttondown’s interface, via your codebase.

Or Terminal, if you’re so inclined. You can draft a newsletter in Markdown, push it to Buttondown with a 

 command, preview, then schedule it, all without ever moving your mouse.

First, the essentials. You’ll need a Buttondown account—at least a Basic account, starting at $9/month, for API access. 

 if you don’t have a newsletter yet. Turn on Buttondown’s API, and 

Now for the fun part: sending newsletters without ever opening Buttondown in your browser again. You could jump right into 

—or copy the recipes below to schedule newsletters in seconds.

Start with something easy, a draft “Hello, world!” email to test things out without emailing your list. You'll send a POST request to 

 with your API token for authorization, and a JSON-formatted body with an email subject, body, and status of 

 for your API key, then run it in your favorite terminal:

curl -s -X POST \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"subject": "Hello, world!", "body": "Yup, this is an email alright.", "status": "draft"}' "https://api.buttondown.com/v1/emails"

A moment later, Buttondown will respond with JSON-formatted details of your email—including an 

https://buttondown.com/your_list_name/archive/hello-world/

A single line email won't cut it, most of the time (though, couldn't hurt to try once). For the rest of the times, the best strategy is to write your email in 

 with embeds if you include a Giphy, YouTube, X/Twitter link, or 

, or HTML, even. Swap out paragraph breaks with 

 to split out paragraphs. Save the email copy in a JSON file, with separate subject, body, and 

Then POST it to Buttondown as before, swapping in your API key and your email file if you named it something other than 

curl -s -X POST \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" --data @email.json "https://api.buttondown.com/v1/emails"

Add images to your newsletter from Terminal

Want to include images? Two options work. You could upload your image anywhere you'd like—your server, an image service like Imgur, or Github even—and include the image link in your Markdown email copy. Or, you could upload the image to Buttondown from Terminal, copy the link, and include that in your Markdown copy. Swap in your API key and image file name, as before:

curl -s -X POST \
-H "Authorization: Token YOUR_API_KEY" \
-F "image=@image.png" "https://api.buttondown.com/v1/images"

https://assets.buttondown.email/images/ID.png

 link. Copy that link, add it to your email body with a Markdown image embed like 

![this](https://assets.buttondown.email/images/ID.png)

, then wrap up your email and POST it as before.

Schedule an email newsletter from Terminal

You could send your email directly from Terminal. Omit the 

 line from the JSON body and Buttondown will send the email to your list, instantly.

Scheduling is safer, just in case you got something wrong, sent the wrong JSON file to Buttondown, or broke formatting along the way.

For that, you'll need two new lines in your email JSON:

POST as normal, check the preview link, and make sure everything looks good. If not, run the following with your API key and the ID number from your previous Buttondown response to unschedule the email and turn it back into a draft.

curl -s -X PATCH \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "draft"}' "https://api.buttondown.com/v1/emails/YOUR_EMAIL_ID"

In the same way, you could add more data to your email with additional JSON lines. An array of attachment URLs. Tags. A custom slug for the archive page. A boolean to enable comments, or turn them off. Dig through 

 to build out the JSON email template you need.

Automatically build a newsletter from your Git log

Or, dig through the rest of your Terminal command arsenal to turn coding artifacts into newsletters.

You’re already shipping features and detailing the changes with every Git commit. That could be an email newsletter if you reformatted it. Dump your Git log, format it into a Markdown list, and add it to a JSON email body to quickly turn your commit notes into an email newsletter:

git log --since="1 week ago" --pretty=format:"- %s" | \
awk 'BEGIN { print "{ \"subject\": \"This week'\''s commits\", \"status\": \"draft\", \"body\": \"" } { print $0 " \\n" } END { print "\"}" }' > email.json

Write about your software from the place you build it.