beehiiv

1# Beehiiv
2 
3## Purpose
4Read and write the user's beehiiv newsletters: list publications, list subscribers, list posts with stats, add subscribers. Use when the user mentions beehiiv or their newsletter.
5 
6## Tooling
7All commands go through `bin/beehiiv.py`:
8 
9```bash
10bin/beehiiv.py auth                                     # verify the API key
11bin/beehiiv.py publications                             # list publications
12bin/beehiiv.py subscriptions --pub pub_abc123 --limit 25  # list subscribers
13bin/beehiiv.py posts --pub pub_abc123 --limit 25        # list posts with stats
14bin/beehiiv.py subscribe --pub pub_abc123 --email "them@example.com"  # add a subscriber
15```
16 
17Most endpoints need a publication ID (`pub_...`); use `publications` to resolve it first.
18 
19## Auth
20- Provider id: `beehiiv` (credential is collected as `custom.beehiiv`)
21- Collection: API key via the secure credential flow (`credentials.request_api_access`); created in beehiiv under Settings > Workspace Settings > API (requires Owner or Admin role, Scale plan or higher)
22- Allowed hosts: `api.beehiiv.com`
23- Status check: `bin/beehiiv.py auth` (must return `"ok": true`)
24 
25## Operating Rules
261. `subscribe` is a write: confirm the email address and publication with the user before adding, unless standing permission exists.
272. Reading (publications, subscriptions, posts) needs no confirmation.
283. beehiiv rate-limits to 180 requests per minute per organization; back off on 429s.
29…