Send your next email newsletter from Terminal

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 npm followed by run dev without thinking (or if not npm, bun).

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 sales creep, 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 curl command, preview, then schedule it, all without ever moving your mouse.

What you need

First, the essentials. You’ll need a Buttondown account—at least a Basic account, starting at $9/month, for API access. Sign up here if you don’t have a newsletter yet. Turn on Buttondown’s API, and grab your API key.

Now for the fun part: sending newsletters without ever opening Buttondown in your browser again. You could jump right into Buttondown’s API docs—or copy the recipes below to schedule newsletters in seconds.

Draft a newsletter email from Terminal

Start with something easy, a draft “Hello, world!” email to test things out without emailing your list. You'll send a POST request to api.buttondown.com/v1/emails with your API token for authorization, and a JSON-formatted body with an email subject, body, and status of draft.

Copy the following, swap YOUR_API_KEY 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 absolute_URL of something like https://buttondown.com/your_list_name/archive/hello-world/. Open that link to preview your email.

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 Markdown formatting with embeds if you include a Giphy, YouTube, X/Twitter link, or LaTeX formatting, or HTML, even. Swap out paragraph breaks with /n/n to split out paragraphs. Save the email copy in a JSON file, with separate subject, body, and "status": "draft" lines.

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

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"

Buttondown will respond with an 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 "status":"draft" 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:

• "status": "scheduled" instead of the draft line
• "publish_date": "YYYY-MM-DDTHH:MM:SSZ" for the date and time when the email will be published.

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 Buttondown's email API options 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

Open that email.json file, add any extra details you want to explain what you added and changed, delete any extraneous entities, upload a screenshot to showcase the changes and add it to your email, save, and run your Buttondown command to save it as a draft email.

Confident that your Git log alone is enough? Combine the git log command with a date command to format tomorrow 9AM into ISO format, update the JSON body to include that and switch the status to scheduled, then POST it to Buttondown for an email newsletter in seconds. If you’re really confident, that into a cron job or GitHub Action to automatically grab this week’s Git log and mail it out every Friday.

Turns out, you’ve been writing your developer updates all along—you just needed a way to send them out to your followers.

Run your newsletter from Terminal

Why stop there? Buttondown's API includes everything you need to start, maintain, and run an email newsletter without opening the app.

You could start your email newsletter from Terminal. Spin up a new project, and right after your first commit, run the following with your newsletter name and API key swapped in:

curl -X POST \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
		"username": "USERNAME",
    "name": "NEWSLETTER_NAME",
    "description": "DESCRIPTION"
      }' \
  https://api.buttondown.com/v1/newsletters

That username is your new newsletter's slug, so share https://buttondown.com/USERNAME with your followers to get them to sign up. You might not even need to start a blog or changelog for the project; just share the Buttondown archive link for a simple, Markdown-powered blog, complete with an RSS feed for followers who don't want to receive emails.

You could add your first subscribers manually—yourself, your team members, others who you know want to receive your emails—via Terminal, too:

curl -X POST \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "email@domain.com"
      }' \
  https://api.buttondown.com/v1/subscribers

Then draft your first email, schedule it from Terminal, and get back to coding. Rinse, repeat.

Later, when you've sent a number of emails and built a following, you can go back and export your email subscribers to analyze them locally. You'll still need to go online to check your open and click-through rates—but everything else about your newsletter, from spinning up a new list to adding subscribers and sending messages, can be done from terminal.

Send developer emails from your dev environment

You might not even need to use terminal.

You could add Buttondown's code directly to your project, with sample Python, Ruby, and JavaScript code for every Buttondown API call in the docs. Add it to your GitHub Actions, to spin up a draft email when you push new changes. Turn it into a shell script, if you want, to not have to copy and paste commands into Terminal every time.

Then, instead of having to think about what to write on your dev blog, write about what you're coding. Type up a changelog, for commit messages and your dev blog list at the same time. Detail how you resolved a bug, so you'll remember it next time and help out your readers if they encounter something similar.

Don't just write your newsletter. Code it.