| name | kit |
| description | Fetch Kit (ConvertKit) broadcasts for writing context, and create or update broadcast drafts via the Kit v4 API. Use when asked to download newsletters for style reference, or to draft, stage, or edit a Kit broadcast. |
Kit Broadcasts Fetcher
Use the kit-broadcasts CLI to fetch newsletters from Kit (ConvertKit). Useful for retrieving past newsletter content as context for writing new newsletters in a consistent style.
Usage
kit-broadcasts
kit-broadcasts -o broadcasts.json
kit-broadcasts -v -o broadcasts.json
kit-broadcasts --full -o broadcasts.json
kit-broadcasts --api-key "your-key"
Arguments
| Argument | Short | Description |
|---|
--output | -o | Output file path (default: stdout) |
--api-key | -k | Kit API key (or set KIT_API_KEY env var) |
--full | | Include all fields, not just subject/preview/content |
--verbose | -v | Show progress info |
Output Format
Default (simplified):
[
{
"id": 123,
"subject": "Newsletter Subject",
"preview_text": "Preview text...",
"content": "<html>...</html>",
"created_at": "2024-01-15T10:00:00Z",
"send_at": "2024-01-15T12:00:00Z",
"stats": {"open_rate": 45.2, "click_rate": 3.1}
}
]
Requirements
-
Install the hamel package:
pip install hamel
-
Set environment variable:
export KIT_API_KEY="your-v4-api-key"
Get your V4 API key from Kit Developer Settings. The API key is tied to your Kit account - no separate account ID needed.
Examples
Fetch newsletters as writing context:
kit-broadcasts -o newsletters.json
Get recent newsletters for style reference:
kit-broadcasts | jq '.[0:5]'
Analyze newsletter performance:
kit-broadcasts -o newsletters.json
Summarize with AI:
kit-broadcasts -o /tmp/newsletters.json && ai-gem "List the main topics covered in these newsletters" /tmp/newsletters.json
(Don't pipe kit-broadcasts into ai-gem with a prompt argument — ai-gem only reads stdin when no prompt argument is given.)
Creating / updating broadcasts (Kit v4 REST)
The kit-broadcasts CLI is fetch-only. To create or edit a broadcast, call the Kit v4 REST API directly. Auth uses the same v4 key, sent as a header: X-Kit-Api-Key: $KIT_API_KEY.
Create a draft: POST, omit send_at/published_at, and set public: false.
curl -s -X POST https://api.kit.com/v4/broadcasts \
-H "X-Kit-Api-Key: $KIT_API_KEY" -H "Content-Type: application/json" \
-d '{"subject":"...","content":"<p>...</p>","preview_text":"...","public":false}'
Update an existing broadcast's content, subject, or preview_text:
curl -s -X PUT https://api.kit.com/v4/broadcasts/<id> \
-H "X-Kit-Api-Key: $KIT_API_KEY" -H "Content-Type: application/json" \
-d '{"content":"<p>updated</p>"}'
Critical: once a broadcast is scheduled (send_at set), PUT is locked and editing content returns HTTP 422 Unprocessable Entity. Unschedule it in the Kit UI before editing, or don't schedule until the content is final.
