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

# Segment email sequences: Save a segment's email sequence version

> **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 [Segment email sequences](/docs/api/segment-email-sequences.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Save a segment's email sequence version

`POST /v1/segments/{segmentId}/email-sequence/versions` - operationId `segment-email-sequences.save-version`

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

Saves a version of the segment's own email sequence that you can restore later. The call does not change the
live sequence.

Without `sourceVersionId`, the version is a copy of the live sequence, and Kenso does not store the `name`,
`isActive` or `steps` you send. With `sourceVersionId`, the version starts from that saved version: `name` and
`isActive` replace its values when you send them, and a non-empty `steps` list replaces its steps.

Kenso checks any `steps` you send with the rules of `PUT /v1/segments/{segmentId}/email-sequence`, links
included, because a restore makes them live.

Errors:

- `400 validation_failed`: a step breaks a sequence rule.
- `400 validation_failed` with `link_reputation_blocked` details: a link failed the URL reputation check. Each detail has `field`, `rule`, `url`, `stepOrder` and, for a step you sent with an `id`, `stepId`.
- `404 not_found`: the segment does not exist in this workspace, it has no email sequence of its own, or `sourceVersionId` is not one of that sequence's versions.
- `409 conflict`: another version save for this sequence is running. Retry shortly.

Requires Campaigns edit.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/sequences/POST/v1/segments/%7BsegmentId%7D/email-sequence/versions)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `segmentId` | path | integer (int64) | yes | The segment'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 name to store in the version. Used only with `sourceVersionId`. Omit it to keep that version's name. |
| `isActive` | boolean | no | Whether the sequence is on, as stored in the version. Used only with `sourceVersionId`. Omit it to keep that version's value. |
| `steps` | array of ReplaceEmailSequenceStepRequest | no | The steps to store in the version, in the same shape as a sequence replace. Used only with `sourceVersionId`, where a non-empty list replaces that version's steps. Kenso checks the steps with the sequence rules either way. |
| `sourceVersionId` | integer (int64) | no | The id of a saved version of this sequence to start from. Omit it to save a copy of the live sequence. |

### Response 200

`data` is a `EmailSequenceVersionSave`.

| Field | Type | Description |
| --- | --- | --- |
| `sequence` | EmailSequence | The sequence as the saved version holds it, in the same shape as `GET /v1/campaigns/{campaignId}/email-sequence`. The live sequence does not change. |
| `version` | SequenceVersion | The version Kenso saved. |
| `versionWarning` | string | Why Kenso could not record the version. Omitted when it did. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/segments/812/email-sequence/versions" \
  -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 '{
  "sourceVersionId": 3298,
  "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
    }
  ]
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "sequence": {
      "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"
    },
    "version": {
      "id": 3302,
      "versionNumber": 6,
      "createdAt": "2026-10-14T09:41:27Z",
      "createdByUserId": 1093,
      "createdByEmail": "jordan.patel@northwind-outbound.example.com",
      "isRevert": false
    }
  }
}
```

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

### EmailSequence

The emails Kenso sends to each contact of a campaign or segment, in step order. A step can have up to four variants for A/B testing.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The email sequence's id. |
| `campaignId` | integer (int64) | no | The id of the campaign the sequence belongs to. |
| `segmentId` | integer (int64) | no | The id of the segment that owns the sequence. Null for the campaign's own sequence. |
| `name` | string | no | The sequence's name. |
| `isActive` | boolean | no | Whether the sequence is on. |
| `steps` | array of EmailSequenceStep | no | Every step and variant of the sequence, in step order. |
| `createdAt` | string (date-time) | no | When the sequence was created, in UTC (ISO 8601). |
| `modifiedAt` | string (date-time) | no | 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 | no | 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. |

### SequenceVersion

A saved version of an email or LinkedIn sequence.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The version's id. |
| `versionNumber` | integer (int32) | no | The version's number within its sequence. The first version is 1, and each new version gets the next number. |
| `createdAt` | string (date-time) | no | When Kenso saved the version, in UTC. |
| `createdByUserId` | integer (int64) | no | The id of the member who saved the version. Omitted when Kenso could not match the saver to a member. |
| `createdByEmail` | string | no | The email address of the member who saved the version. Omitted when none was recorded. |
| `isRevert` | boolean | no | True when the version records a restore of an earlier version. |
| `revertedFromVersionId` | integer (int64) | no | The id of the version that was restored. Omitted when `isRevert` is false. |
| `revertedFromVersionNumber` | integer (int32) | no | The number of the version that was restored. Omitted when `isRevert` is false. |
| `revertedFromCreatedAt` | string (date-time) | no | When the restored version was saved, in UTC. Omitted when `isRevert` is false. |

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