Buttondown

Buttondown is the newsletter tool with the cleanest REST API — create draft emails, send to subscribers, manage subscriber lists with tags, and query delivery analytics. For agents: automate subscriber management (add/remove subscribers, apply tags, manage unsubscribes), programmatically create and schedule newsletter drafts, trigger sequences (drip email series), and receive webhooks for subscriber events. Buttondown is indie-built with a focus on developer experience; the API is small, well-documented, and works reliably. Confidence is docs-derived.

REST API at api.buttondown.email/v1. Subscribers: GET /subscribers lists subscribers (paginated with ?page=). POST /subscribers body: {"email": "user@example.com", "tags": ["tag1"], "metadata": {"source": "signup"}} creates subscriber. PATCH /subscribers/{subscriber_id} updates tags/metadata. DELETE /subscribers/{subscriber_id} unsubscribes. Filter: GET /subscribers?type=regular&tag=customers. Emails (newsletters): GET /emails lists drafts + sent. POST /emails body: {"subject": "Newsletter title", "body": "Markdown content...", "status": "draft"|"scheduled"|"sent"} creates/sends. PATCH /emails/{email_id} updates draft. POST /emails/{email_id}/send sends a draft. Sequences: GET /sequences lists drip sequences. POST /sequences/{id}/subscribers/{subscriber_id} adds subscriber to sequence. Analytics: GET /emails/{email_id}/analytics → {recipients, opens, open_rate, clicks, click_rate}.

API key auth: Authorization: Token {api_key}. Key from buttondown.email → Settings → API. HTTPS enforced. Single-user API key (no multi-tenant API). No OAuth2. Webhooks: configure endpoint URL in Settings → Webhooks; events: subscriber.created, subscriber.unsubscribed, email.sent, email.opened. Webhook validation: HMAC signature in X-Buttondown-Webhook-Secret header. Rate limits: documented in API reference (requests per minute per endpoint).

Send reliability: Buttondown uses SendGrid under the hood — delivery rates are high for confirmed-opt-in lists. Bounce handling: automatic — hard bounces auto-unsubscribe. Scheduled sends: status: "scheduled" with scheduled_for timestamp (ISO 8601). API pagination: all list endpoints paginated (results per page configurable with ?count=). Large subscriber imports: use POST /subscribers/bulk for batch creation (up to 1000 per request). Webhook retries: Buttondown retries failed webhook deliveries. Unsubscribe tracking: webhooks fire on unsubscribe; API reflects updated subscriber type.

docs.buttondown.com covers REST API reference, webhook events, subscriber management guide, and email authoring. Getting started: get API key, POST /subscribers — first subscriber in 2 minutes. Free plan (100 subscribers). Paid plans scale with list size. GitHub: no open-source repo (SaaS). Community via Discord (small but active). Excellent API documentation for a solo-built product; Buttondown has one of the cleanest newsletter APIs available.