# Buttondown

> Create, update, inspect, and send test previews of Buttondown newsletter emails through the Buttondown API. Use when Codex needs to post newsletter copy as a Buttondown draft, manage Buttondown email drafts, preview draft emails to specific recipients, or inspect Buttondown email metadata. Defaults to draft-only and requires explicit user approval before sending, scheduling, publishing, deleting, or emailing previews.

- Skill: `lord1egypt/buttondown` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lord1egypt/buttondown`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lord1egypt/buttondown/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Lord1Egypt (https://skillmd.com/u/lord1egypt)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/lord1egypt/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:

```bash
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:

```bash
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:

```bash
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.