> 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

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

The email sequence of one segment, with preview, test sends and saved versions.

Campaigns. 9 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/segment-email-sequences/openapi.json](/docs/api/segment-email-sequences/openapi.json).

- `GET /v1/segments/{segmentId}/email-sequence` - Get a segment's email sequence (`segment-email-sequences.get`): [/docs/api/segment-email-sequences/get.md](/docs/api/segment-email-sequences/get.md)
- `PUT /v1/segments/{segmentId}/email-sequence` - Replace a segment's email sequence (`segment-email-sequences.replace`): [/docs/api/segment-email-sequences/replace.md](/docs/api/segment-email-sequences/replace.md)
- `DELETE /v1/segments/{segmentId}/email-sequence` - Delete a segment's email sequence (`segment-email-sequences.delete`): [/docs/api/segment-email-sequences/delete.md](/docs/api/segment-email-sequences/delete.md)
- `GET /v1/segments/{segmentId}/email-sequence/preview` - Preview a segment's email sequence (`segment-email-sequences.preview`): [/docs/api/segment-email-sequences/preview.md](/docs/api/segment-email-sequences/preview.md)
- `POST /v1/segments/{segmentId}/email-sequence/test-send` - Test a segment's email sequence (`segment-email-sequences.test-send`): [/docs/api/segment-email-sequences/test-send.md](/docs/api/segment-email-sequences/test-send.md)
- `GET /v1/segments/{segmentId}/email-sequence/versions` - List a segment's email sequence versions (`segment-email-sequences.list-versions`): [/docs/api/segment-email-sequences/list-versions.md](/docs/api/segment-email-sequences/list-versions.md)
- `POST /v1/segments/{segmentId}/email-sequence/versions` - Save a segment's email sequence version (`segment-email-sequences.save-version`): [/docs/api/segment-email-sequences/save-version.md](/docs/api/segment-email-sequences/save-version.md)
- `GET /v1/segments/{segmentId}/email-sequence/versions/{versionId}` - Get a segment's email sequence version (`segment-email-sequences.get-version`): [/docs/api/segment-email-sequences/get-version.md](/docs/api/segment-email-sequences/get-version.md)
- `POST /v1/segments/{segmentId}/email-sequence/versions/{versionId}/restore` - Restore a segment's email sequence version (`segment-email-sequences.restore-version`): [/docs/api/segment-email-sequences/restore-version.md](/docs/api/segment-email-sequences/restore-version.md)

## Get a segment's email sequence

`GET /v1/segments/{segmentId}/email-sequence` - operationId `segment-email-sequences.get`

| Permission | Rate limit |
| --- | --- |
| Campaigns view | 12,000 requests a minute per API key |

Returns the segment's own email sequence with its steps. A segment without one sends the campaign's email
sequence, and this call answers `404 not_found`.

Errors:

- `404 not_found`: the segment does not exist in this workspace, or it has no email sequence of its own.

Requires Campaigns view.

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

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

### 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 GET "https://api.ken.so/v1/segments/812/email-sequence" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### 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"
  }
}
```

## Replace a segment's email sequence

`PUT /v1/segments/{segmentId}/email-sequence` - operationId `segment-email-sequences.replace`

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

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

The step rules, link and content checks, and client approval of `PUT /v1/campaigns/{campaignId}/email-sequence`
apply. `steps` is the whole list: Kenso deletes the existing steps you leave out, and an empty list deletes
every step.

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` (`steps[i].subject` or `steps[i].body`), `rule`, `url`, `stepOrder` and, for a saved step, `stepId`.
- `404 not_found`: the segment 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/segments/%7BsegmentId%7D/email-sequence)

### 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 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/segments/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"
  }
}
```

## Delete a segment's email sequence

`DELETE /v1/segments/{segmentId}/email-sequence` - operationId `segment-email-sequences.delete`

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

Deletes the segment's own email sequence and its steps. The segment's contacts then get the campaign's email
sequence. When the workspace needs client approval of copy, Kenso pauses a sending campaign until the client
approves the change.

Errors:

- `404 not_found`: the segment does not exist in this workspace, or it has no email sequence of its own.

Requires Campaigns edit.

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

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

### Response 204

### Request

```bash
curl -X DELETE "https://api.ken.so/v1/segments/812/email-sequence" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```http
HTTP/1.1 204 No Content
```

## Preview a segment's email sequence

`GET /v1/segments/{segmentId}/email-sequence/preview` - operationId `segment-email-sequences.preview`

| Permission | Rate limit |
| --- | --- |
| Campaigns view | 12,000 requests a minute per API key |

Shows each step of the segment's own email sequence as Kenso would send it to one contact, with the variables
filled in. Pass `contactId`, or `useRandom=true` to pick a random contact of the segment.

`language` and `senderEmailId` work as in `GET /v1/campaigns/{campaignId}/email-sequence/preview`.

`providerTrack` (`google`, `microsoft` or `other`) previews or tests the email as that provider track sends it:
recipients on Google get plain text. A track's own `sequenceSegmentId` implies its track. Each step's
`sendsPlainText` is true when that track sends the step as plain text, and false with no track or on a campaign
that is not on provider tracks. `useRandom=true` on a track's own sequence picks from its audience segment.

Errors:

- `400 validation_failed`: neither `contactId` nor `useRandom=true` was sent, or `language` is not a language tag.
- `400 validation_failed` with detail `invalid_track`: `providerTrack` is not `google`, `microsoft` or `other`.
- `404 not_found`: the segment does not exist in this workspace or has no email sequence of its own, the contact is not in the campaign, or the segment has no contact to pick.

Requires Campaigns view.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `segmentId` | path | integer (int64) | yes | The segment's id. |
| `providerTrack` | query | string | no | `google`, `microsoft` or `other`. Each step's `sendsPlainText` tells whether that provider track sends it as plain text: recipients on Google get plain text. A track's own `sequenceSegmentId` implies its track. Ignored when the campaign is not on provider tracks. |
| `contactId` | query | integer (int64) | no | The id of the contact to preview as. The contact must be in the campaign. Send this or `useRandom`. |
| `useRandom` | query | boolean | no | Set to true to preview as a random contact of the campaign, or of the segment for a segment preview. Kenso ignores it when you pass `contactId`. Defaults to false. |
| `language` | query | string | no | A language or locale tag, such as `fr` or `fr-FR`. The preview shows the steps as a contact in that language would get them. Omit it to use the contact's own language. The campaign's source language shows the original text. |
| `senderEmailId` | query | integer (int64) | no | The id of the inbox to preview from. Its names, signature and unsubscribe link fill the steps. When you omit it, or it is not one of the campaign's inboxes, Kenso uses the campaign's first inbox by email address. |
| `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`. |

### Response 200

`data` is a `EmailSequencePreview`.

| Field | Type | Description |
| --- | --- | --- |
| `steps` | array of EmailSequencePreviewStep | Every step and variant of the sequence, inactive ones included, in step order. |
| `contact` | EmailSequencePreviewContact | The contact the preview is filled in for. |
| `sender` | EmailSequencePreviewSender | The mailbox whose names, signature and domain fill the preview: the `senderEmailId` you passed when it is one of the campaign's mailboxes, else the first in `senders`. Omitted when the campaign has no mailboxes. |
| `senders` | array of EmailSequencePreviewSender | Up to 50 of the campaign's mailboxes, ordered by email address. The mailbox you passed as `senderEmailId` is always included. Empty when the campaign has no mailboxes. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/segments/812/email-sequence/preview" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "steps": [
      {
        "stepNumber": 1,
        "subject": "Onboarding new engineers at Northwind Labs",
        "body": "Hi Amanda,\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\nAlex",
        "waitDays": 0,
        "variables": [
          {
            "name": "firstName",
            "type": "lead_variable",
            "value": "Amanda"
          },
          {
            "name": "company",
            "type": "lead_variable",
            "value": "Northwind Labs"
          },
          {
            "name": "sender_first_name",
            "type": "system_variable",
            "value": "Alex"
          }
        ]
      },
      {
        "stepNumber": 2,
        "subject": "",
        "body": "Hi Amanda, following up on this. Happy to send a 2-minute video instead if that is easier.\n\nAlex",
        "waitDays": 3,
        "variables": [
          {
            "name": "firstName",
            "type": "lead_variable",
            "value": "Amanda"
          },
          {
            "name": "sender_first_name",
            "type": "system_variable",
            "value": "Alex"
          }
        ]
      }
    ],
    "contact": {
      "id": 90125,
      "fullName": "Amanda Chen",
      "company": "Northwind Labs",
      "title": "VP of Engineering",
      "email": "amanda.chen@northwind.example.com"
    },
    "sender": {
      "id": 5530,
      "email": "alex@mail.example.com",
      "status": "active",
      "warmupReputation": 98,
      "healthScore": 94
    },
    "senders": [
      {
        "id": 5530,
        "email": "alex@mail.example.com",
        "status": "active",
        "warmupReputation": 98,
        "healthScore": 94
      }
    ]
  }
}
```

## Test a segment's email sequence

`POST /v1/segments/{segmentId}/email-sequence/test-send` - operationId `segment-email-sequences.test-send`

| Permission | Rate limit |
| --- | --- |
| Campaigns edit | 200 requests a minute per API key |

Sends the segment's own email sequence to up to 5 addresses, filled with one contact's data, so you can check
the emails in a real inbox.

The address, inbox and daily limit rules of `POST /v1/campaigns/{campaignId}/email-sequence/test-send` apply.
When some emails fail, the call still answers `200`: read `emailsSent` and `failures`.

`providerTrack` (`google`, `microsoft` or `other`) previews or tests the email as that provider track sends it:
recipients on Google get plain text. A track's own `sequenceSegmentId` implies its track. Ignored when the campaign
is not on provider tracks.

Errors:

- `400 validation_failed`: a required field is missing, an address is invalid, blocked or hard bounced, the inbox cannot be used, or no step has a subject or body.
- `400 validation_failed` with detail `invalid_track`: `providerTrack` is not `google`, `microsoft` or `other`.
- `402 free_plan_sending_needs_plan`: the workspace is on the Free plan, which sends nothing (test emails included) for a workspace created after the Free no-send rule started. `error.refusal` has `code` `FREE_PLAN_SENDING_NEEDS_PLAN` and `remedy` `Upgrade`: pick a paid plan, then send again.
- `404 not_found`: the segment does not exist in this workspace or has no email sequence of its own, or the contact is not in the campaign.
- `429 rate_limited`: the workspace has used its test emails for today.

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/test-send)

### 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 |
| --- | --- | --- | --- |
| `contactId` | integer (int64) | yes | The id of the contact whose details fill the variables. Required, and the contact must be in the campaign. |
| `targetEmails` | string | yes | The addresses to send the test to, separated by commas or semicolons, at most 5. Required. Addresses on the workspace's blocklist or with a hard bounce are refused. |
| `senderEmailId` | integer (int64) | yes | The id of the inbox to send from. Required. Once the campaign has inboxes, it must be one of them, and it must be able to send. |
| `language` | string | no | A language or locale tag, such as `fr` or `fr-FR`. Kenso sends the steps as a contact in that language would get them. Omit it to use the contact's own language. The campaign's source language sends the original text. |
| `providerTrack` | string | no | `google`, `microsoft` or `other`. Kenso sends the steps as that provider track sends them: recipients on Google get plain text. On a segment, a track's own `sequenceSegmentId` implies its track. Ignored when the campaign is not on provider tracks. |

### Response 200

`data` is a `EmailSequenceTestSend`.

| Field | Type | Description |
| --- | --- | --- |
| `stepsSent` | integer (int32) | Steps that reached every address in `targetEmails`. Each variant counts as a step. |
| `emailsAttempted` | integer (int32) | Emails Kenso tried to send, at most one per step and address. |
| `emailsSent` | integer (int32) | Emails that went out. |
| `sentTo` | array of string | The addresses that got at least one email, in alphabetical order. |
| `failures` | array of string | One message for each email or step that did not go out. Each message starts with the step number. |
| `notes` | array of string | Notes on emails that went out differently from the step as written, such as a handwritten letter sent as normal text. These emails did go out. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/segments/812/email-sequence/test-send" \
  -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 '{
  "contactId": 90125,
  "targetEmails": "jordan.patel@northwind-outbound.example.com",
  "senderEmailId": 5530,
  "providerTrack": "google"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "stepsSent": 2,
    "emailsAttempted": 2,
    "emailsSent": 2,
    "sentTo": [
      "jordan.patel@northwind-outbound.example.com"
    ],
    "failures": [],
    "notes": []
  }
}
```

## List a segment's email sequence versions

`GET /v1/segments/{segmentId}/email-sequence/versions` - operationId `segment-email-sequences.list-versions`

| Permission | Rate limit |
| --- | --- |
| Campaigns view | 12,000 requests a minute per API key |

Returns the saved versions of the segment's own email sequence, newest first. Kenso adds a version when you save
one, restore one, or restore the segment. Replacing the sequence does not add a version.

Errors:

- `400 validation_failed`: `limit` is out of range, or `cursor` is invalid.
- `404 not_found`: the segment does not exist in this workspace, or it has no email sequence of its own.

Requires Campaigns view.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `segmentId` | path | integer (int64) | yes | The segment's id. |
| `limit` | query | integer (int32) | no | Versions per page, from 1 to 100. Defaults to 20. |
| `cursor` | query | string | no | The `nextCursor` from the previous page. Omit it for the first page. |
| `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`. |

### Response 200

`data` is a list of `SequenceVersion`. Each item has these fields. The response also carries `pagination`.

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

### Request

```bash
curl -X GET "https://api.ken.so/v1/segments/812/email-sequence/versions?limit=20" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "id": 3302,
      "versionNumber": 6,
      "createdAt": "2026-10-14T09:41:27Z",
      "createdByUserId": 1093,
      "createdByEmail": "jordan.patel@northwind-outbound.example.com",
      "isRevert": false
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## 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
    }
  }
}
```

## Get a segment's email sequence version

`GET /v1/segments/{segmentId}/email-sequence/versions/{versionId}` - operationId `segment-email-sequences.get-version`

| Permission | Rate limit |
| --- | --- |
| Campaigns view | 12,000 requests a minute per API key |

Returns one saved version with a copy of the sequence's name, `isActive` and steps as they were saved.

Errors:

- `404 not_found`: the segment does not exist in this workspace, it has no email sequence of its own, or the version is not one of that sequence's versions.

Requires Campaigns view.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `segmentId` | path | integer (int64) | yes | The segment's id. |
| `versionId` | path | integer (int64) | yes | The version's id, from the list of versions. |
| `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`. |

### Response 200

`data` is a `EmailSequenceVersionDetail`.

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

### Request

```bash
curl -X GET "https://api.ken.so/v1/segments/812/email-sequence/versions/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 3302,
    "versionNumber": 6,
    "createdAt": "2026-10-14T09:41:27Z",
    "createdByUserId": 1093,
    "createdByEmail": "jordan.patel@northwind-outbound.example.com",
    "isRevert": false,
    "snapshot": {
      "schemaVersion": 1,
      "name": "Engineering leaders",
      "isActive": true,
      "steps": [
        {
          "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,
          "handwrittenEnabled": false
        },
        {
          "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,
          "handwrittenEnabled": false
        }
      ]
    }
  }
}
```

## Restore a segment's email sequence version

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

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

Writes the steps of a saved version into the segment's live email sequence and adds a new version that records
the restore. `newVersionNumber` in the response is that version's number.

Kenso checks the version's steps with today's sequence rules and URL reputation check before it writes them.

Errors:

- `400 validation_failed`: the version has no steps while the live sequence has some, or a step breaks today's sequence rules.
- `400 validation_failed` with `link_reputation_blocked` details: a link failed the URL reputation check. Each detail's `field` is `steps.subject` or `steps.body`, and `stepId` is the live step the restore would overwrite.
- `404 not_found`: the segment does not exist in this workspace, it has no email sequence of its own, or the version 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/%7BversionId%7D/restore)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `segmentId` | path | integer (int64) | yes | The segment's id. |
| `versionId` | path | integer (int64) | yes | The id of the version to restore. |
| `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`. |

### Response 200

`data` is a `SequenceRestore`.

| Field | Type | Description |
| --- | --- | --- |
| `newVersionNumber` | integer (int32) | The number of the new version that records the restore. Omitted when Kenso restored the steps but could not record the version. |
| `versionWarning` | string | Why Kenso could not record the version after it restored the steps. Omitted when it did. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/segments/812/email-sequence/versions/812/restore" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "newVersionNumber": 7
  }
}
```

## Types

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

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

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

### EmailSequencePreviewStep

One step and variant filled in for the contact.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `stepNumber` | integer (int32) | no | The step's `stepOrder`. Variants of one step share it. |
| `subject` | string | no | The subject as the contact would get it, with spintax picked and variables filled in. An AI variable with no value shows a placeholder in brackets. |
| `body` | string | no | The body as the contact would get it, with spintax picked, variables filled in and tracked links shown as their target URLs. The unsubscribe link is a sample that unsubscribes nobody. |
| `waitDays` | integer (int32) | no | Days Kenso waits after the previous step is sent before it sends this one. |
| `variables` | array of EmailSequencePreviewVariable | no | The variables found in the subject and body, with what Kenso filled in. |
| `language` | string | no | The language tag of the approved translation the contact gets, such as `fr-FR`. Omitted when the contact gets the text as written. |
| `mirrorSubject` | string | no | An English translation of the translated subject, filled in like `subject`. Only set with `language`. |
| `mirrorBody` | string | no | An English translation of the translated body, filled in like `body`. Only set with `language`. |
| `qaScore` | integer (int32) | no | The quality score Kenso gave the translation, from 0 to 100. Only set with `language`. |
| `sendsPlainText` | boolean | no | Segment previews only: true when this step goes out as plain text for the requested provider track. |

### EmailSequencePreviewContact

The contact a preview is filled in for.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The contact's id. |
| `fullName` | string | no | The contact's full name. |
| `company` | string | no | The name of the contact's company. Omitted when unknown. |
| `title` | string | no | The contact's job title. Omitted when unknown. |
| `email` | string | no | The address Kenso would send to. Omitted when the contact has no address Kenso can send to. |

### EmailSequencePreviewSender

A mailbox the campaign sends from.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int32) | no | The mailbox's id, the value to pass as `senderEmailId`. |
| `email` | string | no | The mailbox's email address. |
| `status` | string | no | The mailbox's state: `active`, `warmup`, `disconnected`, `paused`, `banned`, `connection_error`, `deleted`, `inactive`, `replaced` or `pending_provisioning`. |
| `warmupReputation` | integer (int32) | no | The mailbox's reputation from its latest warmup data. Omitted when there is none. |
| `healthScore` | number (double) | no | The mailbox's health score, from its delivery score or else its latest warmup score. Omitted when neither is known. |

### EmailSequencePreviewVariable

A variable found in a step, and what Kenso filled in for it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The variable's name as written in the step. |
| `type` | string | no | The kind of variable: `lead_variable`, `ai_variable` or `system_variable`. |
| `value` | string | no | The value Kenso filled in. Omitted when there is none. |
| `placeholder` | string | no | The text the preview shows in place of an AI variable that has no value yet, such as `[name - Not available]`. Omitted otherwise. |
| `lineId` | integer (int64) | no | The id of the lead's AI line whose text `value` shows, the same id the contact's AI lines list. Omitted for every other value: lead fields, the lead's own custom variables, placeholders and prompt defaults. |

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

### EmailSequenceSnapshot

A copy of an email sequence as it was when the version was saved.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaVersion` | integer (int32) | no | The format version of the copy. |
| `name` | string | no | The sequence's name. |
| `isActive` | boolean | no | Whether the sequence was on. |
| `steps` | array of EmailSequenceSnapshotStep | no | Every step and variant of the sequence, inactive ones included. |

### EmailSequenceSnapshotStep

One email step and variant in a saved version.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `stepOrder` | integer (int32) | no | The step's position in the sequence, from 1. Variants of one step share it. |
| `variant` | string | no | The variant: `a`, `b`, `c` or `d`. |
| `name` | string | no | The step's name. Omitted when it has none. |
| `subject` | string | no | The subject line as written, with its variables and spintax. |
| `body` | string | no | The body as written, in `bodyFormat`, with its variables and spintax. |
| `bodyFormat` | string | no | The body's format: `plain`, `markdown` or `html`. |
| `waitDays` | integer (int32) | no | Days Kenso waits after the previous step is sent before it sends this one. 0 on the first step. |
| `isActive` | boolean | no | Whether the variant was on. |
| `handwrittenEnabled` | boolean | no | True when the step sends its body as an image of a handwritten letter. |
| `handwrittenBackground` | string | no | The letter paper: `walnut`, `linen`, `kraft`, `marble`, `deckle` or `notepad`. Omitted means `walnut`. |
| `handwrittenIntro` | string | no | The normal-text line above the letter. Omitted means the default line. |

All resources: [/docs.md](/docs.md).
