> 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

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

A campaign's email sequence: read, replace or delete it, preview it for one contact and send a test.

Campaigns. 5 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/email-sequences/openapi.json](/docs/api/email-sequences/openapi.json).

- `GET /v1/campaigns/{campaignId}/email-sequence` - Get a campaign's email sequence (`email-sequences.get`): [/docs/api/email-sequences/get.md](/docs/api/email-sequences/get.md)
- `PUT /v1/campaigns/{campaignId}/email-sequence` - Replace a campaign's email sequence (`email-sequences.replace`): [/docs/api/email-sequences/replace.md](/docs/api/email-sequences/replace.md)
- `DELETE /v1/campaigns/{campaignId}/email-sequence` - Delete a campaign's email sequence (`email-sequences.delete`): [/docs/api/email-sequences/delete.md](/docs/api/email-sequences/delete.md)
- `GET /v1/campaigns/{campaignId}/email-sequence/preview` - Preview a campaign's email sequence (`email-sequences.preview`): [/docs/api/email-sequences/preview.md](/docs/api/email-sequences/preview.md)
- `POST /v1/campaigns/{campaignId}/email-sequence/test-send` - Test a campaign's email sequence (`email-sequences.test-send`): [/docs/api/email-sequences/test-send.md](/docs/api/email-sequences/test-send.md)

## Get a campaign's email sequence

`GET /v1/campaigns/{campaignId}/email-sequence` - operationId `email-sequences.get`

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

Returns the campaign's own email sequence with its steps. Contacts in a segment that has no email sequence of
its own get this one.

Errors:

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

Requires Campaigns view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/sequences/GET/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`. |

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

## Delete a campaign's email sequence

`DELETE /v1/campaigns/{campaignId}/email-sequence` - operationId `email-sequences.delete`

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

Deletes the campaign's own email sequence and its steps. Segments that have their own email sequence keep it.
When the workspace needs client approval of copy, Kenso pauses a sending campaign until the client approves
the change.

Errors:

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

Requires Campaigns edit.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/sequences/DELETE/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`. |

### Response 204

### Request

```bash
curl -X DELETE "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"
```

### Example response

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

## Preview a campaign's email sequence

`GET /v1/campaigns/{campaignId}/email-sequence/preview` - operationId `email-sequences.preview`

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

Shows each step of the campaign's 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 campaign.

A contact whose language has an approved translation sees that translation, with its `language`, the English
`mirrorSubject` and `mirrorBody`, and `qaScore`. Pass `language` to preview as a contact in that language.

Pass `senderEmailId` to preview from one of the campaign's inboxes, as a test send from it would look: its
names, signature and unsubscribe link fill the steps. Without it, or with an inbox the campaign does not use,
Kenso uses the campaign's first inbox by email address. `sender` names the inbox used.

Errors:

- `400 validation_failed`: neither `contactId` nor `useRandom=true` was sent, or `language` is not a language tag.
- `404 not_found`: the campaign does not exist in this workspace, the contact is not in the campaign, or the campaign 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/campaigns/%7BcampaignId%7D/email-sequence/preview)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | The campaign's id. |
| `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/campaigns/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 campaign's email sequence

`POST /v1/campaigns/{campaignId}/email-sequence/test-send` - operationId `email-sequences.test-send`

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

Sends the campaign's email sequence to up to 5 addresses, filled with one contact's data, so you can check the
emails in a real inbox. Kenso sends every step and variant that has a subject or body, in step order, from the
inbox in `senderEmailId`.

`contactId`, `targetEmails` and `senderEmailId` are required. The contact must be in the campaign. Once the
campaign has inboxes, `senderEmailId` must be one of them. Each step goes out in the contact's language, or in
`language` when you send it. `notes` lists steps that went out differently from the step as written, such as an
approved translation or a handwritten letter sent as normal text.

Each address and step pair counts as one email against the workspace's daily test send limit. When some
emails fail, the call still answers `200`: read `emailsSent` and `failures`.

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

Errors:

- `400 validation_failed`: a required field is missing, `targetEmails` has more than 5 addresses or an invalid one, or `language` is not a language tag.
- `400 validation_failed` with detail `invalid_track`: `providerTrack` is not `google`, `microsoft` or `other`.
- `400 validation_failed`: an address is on the workspace blocklist or has hard bounced.
- `400 validation_failed`: the inbox is paused, cannot send, is a member's own mailbox, or is not one of the campaign's inboxes, or no step has a subject or body.
- `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 campaign does not exist in this workspace, 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/campaigns/%7BcampaignId%7D/email-sequence/test-send)

### 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 |
| --- | --- | --- | --- |
| `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/campaigns/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
}'
```

### Example response

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

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

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