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

# Fetch all broadcasts to stdout (JSON format)
kit-broadcasts

# Save to file
kit-broadcasts -o broadcasts.json

# Verbose mode shows progress
kit-broadcasts -v -o broadcasts.json

# Include all fields (not just simplified data)
kit-broadcasts --full -o broadcasts.json

# Use specific API key
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
# Use the content field as examples for writing new newsletters

Get recent newsletters for style reference:

kit-broadcasts | jq '.[0:5]'  # First 5 (most recent) newsletters

Analyze newsletter performance:

kit-broadcasts -o newsletters.json
# Check stats.open_rate and stats.click_rate to identify best-performing content

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.