buttondown

1# Buttondown
2 
3## Purpose
4Read and write the user's Buttondown newsletter: list subscribers, list emails (drafts and sent), add subscribers, create email drafts. Use when the user mentions Buttondown or their newsletter.
5 
6## Tooling
7All commands go through `bin/buttondown.py`:
8 
9```bash
10bin/buttondown.py auth                                      # verify the API key
11bin/buttondown.py subscribers --limit 25                    # list subscribers
12bin/buttondown.py subscriber-add --email "them@example.com" # add a subscriber
13bin/buttondown.py emails --limit 25                         # list emails
14bin/buttondown.py email-create --subject "Hi" --body "..."   # create a draft email
15bin/buttondown.py email-create --subject "Hi" --body "..." --send  # send to the list (confirm first)
16```
17 
18Writes (`subscriber-add`, `email-create`) also accept `--json` for extra provider fields.
19 
20## Auth
21- Provider id: `buttondown` (credential is collected as `custom.buttondown`)
22- Collection: API key via the secure credential flow (`credentials.request_api_access`); created in Buttondown under Settings > API
23- Allowed hosts: `api.buttondown.com`
24- Status check: `bin/buttondown.py auth` (must return `"ok": true`)
25 
26## Operating Rules
271. `email-create` defaults to a draft. `--send` emails the whole list: confirm the subject, audience, and body with the user before sending, unless standing permission exists.
282. `subscriber-add` is a write: confirm the email address with the user first.
29…