> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [https://api.ken.so/v1/docs/openapi.json](https://api.ken.so/v1/docs/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-15.

# Create and launch a campaign

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

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>` and `export KENSO_WORKSPACE_ID=<your workspace id>` (see [Authentication](/docs/authentication) and [Workspaces](/docs/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](/cli)).
- MCP: connect `https://mcp.ken.so/mcp` ([setup](/mcp)). 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`](/docs/api/campaigns.md)

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**

```bash
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**

```bash
CAMPAIGN_ID=$(kenso campaigns create --name "Q1 RevOps leaders" --contact-limit 200 | jq -r '.id')
```

**MCP** (`campaigns`)

```text
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`](/docs/api/email-sequences.md)

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**

```bash
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**

```bash
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`)

```text
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`](/docs/api/contacts.md)

Add the leads as in [Add leads from your app](/docs/recipes/add-leads), at most 1,000 rows per call, and read each row's `status`.

**REST**

```bash
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": "dana.reyes@example.com",
      "firstName": "Dana",
      "lastName": "Reyes",
      "title": "VP Revenue Operations",
      "companyName": "Northwind Analytics"
    },
    {
      "email": "sam.ortiz@example.com",
      "firstName": "Sam",
      "lastName": "Ortiz",
      "companyName": "Contoso"
    }
  ]
}'
```

**kenso**

```bash
cat > body.json <<'JSON'
{
  "contacts": [
    {
      "email": "dana.reyes@example.com",
      "firstName": "Dana",
      "lastName": "Reyes",
      "title": "VP Revenue Operations",
      "companyName": "Northwind Analytics"
    },
    {
      "email": "sam.ortiz@example.com",
      "firstName": "Sam",
      "lastName": "Ortiz",
      "companyName": "Contoso"
    }
  ]
}
JSON
kenso contacts create --campaign-id "$CAMPAIGN_ID" --data @body.json
```

**MCP** (`contacts`)

```text
contacts({
  "operation": "create",
  "campaign_id": 812,
  "contacts": [
    {
      "email": "dana.reyes@example.com",
      "first_name": "Dana",
      "last_name": "Reyes",
      "company_name": "Northwind Analytics"
    },
    {
      "email": "sam.ortiz@example.com",
      "first_name": "Sam",
      "last_name": "Ortiz",
      "company_name": "Contoso"
    }
  ],
  "client_id": 4107
})
```

## 4. Start the campaign

[`POST /v1/campaigns/{campaignId}/resume`](/docs/api/campaigns.md)

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**

```bash
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**

```bash
kenso campaigns resume --campaign-id "$CAMPAIGN_ID"
```

**MCP** (`campaigns`)

```text
campaigns({
  "operation": "resume",
  "campaign_id": 812,
  "client_id": 4107
})
```

## 5. Wait until it can launch

[`GET /v1/campaigns/{campaignId}/launch-readiness`](/docs/api/campaigns.md)

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**

```bash
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**

```bash
kenso campaigns get-launch-readiness --campaign-id "$CAMPAIGN_ID"
```

**MCP** (`campaign_flow`)

```text
campaign_flow({
  "operation": "get-launch-readiness",
  "campaign_id": 812,
  "client_id": 4107
})
```

## 6. Launch

[`POST /v1/campaigns/{campaignId}/launch`](/docs/api/campaigns.md)

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**

```bash
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**

```bash
kenso campaigns launch --campaign-id "$CAMPAIGN_ID"
```

**MCP** (`campaigns`)

```text
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](/docs/api/campaigns#campaigns.list) before you retry.

## More recipes

- [Add leads from your app](/docs/recipes/add-leads.md)
- [Read and answer replies](/docs/recipes/answer-replies.md)
- [Receive webhooks](/docs/recipes/receive-webhooks.md)
- [API reference](/docs.md)
