Kit (ConvertKit)
Read and write a Kit (formerly ConvertKit) account - subscribers and their custom fields, tags, forms and sequences, and broadcast reporting - keeping the opt-in process where Kit puts it.
Connect a Kit account with a v4 API key to work its audience end to end: find subscribers by address or state, create and update them, unsubscribe someone account-wide, read and apply tags (remembering that in Kit a tag is an automation trigger, not a label), subscribe people through a form so the account's own double opt-in and incentive emails actually run, start sequences, and read broadcasts with their delivery and engagement stats. Custom field values are keyed by the field's LABEL, which List custom fields shows alongside Kit's internal key. Counts are only returned when you ask for them, and rates come back as percentages rather than fractions. Creating or sending broadcasts is deliberately not offered.
Connect
| Credential field | Required | Where it comes from |
|---|---|---|
API key (API_KEY) | Yes | From Settings → Advanced → API in Kit - the API KEY, not the API Secret (that one is the legacy v3 credential and cannot authenticate v4). It carries the whole account's access, with no scopes to narrow. |
Tools
| Tool | Access | What it does |
|---|---|---|
Whoami (yekar.convertkit.whoami) | Read | The Kit account this connection's API key belongs to - name, plan and primary email address. Call this first to confirm which account is about to be written to; the plan matters, because broadcasts and sequences are plan-gated and refuse with a 403 rather than an explanation. |
List subscribers (yekar.convertkit.list-subscribers) | Read | A page of subscribers with their state and custom field values. Kit shows only ACTIVE subscribers unless you ask otherwise, so a missing address may simply have bounced or unsubscribed - pass state=all to see. total is only returned when you set includeTotal. |
Get subscriber (yekar.convertkit.get-subscriber) | Read | One subscriber by id, with their state and custom field values. Only active means Kit will mail them - inactive is a pending double opt-in, and bounced/complained/cancelled are outcomes Kit recorded and will not reverse. |
Create or update subscriber (yekar.convertkit.create-subscriber) | Write | Add someone to the Kit account, or update them if the address is already there. Repeating the identical call converges rather than creating a second subscriber. It bypasses forms entirely - no confirmation email is sent and no opt-in is recorded - so use Add subscriber to form when the account's double opt-in should run. |
Update subscriber (yekar.convertkit.update-subscriber) | Write | Update an existing subscriber's name, address or custom field values. State is deliberately not settable here - to stop mailing someone use Unsubscribe subscriber, and the bounced/complained states are Kit's own findings rather than something an integration asserts. |
Unsubscribe subscriber (yekar.convertkit.unsubscribe-subscriber) | Write | Stop mailing a subscriber account-wide. This is the right tool when the intent is 'stop emailing this person' - removing a tag or taking them out of a sequence leaves them mailable everywhere else. Their record is kept; only the mailable state changes. |
List tags (yekar.convertkit.list-tags) | Read | The tags on the account with their ids. Tagging a subscriber takes the tag's ID, so this read comes first. Kit tags are also what most automations trigger on, which is why adding one is never a purely cosmetic act. |
Create tag (yekar.convertkit.create-tag) | Write | Create a new tag on the account. Kit refuses an exact duplicate name, but nothing stops 'Customers' and 'customer' coexisting - read List tags first, because automations key off tags and a near-duplicate silently splits an audience. |
Tag subscriber (yekar.convertkit.tag-subscriber) | Write | Put a tag on a subscriber. In Kit a tag is an automation trigger, not just a label: adding one can start a sequence and send email immediately. Use List tags to see what exists, and check the automation wired to a tag before applying it in bulk. |
Remove subscriber tag (yekar.convertkit.remove-subscriber-tag) | Write | Take a tag off a subscriber. The tag stays on the account. This is not an unsubscribe, and it does not stop a sequence that the tag has already triggered. |
List subscribers with a tag (yekar.convertkit.list-tag-subscribers) | Read | A page of the subscribers carrying one tag. Set includeTotal to have Kit count the whole tagged audience - otherwise total comes back null, meaning unknown rather than zero. |
List forms (yekar.convertkit.list-forms) | Read | The forms (and landing pages) on the account. A form is where Kit's opt-in process lives - its double opt-in, incentive email and confirmation all belong to the form, not to the subscriber record - so this is the read that comes before Add subscriber to form. |
Add subscriber to form (yekar.convertkit.add-subscriber-to-form) | Write | Subscribe someone through a form, running that form's own opt-in process - including double opt-in and any incentive email. This is the tool to use when the account's opt-in flow should happen; Create or update subscriber writes the record directly and sends nothing. |
List sequences (yekar.convertkit.list-sequences) | Read | The email sequences on the account. hold true means the sequence is paused - subscribers added to it wait rather than receiving anything, which is the difference between 'nothing happened' and 'it is queued'. |
Add subscriber to sequence (yekar.convertkit.add-subscriber-to-sequence) | Write | Start an email sequence for someone. The sequence begins immediately on its own schedule and will send email - there is no dry run, and this integration cannot take them back out. Check List sequences for whether the sequence is paused before assuming nothing will go out. |
List broadcasts (yekar.convertkit.list-broadcasts) | Read | The broadcasts (one-off emails) on the account. sendAt null means it is still a draft and nothing is scheduled; a set sendAt means Kit will send it at that moment with no further call. |
Get broadcast (yekar.convertkit.get-broadcast) | Read | One broadcast with its subject, preview text, schedule and body. Long bodies are cut to fit the prompt budget and the response flags it - reading a broadcast never changes it. |
Get broadcast stats (yekar.convertkit.get-broadcast-stats) | Read | Performance of a sent broadcast: recipients, opens, clicks and unsubscribes. Kit reports open and click rates as PERCENTAGES already (42.0 means 42%) - unlike most email APIs, which send fractions - so do not scale them again. progressPercent below 100 means the send is still going and every number is provisional. |
List custom fields (yekar.convertkit.list-custom-fields) | Read | The custom fields defined on the account. Note the two names each field has: key is Kit's internal identifier, and label is what a subscriber's fields map is keyed by. Writes use the LABEL - using the key silently stores nothing. |
Create custom field (yekar.convertkit.create-custom-field) | Write | Add a custom field to the account. Kit derives the internal key from the label you give, and subscriber writes address the value by the LABEL. Read List custom fields first: a second field with a near-identical label splits the data with no warning. |
Notes
- In Kit, go to Settings → Advanced → API.
- Copy the API KEY - the value used by the v4 API. The API SECRET on the same screen belongs to the legacy v3 API and will not work here.
- Paste it here as the credential. A Kit key carries the whole account's access; there are no per-key scopes, so treat it as a full-account credential.
- Call Whoami to confirm which Kit account and plan the key resolves to - broadcasts and sequences are plan-gated and refuse with a 403 that does not explain itself.
- Add one credential per Kit account.