Buttondown

Buttondown

Use Buttondown's API to create and manage newsletter email drafts.

Safety Defaults

• Draft-first: when creating an email, set status: draft unless the user explicitly approves a different status in the current conversation.
• Do not send, schedule, publish, delete, or send draft previews without explicit user approval in the current conversation.
• Do not put API keys in chat, command history, repo files, draft bodies, logs, or screenshots.
• Read the Buttondown API key from BUTTONDOWN_API_KEY. Store it in your shell, launcher, runtime secret store, or OpenClaw SecretRef; never ask the user to paste the token into chat.
• If using a platform account for multiple newsletters, pass the Buttondown newsletter username through --context or BUTTONDOWN_CONTEXT.

Configuration

The bundled CLI reads the API key from:

export BUTTONDOWN_API_KEY="..."

Prefer setting this through your runtime's secret manager or environment injection rather than typing it into a command. In OpenClaw, configure it through a SecretRef or equivalent managed environment variable.

Optional environment:

• BUTTONDOWN_CONTEXT - newsletter username for the Buttondown-Context header.
• BUTTONDOWN_API_BASE - defaults to https://api.buttondown.com/v1.

CLI

Run commands from the skill directory:

python3 scripts/buttondown.py create-draft --subject "Subject" --body-file issue.md
python3 scripts/buttondown.py create-draft --subject "Subject" --body-file issue.md --slug "issue-1" --description "SEO/archive summary"
python3 scripts/buttondown.py create-draft --subject "Subject" --body-file issue.md --editor-mode plaintext
python3 scripts/buttondown.py update-draft <email_id> --subject "New subject" --body-file issue.md
python3 scripts/buttondown.py list --status draft
python3 scripts/buttondown.py get <email_id>
python3 scripts/buttondown.py render <email_id>
python3 scripts/buttondown.py send-draft <email_id> --recipient user@example.com

Use --dry-run on write commands to inspect the request without calling Buttondown:

python3 scripts/buttondown.py create-draft --subject "Subject" --body-file issue.md --dry-run

Workflow

1. Prepare clean Markdown or HTML body content in a local file.
2. Remove YAML frontmatter from the body before uploading. Buttondown rejects bodies that start with frontmatter.
3. Create the draft with create-draft; confirm the response contains status: draft.
4. Share the Buttondown email ID and archive/admin URL from the response when available.
5. For a preview email, show the user the target recipient(s) and get explicit approval, then run send-draft.

Body Format

Buttondown detects Markdown versus HTML automatically. To force the editor mode, pass:

• --editor-mode plaintext for Markdown.
• --editor-mode fancy for rich HTML.

The CLI prepends the official Buttondown editor-mode comment when this option is set.

API Reference

Read references/api.md when you need endpoint details, request fields, status values, error codes, or direct curl equivalents.