Managing Convertkit

ConvertKit Management Skill

Monitor and manage ConvertKit email marketing for creators.

MANDATORY: Discovery-First Pattern

Always discover account info and subscriber count before querying forms or sequences.

Phase 1: Discovery

#!/bin/bash
CK_API="https://api.convertkit.com/v3"
API_SECRET="${CONVERTKIT_API_SECRET}"

echo "=== Account Info ==="
curl -s "$CK_API/account?api_secret=$API_SECRET" | \
  jq -r '"Name: \(.name)\nPlan: \(.plan_name)\nSubscribers: \(.total_subscribers)"'

echo ""
echo "=== Forms ==="
curl -s "$CK_API/forms?api_secret=$API_SECRET" | \
  jq -r '.forms[] | "\(.name) | ID: \(.id) | Type: \(.type) | Subscribers: \(.total_subscriptions) | Created: \(.created_at)"'

echo ""
echo "=== Sequences ==="
curl -s "$CK_API/sequences?api_secret=$API_SECRET" | \
  jq -r '.courses[] | "\(.name) | ID: \(.id) | Subscribers: \(.total_subscriptions) | Created: \(.created_at)"'

echo ""
echo "=== Tags ==="
curl -s "$CK_API/tags?api_secret=$API_SECRET" | \
  jq -r '.tags[] | "\(.name) | ID: \(.id) | Created: \(.created_at)"' | head -20

Phase 1 outputs: Account plan, forms, sequences, tags

Phase 2: Analysis

#!/bin/bash
echo "=== Subscriber Growth (recent) ==="
curl -s "$CK_API/subscribers?api_secret=$API_SECRET&sort_order=desc&per_page=5" | \
  jq -r '.subscribers[] | "\(.email_address) | State: \(.state) | Created: \(.created_at)"'

echo ""
echo "=== Subscriber States ==="
total=$(curl -s "$CK_API/subscribers?api_secret=$API_SECRET" | jq '.total_subscribers')
echo "Total subscribers: $total"

echo ""
echo "=== Broadcasts (recent) ==="
curl -s "$CK_API/broadcasts?api_secret=$API_SECRET" | \
  jq -r '.broadcasts[:10] | .[] | "\(.subject) | Status: \(.status) | Sent: \(.sent_at // "not sent")"'

echo ""
echo "=== Automations ==="
curl -s "$CK_API/automations?api_secret=$API_SECRET" | \
  jq -r '.automations[] | "\(.name) | Status: \(.status) | Subscribers: \(.subscriber_count)"' | head -10

echo ""
echo "=== Form Conversion Rates ==="
curl -s "$CK_API/forms?api_secret=$API_SECRET" | \
  jq -r '.forms[] | "\(.name): \(.total_subscriptions) subs from \(.total_unique_visitors // "N/A") visitors"'

Output Format

CONVERTKIT STATUS
=================
Account: {name} ({plan})
Total Subscribers: {count}
Forms: {count} | Sequences: {count} | Tags: {count}
Recent Broadcasts: {count}
Active Automations: {count}
Top Form: {name} ({conversions} conversions)
Issues: {list_of_warnings}

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• API key vs API secret: Most endpoints need api_secret, not api_key
• Subscriber states: active, cancelled, bounced, complained — filter accordingly
• Rate limits: 120 requests/minute — batch subscriber queries
• Sequences vs Automations: Sequences are linear email series; automations are rule-based workflows