> 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: Preview a campaign's email sequence

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

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

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

## Types

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

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