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

# Email sequences: Replace a campaign's email sequence

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

One endpoint of [Email sequences](/docs/api/email-sequences.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Replace a campaign's email sequence

`PUT /v1/campaigns/{campaignId}/email-sequence` - operationId `email-sequences.replace`

| Permission | Rate limit |
| --- | --- |
| Campaigns edit | 4,800 requests a minute per API key |

Replaces the campaign's own email sequence with the steps you send, and creates it when the campaign has none.
Send the `modifiedAt` from your last read as `expectedModifiedAt`, so you do not overwrite an edit made since.

`steps` is required and is the whole list. A step with the `id` of an existing step updates that step, and a
step without an `id` is new. Kenso deletes the existing steps you leave out and drops a step whose `id` is not on
this sequence. An empty list deletes every step.

`steps` holds at most 30 entries. `stepOrder` starts at 1, each `stepOrder` and `variant` pair appears once,
and each `stepOrder` needs at least one active variant. Variants of one step must differ in subject or body.
Each `{variable}` must be one that `GET /v1/sequence-variables` lists for the campaign.

Kenso runs every link through its URL reputation check and every step through its content policy.
`contentWarnings` in the response lists the content policy findings. When the workspace needs client approval
of copy, the change goes to the client, and Kenso pauses a sending campaign until the client approves it.

Errors:

- `400 validation_failed`: a step breaks a rule above.
- `400 validation_failed` with `link_reputation_blocked` details: a link failed the URL reputation check. Each detail has `field` (`steps[i].subject` or `steps[i].body`), `rule`, `url`, `stepOrder` and, for a saved step, `stepId`.
- `404 not_found`: the campaign does not exist in this workspace.
- `409 conflict` with a `stale_write` detail on `expectedModifiedAt`: the sequence changed since your read, or it no longer exists.

Requires Campaigns edit.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/sequences/PUT/v1/campaigns/%7BcampaignId%7D/email-sequence)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | The campaign's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The sequence's name. Omit it to keep the current name, or to name a new sequence "Email Sequence". |
| `isActive` | boolean | no | Whether the sequence is on. Defaults to true. |
| `steps` | array of ReplaceEmailSequenceStepRequest | yes | Every step and variant the sequence should have, at most 30 entries. Required. A step with an `id` updates that step, a step without one is added, and existing steps you leave out are deleted. An empty list deletes every step. |
| `expectedModifiedAt` | string (date-time) | no | The `modifiedAt` from your last read, in UTC (ISO 8601), compared to the second. When the sequence changed since then, Kenso refuses the replace with `409 conflict` and a `stale_write` detail, so you do not overwrite someone else's change. Omit it to replace without the check. |
| `instruction` | string | no | The person's request that led to this change, in their own words when you have them. Optional. Kenso keeps it with the edit history of the steps this save changes, marked as reported by your agent, and keeps the first 2,000 characters. Leave it out when no person asked for the change; never invent one. |

### Response 200

`data` is a `EmailSequence`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The email sequence's id. |
| `campaignId` | integer (int64) | The id of the campaign the sequence belongs to. |
| `segmentId` | integer (int64) | The id of the segment that owns the sequence. Null for the campaign's own sequence. |
| `name` | string | The sequence's name. |
| `isActive` | boolean | Whether the sequence is on. |
| `steps` | array of EmailSequenceStep | Every step and variant of the sequence, in step order. |
| `createdAt` | string (date-time) | When the sequence was created, in UTC (ISO 8601). |
| `modifiedAt` | string (date-time) | When the sequence last changed, in UTC (ISO 8601). Send it as `expectedModifiedAt` on your next replace so you do not overwrite someone else's change. |
| `contentWarnings` | array of EmailSequenceContentWarning | What Kenso's content checks found in the steps you saved, such as a link whose text names another site. Only a replace response with findings carries it. Omitted otherwise. |

### Request

```bash
curl -X PUT "https://api.ken.so/v1/campaigns/812/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 '{
  "name": "Engineering leaders",
  "isActive": true,
  "steps": [
    {
      "id": 8841,
      "stepOrder": 1,
      "variant": "a",
      "subject": "Onboarding new engineers at {company}",
      "body": "Hi {firstName},\n\nMost engineering teams lose a new hire'\''s first two weeks to setup and access requests. We help teams like yours get that down to two days.\n\nWorth a 15-minute look next week?\n\n{sender_first_name}",
      "bodyFormat": "plain",
      "waitDays": 0,
      "isActive": true,
      "openTrackingEnabled": false,
      "handwrittenEnabled": false
    },
    {
      "id": 8842,
      "stepOrder": 2,
      "variant": "a",
      "subject": "",
      "body": "Hi {firstName}, following up on this. Happy to send a 2-minute video instead if that is easier.\n\n{sender_first_name}",
      "bodyFormat": "plain",
      "waitDays": 3,
      "isActive": true,
      "openTrackingEnabled": false,
      "handwrittenEnabled": false
    }
  ],
  "expectedModifiedAt": "2026-10-14T09:41:27Z",
  "instruction": "Offer a short video in the follow-up."
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 2210,
    "campaignId": 4821,
    "segmentId": 1207,
    "name": "Engineering leaders",
    "isActive": true,
    "steps": [
      {
        "id": 8841,
        "stepOrder": 1,
        "variant": "a",
        "subject": "Onboarding new engineers at {company}",
        "body": "Hi {firstName},\n\nMost engineering teams lose a new hire's first two weeks to setup and access requests. We help teams like yours get that down to two days.\n\nWorth a 15-minute look next week?\n\n{sender_first_name}",
        "bodyFormat": "plain",
        "waitDays": 0,
        "isActive": true,
        "openTrackingEnabled": false,
        "handwrittenEnabled": false
      },
      {
        "id": 8842,
        "stepOrder": 2,
        "variant": "a",
        "subject": "",
        "body": "Hi {firstName}, following up on this. Happy to send a 2-minute video instead if that is easier.\n\n{sender_first_name}",
        "bodyFormat": "plain",
        "waitDays": 3,
        "isActive": true,
        "openTrackingEnabled": false,
        "handwrittenEnabled": false
      }
    ],
    "createdAt": "2026-09-23T15:02:11Z",
    "modifiedAt": "2026-10-14T09:41:27Z"
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### ReplaceEmailSequenceStepRequest

One variant of one email step to save.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The id of the step to update. Omit it to add a new step. Kenso skips a step whose id is not in this sequence. |
| `stepOrder` | integer (int32) | no | The step's position, starting at 1. Each `stepOrder` and `variant` pair can appear once, and each `stepOrder` needs at least one active variant. |
| `variant` | string | no | The variant for A/B testing: `a`, `b`, `c` or `d`. Defaults to `a`. The variants of one step cannot be identical. |
| `name` | string | no | A label for the step. Omit it to leave the step without one. |
| `subject` | string | no | The subject line. A variable in single braces, such as `{firstName}`, must be a contact variable or one of the campaign's custom variables, as `GET /v1/sequence-variables` lists them. Leave the subject empty on step 2 or later to send the email as a reply in the thread of the previous email. |
| `body` | string | no | The email body, written as `bodyFormat` says. Variables follow the same rules as in `subject`. |
| `bodyFormat` | string | no | How `body` is written: `plain`, `markdown` or `html`. Defaults to `plain`. `html` needs the `html_steps` feature. |
| `waitDays` | integer (int32) | no | Days Kenso waits after the previous step is sent before it sends this step. Step 1 ignores it. Defaults to 0. |
| `isActive` | boolean | no | Whether Kenso sends this variant. Defaults to true. |
| `openTrackingEnabled` | boolean | no | Stored and returned for compatibility; it does not affect sending. The campaign's `trackOpens` decides whether a send carries the open pixel. Defaults to false, so a replace that leaves it out turns it off. Saved versions do not keep it. |
| `handwrittenEnabled` | boolean | no | Set to true to send the letter part of the body as an image of a handwritten letter. The letter part is the body above the sender signature (`{sender_signature}`) or the unsubscribe link, and it cannot contain links. Defaults to false, so a replace that leaves it out turns the letter off. While the `handwritten_letters` feature is off for the workspace, the step sends as normal text. |
| `handwrittenBackground` | string | no | The paper behind the handwritten letter: `walnut`, `linen`, `kraft`, `marble`, `deckle` or `notepad`. Null or omitted means `walnut`. |
| `handwrittenIntro` | string | no | The line of normal text above the handwritten letter: at most 200 characters on one line, with no HTML, links or spintax. Null or omitted means Kenso's default line, which names the contact and the sender. |
| `studioTemplateVersionId` | integer (int64) | no | A published Studio email version for this step to send. The step becomes `html` and stores the version's subject and body, so `subject`, `body` and `bodyFormat` sent with it are ignored. Null or omitted unpins the step. Needs the `studio`, `studio_email` and `html_steps` features. Only a sequence replace reads it. A saved version ignores it, so restoring that version unpins the step. |

### EmailSequenceStep

One variant of one email step in a sequence.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The step's id. Send it back in a replace to update this step. |
| `campaignId` | integer (int64) | no | The campaign whose email sequence holds this step. Omitted on sequence reads, which carry it on the sequence. |
| `stepOrder` | integer (int32) | no | The step's position in the sequence, starting at 1. The variants of one step share it. |
| `variant` | string | no | The variant of the step for A/B testing: `a`, `b`, `c` or `d`. |
| `name` | string | no | A label for the step. Null when none is set. |
| `subject` | string | no | The subject line, with variables such as `{firstName}` not yet filled in. An empty subject on step 2 or later sends the email as a reply in the thread of the previous email. |
| `body` | string | no | The email body, with variables not yet filled in. `bodyFormat` says how to read it. |
| `bodyFormat` | string | no | How `body` is written: `plain`, `markdown` or `html`. |
| `waitDays` | integer (int32) | no | Days Kenso waits after the previous step is sent before it sends this step. Step 1 ignores it and is usually 0. |
| `isActive` | boolean | no | Whether Kenso sends this variant. An inactive variant is kept but not sent. |
| `openTrackingEnabled` | boolean | no | Stored and returned for compatibility; it does not affect sending. The campaign's `trackOpens` decides whether a send carries the open pixel. |
| `handwrittenEnabled` | boolean | no | Whether Kenso sends the letter part of the body as an image of a handwritten letter. The letter part is the body above the sender signature or the unsubscribe link. |
| `handwrittenBackground` | string | no | The paper behind the handwritten letter: `walnut`, `linen`, `kraft`, `marble`, `deckle` or `notepad`. Null means `walnut`. |
| `handwrittenIntro` | string | no | The line of normal text above the handwritten letter. Null means Kenso's default line, which names the contact and the sender. |
| `warnings` | array of string | no | Advice about this step that never stops a save. An `html` step can carry `html_on_mailbox_inbox` (the campaign sends from a Google or Microsoft mailbox), `html_size_near_cap` (the body is over 80% of the size limit) and `html_external_image:<host>` (an image loads from another site). A replace response can add `html_removed:<what>` for markup Kenso removed, and `studio_pin_removed` on any step whose Studio email the replace unpinned. Null when there is nothing to report. |
| `studioTemplateVersionId` | integer (int64) | no | The Studio email version this step sends, filled in for each contact. Null when the step does not send a Studio email. |
| `studioPin` | StudioPin | no | The state of the Studio email this step sends. Null when the step does not send one. |

### EmailSequenceContentWarning

One finding of Kenso's content checks on a saved email step.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `stepOrder` | integer (int32) | no | The `stepOrder` of the step the finding is about. |
| `variant` | string | no | The variant of the step the finding is about: `a`, `b`, `c` or `d`. |
| `code` | string | no | The rule that found it, as a stable snake_case code such as `link_host_mismatch` (a link's text is a web address that differs from where the link goes). |
| `severity` | string | no | How serious the finding is: `warning`, `hard_warning` or `block`, from least to most serious. |
| `path` | string | no | The part of the step the finding is about, such as `subject` or `body.links`. |
| `message` | string | no | A sentence that explains the finding. |
| `policyVersion` | string | no | The version of the content rules that produced the finding. |

### StudioPin

The Studio email version a step sends, and whether it can still be sent.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `versionId` | integer (int64) | no | The id of the Studio email version. |
| `templateId` | integer (int64) | no | The id of the Studio email the version belongs to. Null when that email no longer exists. |
| `state` | string | no | `ok`, or `stale` when the version is no longer published, is not an email, or its Studio email was deleted. A `stale` step sends the subject and body stored on the step instead. |
