@kentcdodds/kit

@kentcdodds/kit

Intent

Kit.com API v4 helpers for subscriber/waitlist signups (tags, forms, segments), broadcast drafts, sequences, and HTML that matches Kent's newsletter conventions. Transport is a thin OpenAPI-scaffolded client (headerSecret kitApiKey → X-Kit-Api-Key); domain helpers keep subscriber/broadcast/sequence shaping and HTML builders.

Agent quickstart

Broadcast helpers are draft-only: nothing sends, schedules, or publishes a broadcast — a human sends drafts from the Kit UI via the returned editUrl. Subscriber helpers do write live audience data (subscribeAndTag subscribes real email addresses; an active-state sequence emails its subscribers), so use test addresses when experimenting. Destructive exports: deleteBroadcast, unsubscribeSubscriber, untagSubscriber.

Waitlist/signup flow — one call subscribes and tags (creating the tag on first use):

import { subscribeAndTag } from 'kody:@kentcdodds/kit'

export default async function main() {
	return await subscribeAndTag({
		email_address: 'person@example.com',
		first_name: 'Ada',
		tagName: 'waitlist::kody',
	})
	// => { subscriber: { id, email_address, state: 'active', ... }, tag: { id, name } }
}

First call — create a draft (works as-is, no template id needed; the account default template is used):

import { createBroadcastDraft } from 'kody:@kentcdodds/kit'

export default async function main() {
	return await createBroadcastDraft({
		subject: 'Product Engineering Workshop',
		content: '<p>Workshop details go here.</p>',
	})
	// => { id, subject, status: 'draft', editUrl: 'https://app.kit.com/campaigns/<id>/draft', ... }
}

Read recent broadcasts (always pass maxItems — without it, the helper paginates the entire broadcast history and can blow the execute timeout):

import { listBroadcasts } from 'kody:@kentcdodds/kit'

export default async function main() {
	return await listBroadcasts({ maxItems: 10 })
}

To verify credentials/host approval without touching any data, run the read-only smoke test:

import smokeTest from 'kody:@kentcdodds/kit/smoke-test'

export default async function main() {
	return await smokeTest()
	// => { ok: true, account: { name: '...' }, broadcastCount: 5, sampleBroadcast: {...} }
}

Templates

email_template_id is optional. Omit it and Kit applies the account default template ("Text Only"). Known ids are exported as KIT_TEMPLATES:

• KIT_TEMPLATES.textOnly (684651) — account default, plain text-style emails.
• KIT_TEMPLATES.epePodcast (5215129) — Epic Programming Podcast episode emails.

Verify ids in the Kit UI before relying on new ones.

When To Use

• Subscribe people to the audience (waitlists, signups) and manage tags, forms, and segments.
• Create sequences (welcome/thank-you emails) and enroll subscribers into them.
• Create or update Kit broadcast drafts for workshops, podcasts, or announcements.
• Sync sequence email content from repo markdown into Kit.
• Compose email HTML with Liquid greetings, linked images, and list blocks.
• List or fetch existing broadcasts, sequences, and account/broadcast stats for review workflows.

Welcome sequence flow

Send an automatic email when someone joins (sequences send immediately once active when delay_value is 0):

import { createSequence, createSequenceEmail, addSubscriberToSequence } from 'kody:@kentcdodds/kit'

const sequence = await createSequence({
	name: 'Kody Waitlist Welcome',
	email_address: 'hello@kentcdodds.com', // must be a verified sending address
	active: true,
})
await createSequenceEmail(sequence.id, {
	subject: 'Thanks for your interest!',
	content: '<p>What are you hoping to use Kody for?</p>',
	published: true,
})
await addSubscriberToSequence(sequence.id, 'person@example.com')

For production app integrations calling Kit directly (not through Kody), the raw API contract is: POST /v4/subscribers (upsert by email) then POST /v4/tags/{tag_id}/subscribers with header X-Kit-Api-Key. Note Kit v4 does not accept Authorization: Bearer — only the X-Kit-Api-Key header.

Required setup

• Kit (ConvertKit) v4 API key saved as the kitApiKey secret (user scope).
• Host approval for api.kit.com stays in the account security UI.
• No OAuth integrations or user values are required.

Troubleshooting

• Secret "kitApiKey" is not allowed for package "<caller>" — you imported this package from another package (e.g. kody:@kentcdodds/kit inside a package job). Cross-package calls run under the calling package's identity, so kitApiKey must be approved for that calling package too. Ask the user to approve it at https://heykody.dev/account/secrets (edit kitApiKey → allowed packages), then retry. Ad hoc execute calls are unaffected.
• Host approval errors for api.kit.com — follow the approval path in the error message; approval lives in the account security UI, not in this package.
• API failures throw KitApiError with status, body, method, and path — log those fields before retrying.

OpenAPI surface

Scaffolded from https://developers.kit.com/api-reference/v4.json (auth kind headerSecret):

• Account: get_v4_account, get_v4_account_email_stats, get_v4_account_growth_stats
• Broadcasts: get_v4_broadcasts, post_v4_broadcasts, get_v4_broadcasts_id, put_v4_broadcasts_id, delete_v4_broadcasts_id, get_v4_broadcasts_broadcast_id_stats, get_v4_broadcasts_stats
• Subscribers: get_v4_subscribers, post_v4_subscribers, get_v4_subscribers_id, put_v4_subscribers_id, post_v4_subscribers_id_unsubscribe, get_v4_subscribers_subscriber_id_tags
• Tags: get_v4_tags, post_v4_tags, get_v4_tags_tag_id_subscribers, post_v4_tags_tag_id_subscribers, delete_v4_tags_tag_id_subscribers_id, delete_v4_bulk_tags
• Forms & segments: get_v4_forms, post_v4_forms_form_id_subscribers, get_v4_segments
• Sequences: get_v4_sequences, post_v4_sequences, get_v4_sequences_id, get_v4_sequences_sequence_id_emails, post_v4_sequences_sequence_id_emails, get_v4_sequences_sequence_id_emails_id, put_v4_sequences_sequence_id_emails_id, post_v4_sequences_sequence_id_subscribers

Exports

• ./ (default createBroadcastDraft) — domain helpers: subscriber/tag/form/segment, account/broadcast/sequence wrappers, HTML builders, and summaries.
• ./smoke-test — read-only account + broadcast list smoke.

Breaking in v2: removed hand-rolled kitHeaders / kitFetch / kitListAll. Prefer named helpers or the scaffold ops in src/openapi-client.js.

HTML builder example

import {
	createBroadcastDraft,
	buildLiquidGreeting,
	buildParagraph,
	joinEmailBlocks,
	KIT_TEMPLATES,
} from 'kody:@kentcdodds/kit'

const content = joinEmailBlocks([
	buildLiquidGreeting({ withName: 'Hey {{ subscriber.first_name }}', withoutName: 'Hey friend' }),
	buildParagraph('Workshop details go here.'),
])

await createBroadcastDraft({
	subject: 'Product Engineering Workshop',
	content,
	email_template_id: KIT_TEMPLATES.epePodcast,
})