Buttondown Newsletter
npx machina-cli add skill The-Focus-AI/buttondown-skill/buttondown --openclawButtondown Newsletter Management
This skill provides newsletter management through the Buttondown API. Use the included TypeScript client script to create drafts, schedule sends, list emails, and retrieve analytics.
Script Location
The API client script is located at:
${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts
All commands should be run using this full path:
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts <command> [options]
Authentication
Set the BUTTONDOWN_API_KEY environment variable before running commands:
export BUTTONDOWN_API_KEY=your_api_key
Available Commands
list
List emails with optional status filtering.
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts list
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts list --status draft
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts list --status scheduled
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts list --status sent
Returns JSON with email IDs, subjects, status, created/sent dates, and basic analytics.
create
Create a new email draft.
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts create "Subject Line" "Email body content in markdown"
Important: Always confirm with the user before creating drafts. Show them the subject and content first.
get
Get full details for a specific email.
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts get <email-id>
analytics
Retrieve analytics for a specific email.
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts analytics <email-id>
Returns opens, clicks, unsubscribes, and rate percentages.
schedule
Schedule an email for future delivery.
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts schedule <email-id> "2024-03-27T10:00:00Z"
Important: Always confirm the scheduled time with the user. Show both the ISO timestamp and local time equivalent.
unschedule
Revert a scheduled email back to draft status.
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts unschedule <email-id>
update
Update an existing email's subject or body.
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts update <email-id> --subject "New Subject"
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts update <email-id> --body "New content"
delete
Delete an email permanently.
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts delete <email-id>
Important: Always confirm deletion with the user - this action cannot be undone.
Common Workflows
Creating and Scheduling a Newsletter
- Draft the content with the user
- Create the draft using the create command
- Note the returned email ID
- Confirm scheduling time with user
- Schedule using the schedule command with the ID
Reviewing Newsletter Performance
- List sent emails with
list --status sent - Get analytics for emails of interest with
analytics <id> - Compare open rates and click rates across newsletters
Managing the Draft Queue
- List drafts with
list --status draft - Get details on specific drafts with
get <id> - Update if needed with
update <id> --subject "..." - Schedule when ready with
schedule <id> <datetime>
Response Format
All commands output JSON. Example list response:
{
"total": 5,
"emails": [
{
"id": "abc123",
"subject": "Weekly Update",
"status": "sent",
"created": "2024-03-20T10:00:00Z",
"sent_at": "2024-03-20T14:00:00Z",
"scheduled_for": null,
"analytics": {
"recipients": 150,
"opens": 75,
"clicks": 12
}
}
]
}
Additional Resources
${CLAUDE_PLUGIN_ROOT}/skills/buttondown/references/api-types.md- Complete TypeScript type definitions${CLAUDE_PLUGIN_ROOT}/skills/buttondown/examples/workflow.md- Detailed workflow examples
Source
git clone https://github.com/The-Focus-AI/buttondown-skill/blob/main/skills/buttondown/SKILL.mdView on GitHub Overview
This skill provides Buttondown newsletter management via a TypeScript client. It enables creating drafts, scheduling sends, listing emails, and retrieving analytics using commands that map to Buttondown API endpoints.
How This Skill Works
Authenticate by exporting BUTTONDOWN_API_KEY, then run the TSX-based client script at the specified path to issue commands like list, create, get, analytics, schedule, unschedule, update, and delete. Each command interacts with the Buttondown API to manage drafts, schedules, and performance data, returning structured JSON.
When to Use It
- Create a new email draft and save it for later editing.
- Schedule a newsletter for future delivery and confirm the time with the user.
- List emails filtered by status (draft, scheduled, sent) for quick review.
- Retrieve analytics for a specific email to measure opens, clicks, and unsubscribes.
- Update an existing draft's subject or body or delete a draft when needed.
Quick Start
- Step 1: Export your Buttondown API key to BUTTONDOWN_API_KEY.
- Step 2: Run the script with a command, e.g., npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/buttondown/scripts/buttondown.ts list.
- Step 3: Create, schedule, or analyze drafts using the corresponding subcommands (create, schedule, analytics, etc.).
Best Practices
- Always confirm draft content with the user before creating a new draft.
- Use status filtering (list --status ...) to focus on drafts, scheduled, or sent emails.
- Before scheduling, verify the ISO timestamp and local time equivalent with the user.
- When deleting, confirm with the user since deletion is permanent.
- Keep the BUTTONDOWN_API_KEY secure and rotate credentials as needed.
Example Use Cases
- Draft a Black Friday newsletter and save as a draft.
- List all emails with status scheduled to review upcoming sends.
- Get analytics for the most recent sent email to compare performance.
- Schedule a draft for tomorrow at 10:00 UTC using the schedule command.
- Update the subject line of a draft and save the changes.
