Convertkit Automation

1---
2name: convertkit-automation
3description: "Automate ConvertKit (Kit) tasks via Rube MCP (Composio): manage subscribers, tags, broadcasts, and broadcast stats. Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# ConvertKit (Kit) Automation via Rube MCP
9 
10Automate ConvertKit (now known as Kit) email marketing operations through Composio's Kit toolkit via Rube MCP.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active Kit connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `kit`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `kit`
253. If connection is not ACTIVE, follow the returned auth link to complete Kit authentication
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. List and Search Subscribers
31 
32**When to use**: User wants to browse, search, or filter email subscribers
33 
34**Tool sequence**:
351. `KIT_LIST_SUBSCRIBERS` - List subscribers with filters and pagination [Required]
36 
37**Key parameters**:
38- `status`: Filter by status ('active' or 'inactive')
39- `email_address`: Exact email to search for
40- `created_after`/`created_before`: Date range filter (YYYY-MM-DD)
41- `updated_after`/`updated_before`: Date range filter (YYYY-MM-DD)
42- `sort_field`: Sort by 'id', 'cancelled_at', or 'updated_at'
43- `sort_order`: 'asc' or 'desc'
44- `per_page`: Results per page (min 1)
45- `after`/`before`: Cursor strings for pagination
46- `include_total_count`: Set to 'true' to get total subscriber count
47 
48**Pitfalls**:
49- If `sort_field` is 'cancelled_at', the `status` must be set to 'cancelled'
50- Date filters use YYYY-MM-DD format (no time component)
51- `email_address` is an exact match; partial email search is not supported
52- Pagination uses cursor-based approach with `after`/`before` cursor strings
53- `include_total_count` is a string 'true', not a boolean
54 
55### 2. Manage Subscriber Tags
56 
57**When to use**: User wants to tag subscribers for segmentation
58 
59**Tool sequence**:
601. `KIT_LIST_SUBSCRIBERS` - Find subscriber ID by email [Prerequisite]
612. `KIT_TAG_SUBSCRIBER` - Associate a subscriber with a tag [Required]
623. `KIT_LIST_TAG_SUBSCRIBERS` - List subscribers for a specific tag [Optional]
63 
64**Key parameters for tagging**:
65- `tag_id`: Numeric tag ID (required)
66- `subscriber_id`: Numeric subscriber ID (required)
67 
68**Pitfalls**:
69- Both `tag_id` and `subscriber_id` must be positive integers
70- Tag IDs must reference existing tags; tags are created via the Kit web UI
71- Tagging an already-tagged subscriber is idempotent (no error)
72- Subscriber IDs are returned from LIST_SUBSCRIBERS; use `email_address` filter to find specific subscribers
73 
74### 3. Unsubscribe a Subscriber
75 
76**When to use**: User wants to unsubscribe a subscriber from all communications
77 
78**Tool sequence**:
791. `KIT_LIST_SUBSCRIBERS` - Find subscriber ID [Prerequisite]
802. `KIT_DELETE_SUBSCRIBER` - Unsubscribe the subscriber [Required]
81 
82**Key parameters**:
83- `id`: Subscriber ID (required, positive integer)
84 
85**Pitfalls**:
86- This permanently unsubscribes the subscriber from ALL email communications
87- The subscriber's historical data is retained but they will no longer receive emails
88- Operation is idempotent; unsubscribing an already-unsubscribed subscriber succeeds without error
89- Returns empty response (HTTP 204 No Content) on success
90- Subscriber ID must exist; non-existent IDs return 404
91 
92### 4. List and View Broadcasts
93 
94**When to use**: User wants to browse email broadcasts or get details of a specific one
95 
96**Tool sequence**:
971. `KIT_LIST_BROADCASTS` - List all broadcasts with pagination [Required]
982. `KIT_GET_BROADCAST` - Get detailed information for a specific broadcast [Optional]
993. `KIT_GET_BROADCAST_STATS` - Get performance statistics for a broadcast [Optional]
100 
101**Key parameters for listing**:
102- `per_page`: Results per page (1-500)
103- `after`/`before`: Cursor strings for pagination
104- `include_total_count`: Set to 'true' for total count
105 
106**Key parameters for details**:
107- `id`: Broadcast ID (required, positive integer)
108 
109**Pitfalls**:
110- `per_page` max is 500 for broadcasts
111- Broadcast stats are only available for sent broadcasts
112- Draft broadcasts will not have stats
113- Broadcast IDs are numeric integers
114 
115### 5. Delete a Broadcast
116 
117**When to use**: User wants to permanently remove a broadcast
118 
119**Tool sequence**:
1201. `KIT_LIST_BROADCASTS` - Find the broadcast to delete [Prerequisite]
1212. `KIT_GET_BROADCAST` - Verify it is the correct broadcast [Optional]
1223. `KIT_DELETE_BROADCAST` - Permanently delete the broadcast [Required]
123 
124**Key parameters**:
125- `id`: Broadcast ID (required)
126 
127**Pitfalls**:
128- Deletion is permanent and cannot be undone
129- Deleting a sent broadcast removes it but does not unsend the emails
130- Confirm the broadcast ID before deleting
131 
132## Common Patterns
133 
134### Subscriber Lookup by Email
135 
136```
1371. Call KIT_LIST_SUBSCRIBERS with email_address='user@example.com'
1382. Extract subscriber ID from the response
1393. Use ID for tagging, unsubscribing, or other operations
140```
141 
142### Pagination
143 
144Kit uses cursor-based pagination:
145- Check response for `after` cursor value
146- Pass cursor as `after` parameter in next request
147- Continue until no more cursor is returned
148- Use `include_total_count: 'true'` to track progress
149 
150### Tag-Based Segmentation
151 
152```
1531. Create tags in Kit web UI
1542. Use KIT_TAG_SUBSCRIBER to assign tags to subscribers
1553. Use KIT_LIST_TAG_SUBSCRIBERS to view subscribers per tag
156```
157 
158## Known Pitfalls
159 
160**ID Formats**:
161- Subscriber IDs: positive integers (e.g., 3887204736)
162- Tag IDs: positive integers
163- Broadcast IDs: positive integers
164- All IDs are numeric, not strings
165 
166**Status Values**:
167- Subscriber statuses: 'active', 'inactive', 'cancelled'
168- Some operations are restricted by status (e.g., sorting by cancelled_at requires status='cancelled')
169 
170**String vs Boolean Parameters**:
171- `include_total_count` is a string 'true', not a boolean true
172- `sort_order` is a string enum: 'asc' or 'desc'
173 
174**Rate Limits**:
175- Kit API has per-account rate limits
176- Implement backoff on 429 responses
177- Bulk operations should be paced appropriately
178 
179**Response Parsing**:
180- Response data may be nested under `data` or `data.data`
181- Parse defensively with fallback patterns
182- Cursor values are opaque strings; use exactly as returned
183 
184## Quick Reference
185 
186| Task | Tool Slug | Key Params |
187|------|-----------|------------|
188| List subscribers | KIT_LIST_SUBSCRIBERS | status, email_address, per_page |
189| Tag subscriber | KIT_TAG_SUBSCRIBER | tag_id, subscriber_id |
190| List tag subscribers | KIT_LIST_TAG_SUBSCRIBERS | tag_id |
191| Unsubscribe | KIT_DELETE_SUBSCRIBER | id |
192| List broadcasts | KIT_LIST_BROADCASTS | per_page, after |
193| Get broadcast | KIT_GET_BROADCAST | id |
194| Get broadcast stats | KIT_GET_BROADCAST_STATS | id |
195| Delete broadcast | KIT_DELETE_BROADCAST | id |
196