Create and launch a campaign
A new campaign sends nothing until it is launched, and launch refuses until the campaign is ready. Ready comes a few minutes after you start the campaign, once its first leads pass their checks.
Before you start
- REST:
export KENSO_API_KEY=<your key>andexport KENSO_WORKSPACE_ID=<your workspace id>(see Authentication and Workspaces). The examples read ids withjq. kenso:npm i -g kenso,printf '%s' "$KENSO_API_KEY" | kenso auth login --with-key, thenkenso workspace use <your workspace id>. A command prints the response'sdatawithout the envelope, and a list prints one JSON row per line (CLI guide).- MCP: connect
https://mcp.ken.so/mcp(setup). Each tool takes the workspace id asclient_idand returns the same body as the REST call. - Each step keeps the ids the next steps need in shell variables (
$CAMPAIGN_ID). The MCP examples show the same ids as numbers.
The path
Create, write the sequence, add contacts, start with POST /v1/campaigns/{campaignId}/resume, wait for GET /v1/campaigns/{campaignId}/launch-readiness to say canLaunch, then launch. The order matters: starting needs contacts, a contact limit and copy, and launch needs a started campaign whose status reached ready.
PUT /v1/campaigns/{campaignId}/inboxesis not a step: create already gives the campaign every sendable inbox in the workspace. Use it to narrow that set, or to add inboxes you connect later.POST /v1/contact-importsruns a background import of a file. For leads your code holds,contacts.createanswers at once.autoLaunchWhenReadyonPATCH /v1/campaigns/{campaignId}launches by itself once ready, but a refused launch never reaches you. This recipe launches explicitly.POST /v1/campaigns/{campaignId}/restartis recovery for a stalled or failed campaign.
1. Create the campaign
POST /v1/campaigns Send a name and a contactLimit, the most leads it will email: starting fails without one. With no schedule, it sends Monday to Friday, 10:00 to 18:00 America/New_York. It starts as a draft.
CAMPAIGN_ID=$(curl -sS -X POST "https://api.ken.so/v1/campaigns" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Q1 RevOps leaders",
"contactLimit": 200
}' | jq -r '.data.id')CAMPAIGN_ID=$(kenso campaigns create --name "Q1 RevOps leaders" --contact-limit 200 | jq -r '.id')
campaigns({
"operation": "create",
"name": "Q1 RevOps leaders",
"contact_limit": 200,
"client_id": 4107
})Keeps data.id as $CAMPAIGN_ID.
2. Write the emails
PUT /v1/campaigns/{campaignId}/email-sequence Replace the sequence with your steps. {firstName} and {firstName|there} fill from the contact. {{...}} is an AI variable and needs a prompt, or starting fails. A later step with an empty subject goes as a reply in the same thread.
curl -sS -X PUT "https://api.ken.so/v1/campaigns/$CAMPAIGN_ID/email-sequence" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"steps": [
{
"stepOrder": 1,
"subject": "Quick question, {firstName}",
"body": "Hi {firstName|there},\n\nSaw {company} is growing its SDR team. Worth a look at how teams like yours book meetings from cold email?",
"waitDays": 0
},
{
"stepOrder": 2,
"subject": "",
"body": "Following up on my last note, {firstName}.",
"waitDays": 3
}
]
}'cat > body.json <<'JSON'
{
"steps": [
{
"stepOrder": 1,
"subject": "Quick question, {firstName}",
"body": "Hi {firstName|there},\n\nSaw {company} is growing its SDR team. Worth a look at how teams like yours book meetings from cold email?",
"waitDays": 0
},
{
"stepOrder": 2,
"subject": "",
"body": "Following up on my last note, {firstName}.",
"waitDays": 3
}
]
}
JSON
kenso email-sequences replace --campaign-id "$CAMPAIGN_ID" --data @body.jsonemail_sequences({
"operation": "replace",
"campaign_id": 812,
"steps": [
{
"step_order": 1,
"subject": "Quick question, {firstName}",
"body": "Hi {firstName|there}, ...",
"wait_days": 0
},
{
"step_order": 2,
"subject": "",
"body": "Following up on my last note, {firstName}.",
"wait_days": 3
}
],
"client_id": 4107
})3. Add contacts
POST /v1/campaigns/{campaignId}/contacts Add the leads as in Add leads from your app, at most 1,000 rows per call, and read each row's status.
curl -sS -X POST "https://api.ken.so/v1/campaigns/$CAMPAIGN_ID/contacts" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"contacts": [
{
"email": "[email protected]",
"firstName": "Dana",
"lastName": "Reyes",
"title": "VP Revenue Operations",
"companyName": "Northwind Analytics"
},
{
"email": "[email protected]",
"firstName": "Sam",
"lastName": "Ortiz",
"companyName": "Contoso"
}
]
}'cat > body.json <<'JSON'
{
"contacts": [
{
"email": "[email protected]",
"firstName": "Dana",
"lastName": "Reyes",
"title": "VP Revenue Operations",
"companyName": "Northwind Analytics"
},
{
"email": "[email protected]",
"firstName": "Sam",
"lastName": "Ortiz",
"companyName": "Contoso"
}
]
}
JSON
kenso contacts create --campaign-id "$CAMPAIGN_ID" --data @body.jsoncontacts({
"operation": "create",
"campaign_id": 812,
"contacts": [
{
"email": "[email protected]",
"first_name": "Dana",
"last_name": "Reyes",
"company_name": "Northwind Analytics"
},
{
"email": "[email protected]",
"first_name": "Sam",
"last_name": "Ortiz",
"company_name": "Contoso"
}
],
"client_id": 4107
})4. Start the campaign
POST /v1/campaigns/{campaignId}/resume Resume starts a draft's processing: email checks, then qualification and personalization if the campaign has them. The campaign turns building. A missing name, contact, contact limit, schedule or step copy answers 400 with validation_failed and the list of what to fix.
curl -sS -X POST "https://api.ken.so/v1/campaigns/$CAMPAIGN_ID/resume" \ -H "Authorization: Bearer $KENSO_API_KEY" \ -H "Ken-Version: 2026-11-02" \ -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
kenso campaigns resume --campaign-id "$CAMPAIGN_ID"
campaigns({
"operation": "resume",
"campaign_id": 812,
"client_id": 4107
})5. Wait until it can launch
GET /v1/campaigns/{campaignId}/launch-readiness Call this every minute until data.canLaunch is true. Expect minutes: the campaign turns ready once a first lead has a verified email. data.reasons lists what still blocks, by code (not_ready, no_ken_sendable_inboxes, invalid_schedule, free_plan_sending_needs_plan and more).
curl -sS -X GET "https://api.ken.so/v1/campaigns/$CAMPAIGN_ID/launch-readiness" \ -H "Authorization: Bearer $KENSO_API_KEY" \ -H "Ken-Version: 2026-11-02" \ -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
kenso campaigns get-launch-readiness --campaign-id "$CAMPAIGN_ID"
campaign_flow({
"operation": "get-launch-readiness",
"campaign_id": 812,
"client_id": 4107
})6. Launch
POST /v1/campaigns/{campaignId}/launch Launch queues the first sends and answers at once, with the campaign active. Calling it again on a sending campaign changes nothing. To stop sending later, POST /v1/campaigns/{campaignId}/pause.
curl -sS -X POST "https://api.ken.so/v1/campaigns/$CAMPAIGN_ID/launch" \ -H "Authorization: Bearer $KENSO_API_KEY" \ -H "Ken-Version: 2026-11-02" \ -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
kenso campaigns launch --campaign-id "$CAMPAIGN_ID"
campaigns({
"operation": "launch",
"campaign_id": 812,
"client_id": 4107
})validation_failedready yet, or (details[0].code no_sendable_inbox) no inbox in it can send.plan_limit_reachederror.refusal.code says which).free_plan_sending_needs_planapproval_required, acknowledgement_requiredGood to know
- Replacing the sequence overwrites it: steps you leave out are deleted.
- Starting, launching and pausing need the launch permission as well as edit access to campaigns.
- Inboxes you connect after creating the campaign are not in it: send
{"assignAllActive": true}toPUT /v1/campaigns/{campaignId}/inboxesto add them. campaigns.createtakes noIdempotency-Key: a retried create makes a second campaign, so check List campaigns before you retry.