Buttondown: minimalist newsletter + inbox placement check

Buttondown attracts a specific kind of newsletter writer: developers, researchers, essayists. The product is minimalist on purpose — write in markdown, schedule, send. There is no drag-and-drop template builder, no sprawling automation canvas. That minimalism is the appeal, and it is also why Buttondown newsletters tend to have good deliverability by default: plain text and clean HTML ratio is exactly what Gmail's Inbox classifier likes.

"By default" is not "always". Even a disciplined 1,000-subscriber list on Buttondown occasionally lands an issue in Promotions or Spam — usually after a subject-line experiment, a subscriber-import, or a pattern that looks like list-reactivation. The cheap defence is a seed test on each issue.

Why Buttondown users still need seeds

There are three failure modes that affect Buttondown writers specifically:

• Subject-line drift. Indie writers experiment with subject lines. A subject like "FREE: my course is open" will earn you Spam across half your list even if your content is flawless.
• Long gaps between sends. A six-week silence followed by a big send looks like reactivation. Receiving filters treat reactivation suspiciously.
• Growing past Buttondown's warm-up curve. If you import 2,000 subscribers to a list that has been sending to 200, the next issue faces a volume step change that receiving providers notice.

Seeds will tell you which of these actually cost you placement and which you can ignore. That turns nervous guessing into signal.

Buttondown API for subscribers: importing seeds

Buttondown exposes a simple REST API with token auth. Adding seed subscribers programmatically takes one curl per seed or one JSON batch via the bulk endpoint. Get your API key from Settings → Programming in Buttondown.

# add one seed as a subscriber
curl -X POST https://api.buttondown.email/v1/subscribers \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "seed-gmail-a1@inbox-check.io",
    "tags": ["seed"],
    "notes": "seed — Gmail consumer"
  }'

A twenty-seed batch takes roughly twenty seconds to provision. Tag every seed seed so you can exclude them from audience counts and — if you really want — from specific sends.

A tiny bulk-seed script

#!/usr/bin/env bash
# seed-buttondown.sh — add a seed list to Buttondown in one go
API_KEY="$BUTTONDOWN_API_KEY"

while IFS= read -r email; do
  curl -s -X POST https://api.buttondown.email/v1/subscribers \
    -H "Authorization: Token $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\":\"$email\",\"tags\":[\"seed\"]}" \
    > /dev/null
  echo "added $email"
done < seeds.txt

Test before every issue — the workflow

With seeds subscribed and confirmed, they receive every issue automatically. The question is how you actually use that data. The tight loop looks like this:

1. Draft the issue in Buttondown.
2. Use the "Send test email" feature to dispatch to your seeds only. Buttondown lets you specify a list of test recipients.
3. Wait two minutes, then check each seed inbox across providers.
4. If placement looks fine (Inbox or Primary or Updates), publish the issue to the full list.
5. If placement is bad on one or more providers, adjust subject line or content and re-test.

What good looks like on a Buttondown list

Because Buttondown senders tend to be text-heavy with minimal promotional markup, well-behaved issues usually hit Primary (not Promotions) in Gmail. That is better than most newsletter platforms can manage. Expect:

• Gmail: mostly Primary; Promotions on any obviously promotional issue.
• Outlook / Hotmail: almost always Inbox if SPF and DKIM are clean.
• Yahoo: Inbox reliably.
• Mail.ru / Yandex: Inbox with correct DKIM alignment.
• ProtonMail: Inbox; trackers stripped.

buttondown seed results — essays.buttondown.email
                 gmail     outlook  yahoo   mail.ru  proton
  issue 83       Primary   Inbox    Inbox   Inbox    Inbox
  issue 84       Primary   Inbox    Inbox   Inbox    Inbox
  issue 85       Promo     Inbox    Inbox   Inbox    Inbox  <- "launch" subject
  issue 86       Primary   Inbox    Inbox   Inbox    Inbox  <- back to normal

Frequently asked questions