Kenso

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.

Ken-Version: 2026-11-02
Markdown

Before you start

  • REST: export KENSO_API_KEY=<your key> and export KENSO_WORKSPACE_ID=<your workspace id> (see Authentication and Workspaces). The examples read ids with jq.
  • kenso: npm i -g kenso, printf '%s' "$KENSO_API_KEY" | kenso auth login --with-key, then kenso workspace use <your workspace id>. A command prints the response's data without 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 as client_id and 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}/inboxes is 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-imports runs a background import of a file. For leads your code holds, contacts.create answers at once.
  • autoLaunchWhenReady on PATCH /v1/campaigns/{campaignId} launches by itself once ready, but a refused launch never reaches you. This recipe launches explicitly.
  • POST /v1/campaigns/{campaignId}/restart is 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.

REST
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')
kenso
CAMPAIGN_ID=$(kenso campaigns create --name "Q1 RevOps leaders" --contact-limit 200 | jq -r '.id')
MCP: campaigns
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.

REST
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
    }
  ]
}'
kenso
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.json
MCP: email_sequences
email_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.

REST
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"
    }
  ]
}'
kenso
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.json
MCP: contacts
contacts({
  "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.

REST
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
kenso campaigns resume --campaign-id "$CAMPAIGN_ID"
MCP: campaigns
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).

REST
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
kenso campaigns get-launch-readiness --campaign-id "$CAMPAIGN_ID"
MCP: campaign_flow
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.

REST
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
kenso campaigns launch --campaign-id "$CAMPAIGN_ID"
MCP: campaigns
campaigns({
  "operation": "launch",
  "campaign_id": 812,
  "client_id": 4107
})
Status
`code`
Why launch refused
400
validation_failed
The campaign is not ready yet, or (details[0].code no_sendable_inbox) no inbox in it can send.
402
plan_limit_reached
The plan's included sends are used up and the workspace has no credits (error.refusal.code says which).
402
free_plan_sending_needs_plan
A free workspace cannot send. Pick a plan.
409
approval_required, acknowledgement_required
A client approval or a compliance acknowledgement is still open.

Good 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} to PUT /v1/campaigns/{campaignId}/inboxes to add them.
  • campaigns.create takes no Idempotency-Key: a retried create makes a second campaign, so check List campaigns before you retry.

More recipes and guides