Kenso
Get early access

Segment email sequences

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

Campaigns and sequences9 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors

Return the segment email sequence

GET/v1/segments/{segmentId}/email-sequencesegment-email-sequences.get

Try it on developer.ken.so

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a EmailSequenceModel.

Field
Type
Description
id
integer (int64)
campaignId
integer (int64)
segmentId
integer (int64)
name
string
isActive
boolean
steps
array of EmailSequenceStepModel
createdAt
string (date-time)
modifiedAt
string (date-time)
contentWarnings
array of EmailSequenceContentWarningDTO
Content-policy findings from this save. Only on replace responses that have findings; omitted otherwise.
Request
curl -X GET "https://api.ken.so/v1/segments/812/email-sequence" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "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 {{first_name}},\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 {{first_name}}, 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 the segment email sequence

PUT/v1/segments/{segmentId}/email-sequencesegment-email-sequences.replace

Try it on developer.ken.so

Same refusals as the campaign email sequence replace, link_reputation_blocked and the expectedModifiedAt check included.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
name
string
optional
isActive
boolean
optional
steps
array of ReplaceEmailSequenceStepRequest
optional
expectedModifiedAt
string (date-time)
optional
Optional. The modifiedAt from your last read. When the live sequence changed since, the replace is refused with 409 conflict and detail code stale_write, so you do not overwrite someone else's edit.

Response 200

data is a EmailSequenceModel.

Field
Type
Description
id
integer (int64)
campaignId
integer (int64)
segmentId
integer (int64)
name
string
isActive
boolean
steps
array of EmailSequenceStepModel
createdAt
string (date-time)
modifiedAt
string (date-time)
contentWarnings
array of EmailSequenceContentWarningDTO
Content-policy findings from this save. Only on replace responses that have findings; omitted otherwise.
Request
curl -X PUT "https://api.ken.so/v1/segments/812/email-sequence" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "isActive": true,
  "steps": [
    {
      "id": 812,
      "stepOrder": 1,
      "variant": "string",
      "name": "string",
      "subject": "string",
      "body": "string",
      "bodyFormat": "string",
      "waitDays": 1,
      "isActive": true,
      "openTrackingEnabled": true,
      "handwrittenEnabled": true,
      "handwrittenBackground": "string",
      "handwrittenIntro": "string",
      "studioTemplateVersionId": 812
    }
  ],
  "expectedModifiedAt": "2026-09-23T15:02:11Z"
}'
Response 200
{
  "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 {{first_name}},\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 {{first_name}}, 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 the segment email sequence

DELETE/v1/segments/{segmentId}/email-sequencesegment-email-sequences.delete

Try it on developer.ken.so

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 204

Request
curl -X DELETE "https://api.ken.so/v1/segments/812/email-sequence" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 204
HTTP/1.1 204 No Content

Preview the segment email sequence for one contact

GET/v1/segments/{segmentId}/email-sequence/previewsegment-email-sequences.preview

Try it on developer.ken.so

Pass contactId, or useRandom=true to preview a random contact of the segment; with neither the call is 400 validation_failed on contactId. senderEmailId works as on the campaign preview.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
contactId
In: query
integer (int64)
optional
useRandom
In: query
boolean
optional
language
In: query
string
optional
Preview as a contact in this language (fr-FR, de) gets the steps; omitted previews in the contact's own language. The campaign's source language previews the source text.
senderEmailId
In: query
integer (int64)
optional
The inbox to preview from, as the test send's senderEmailId: its names, signature and unsubscribe host fill the steps, and sender names it. An inbox that is not one of the campaign's, or none, previews from the first sender.
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a EmailSequencePreviewModel.

Field
Type
Description
steps
array of EmailSequencePreviewStepModel
contact
EmailSequencePreviewContactModel
sender
EmailSequencePreviewSenderModel
senders
array of EmailSequencePreviewSenderModel
Request
curl -X GET "https://api.ken.so/v1/segments/812/email-sequence/preview" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "steps": [
      {
        "stepNumber": 1,
        "subject": "string",
        "body": "string",
        "waitDays": 1,
        "variables": [
          {
            "name": "string",
            "type": "string",
            "value": "string",
            "placeholder": "string"
          }
        ],
        "language": "string",
        "mirrorSubject": "string",
        "mirrorBody": "string",
        "qaScore": 1
      }
    ],
    "contact": {
      "id": 812,
      "fullName": "string",
      "company": "string",
      "title": "string",
      "email": "[email protected]"
    },
    "sender": {
      "id": 812,
      "email": "[email protected]",
      "status": "string",
      "warmupReputation": 1,
      "healthScore": 0.5
    },
    "senders": [
      {
        "id": 812,
        "email": "[email protected]",
        "status": "string",
        "warmupReputation": 1,
        "healthScore": 0.5
      }
    ]
  }
}

Send the segment email sequence to test recipients

POST/v1/segments/{segmentId}/email-sequence/test-sendsegment-email-sequences.test-send

Try it on developer.ken.so

The recipient, sender and quota rules of the campaign test send apply.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
contactId
integer (int64)
optional
targetEmails
string
optional
senderEmailId
integer (int64)
optional
language
string
optional
Send as a contact in this language (fr-FR, de) gets the steps; omitted sends in the contact's own language. The campaign's source language sends the source text.

Response 200

data is a EmailSequenceTestSendModel.

Field
Type
Description
stepsSent
integer (int32)
emailsAttempted
integer (int32)
emailsSent
integer (int32)
sentTo
array of string
failures
array of string
notes
array of string
Sends that went out differently from the step as written, e.g. a handwritten letter sent as text.
Request
curl -X POST "https://api.ken.so/v1/segments/812/email-sequence/test-send" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "contactId": 812,
  "targetEmails": "string",
  "senderEmailId": 812,
  "language": "string"
}'
Response 200
{
  "success": true,
  "data": {
    "stepsSent": 1,
    "emailsAttempted": 1,
    "emailsSent": 1,
    "sentTo": [
      "string"
    ],
    "failures": [
      "string"
    ],
    "notes": [
      "string"
    ]
  }
}

List saved versions of a segment email sequence, newest first

GET/v1/segments/{segmentId}/email-sequence/versionssegment-email-sequences.list-versions

Try it on developer.ken.so

limit is 1 to 100 and defaults to 20. Requires ReadAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
limit
In: query
integer (int32)
optional
cursor
In: query
string
optional
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

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

Field
Type
Description
id
integer (int64)
versionNumber
integer (int32)
createdAt
string (date-time)
createdByUserId
integer (int64)
createdByEmail
string
isRevert
boolean
revertedFromVersionId
integer (int64)
revertedFromVersionNumber
integer (int32)
revertedFromCreatedAt
string (date-time)
Request
curl -X GET "https://api.ken.so/v1/segments/812/email-sequence/versions?limit=1" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": [
    {
      "id": 812,
      "versionNumber": 1,
      "createdAt": "2026-09-23T15:02:11Z",
      "createdByUserId": 812,
      "createdByEmail": "[email protected]",
      "isRevert": true,
      "revertedFromVersionId": 812,
      "revertedFromVersionNumber": 1,
      "revertedFromCreatedAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  }
}

Save a new segment email sequence version

POST/v1/segments/{segmentId}/email-sequence/versionssegment-email-sequences.save-version

Try it on developer.ken.so

Omit steps to snapshot the live sequence. With sourceVersionId, omitted or empty steps keep that version's steps, and a non-empty list overlays them. A link the URL reputation check refuses is 400 validation_failed with one link_reputation_blocked detail per link (field, stepId, stepOrder, rule, url), as on the sequence replace. Requires SequenceEditAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
name
string
optional
isActive
boolean
optional
steps
array of ReplaceEmailSequenceStepRequest
optional
sourceVersionId
integer (int64)
optional

Response 200

data is a EmailSequenceVersionSaveModel.

Field
Type
Description
sequence
EmailSequenceModel
version
SequenceVersionModel
versionWarning
string
Request
curl -X POST "https://api.ken.so/v1/segments/812/email-sequence/versions" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "isActive": true,
  "steps": [
    {
      "id": 812,
      "stepOrder": 1,
      "variant": "string",
      "name": "string",
      "subject": "string",
      "body": "string",
      "bodyFormat": "string",
      "waitDays": 1,
      "isActive": true,
      "openTrackingEnabled": true,
      "handwrittenEnabled": true,
      "handwrittenBackground": "string",
      "handwrittenIntro": "string",
      "studioTemplateVersionId": 812
    }
  ],
  "sourceVersionId": 812
}'
Response 200
{
  "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 {{first_name}},\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 {{first_name}}, 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": 812,
      "versionNumber": 1,
      "createdAt": "2026-09-23T15:02:11Z",
      "createdByUserId": 812,
      "createdByEmail": "[email protected]",
      "isRevert": true,
      "revertedFromVersionId": 812,
      "revertedFromVersionNumber": 1,
      "revertedFromCreatedAt": "2026-09-23T15:02:11Z"
    },
    "versionWarning": "string"
  }
}

Return one segment email sequence version

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

Try it on developer.ken.so

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
versionId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a EmailSequenceVersionDetailModel.

Field
Type
Description
id
integer (int64)
versionNumber
integer (int32)
createdAt
string (date-time)
createdByUserId
integer (int64)
createdByEmail
string
isRevert
boolean
revertedFromVersionId
integer (int64)
revertedFromVersionNumber
integer (int32)
revertedFromCreatedAt
string (date-time)
snapshot
EmailSequenceSnapshotModel
Request
curl -X GET "https://api.ken.so/v1/segments/812/email-sequence/versions/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "id": 812,
    "versionNumber": 1,
    "createdAt": "2026-09-23T15:02:11Z",
    "createdByUserId": 812,
    "createdByEmail": "[email protected]",
    "isRevert": true,
    "revertedFromVersionId": 812,
    "revertedFromVersionNumber": 1,
    "revertedFromCreatedAt": "2026-09-23T15:02:11Z",
    "snapshot": {
      "schemaVersion": 1,
      "name": "string",
      "isActive": true,
      "steps": [
        {
          "stepOrder": 1,
          "variant": "string",
          "name": "string",
          "subject": "string",
          "body": "string",
          "bodyFormat": "string",
          "waitDays": 1,
          "isActive": true,
          "handwrittenEnabled": true,
          "handwrittenBackground": "string",
          "handwrittenIntro": "string"
        }
      ]
    }
  }
}

Restore a segment email sequence to a saved version

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

Try it on developer.ken.so

A link the URL reputation check refuses is 400 validation_failed with one link_reputation_blocked detail per link; its field is steps.subject or steps.body and stepId is the live step the restore would overwrite. Requires SequenceEditAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
versionId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a SequenceRestoreModel.

Field
Type
Description
newVersionNumber
integer (int32)
versionWarning
string
Request
curl -X POST "https://api.ken.so/v1/segments/812/email-sequence/versions/812/restore" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "newVersionNumber": 1,
    "versionWarning": "string"
  }
}
More in Campaigns and sequences:CampaignsSegmentsEmail sequencesLinkedIn sequencesSegment LinkedIn sequencesSequence variablesCustom variablesImage variablesCampaign imagesListsTracking linksAuto pausesCampaign complianceCampaign languagesCampaign localizationsMarketsAnalyticsAll resources