Segment email sequences
The email sequence of one segment, with preview, test sends and saved versions.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
segmentId | path | integer (int64) | required | The segment's id. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | 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 date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | 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. |
Get a segment's email sequence
/v1/segments/{segmentId}/email-sequencesegment-email-sequences.get- Permission
- Campaigns view
- Rate limit
- 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.
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"Response 200
data is a EmailSequence.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Replace a segment's email sequence
/v1/segments/{segmentId}/email-sequencesegment-email-sequences.replace- Permission
- Campaigns edit
- Rate limit
- 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_failedwithlink_reputation_blockeddetails: a link failed the URL reputation check. Each detail hasfield(steps[i].subjectorsteps[i].body),rule,url,stepOrderand, for a saved step,stepId.404 not_found: the segment does not exist in this workspace.409 conflictwith astale_writedetail onexpectedModifiedAt: the sequence changed since your read, or it no longer exists.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | The sequence's name. Omit it to keep the current name, or to name a new sequence "Email Sequence". |
isActive | boolean | optional | Whether the sequence is on. Defaults to true. |
steps | array of ReplaceEmailSequenceStepRequest | required | 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) | optional | 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 | optional | 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. |
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."
}'Response 200
data is a EmailSequence.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a segment's email sequence
/v1/segments/{segmentId}/email-sequencesegment-email-sequences.delete- Permission
- Campaigns edit
- Rate limit
- 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.
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"Response 204
HTTP/1.1 204 No ContentPreview a segment's email sequence
/v1/segments/{segmentId}/email-sequence/previewsegment-email-sequences.preview- Permission
- Campaigns view
- Rate limit
- 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: neithercontactIdnoruseRandom=truewas sent, orlanguageis not a language tag.400 validation_failedwith detailinvalid_track:providerTrackis notgoogle,microsoftorother.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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
providerTrack | query | string | optional | 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) | optional | The id of the contact to preview as. The contact must be in the campaign. Send this or useRandom. |
useRandom | query | boolean | optional | 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 | optional | 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) | optional | 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. |
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"Response 200
data is a EmailSequencePreview.
Show the 4 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Test a segment's email sequence
/v1/segments/{segmentId}/email-sequence/test-sendsegment-email-sequences.test-send- Permission
- Campaigns edit
- Rate limit
- 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_failedwith detailinvalid_track:providerTrackis notgoogle,microsoftorother.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.refusalhascodeFREE_PLAN_SENDING_NEEDS_PLANandremedyUpgrade: 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.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
contactId | integer (int64) | required | The id of the contact whose details fill the variables. Required, and the contact must be in the campaign. |
targetEmails | string | required | 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) | required | 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 | optional | 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 | optional | 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. |
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": "[email protected]",
"senderEmailId": 5530,
"providerTrack": "google"
}'Response 200
data is a EmailSequenceTestSend.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List a segment's email sequence versions
/v1/segments/{segmentId}/email-sequence/versionssegment-email-sequences.list-versions- Permission
- Campaigns view
- Rate limit
- 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:limitis out of range, orcursoris invalid.404 not_found: the segment does not exist in this workspace, or it has no email sequence of its own.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | Versions per page, from 1 to 100. Defaults to 20. |
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
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"Response 200
data is a list of SequenceVersion. Each item has these fields. The response also carries pagination.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Save a segment's email sequence version
/v1/segments/{segmentId}/email-sequence/versionssegment-email-sequences.save-version- Permission
- Campaigns edit
- Rate limit
- 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_failedwithlink_reputation_blockeddetails: a link failed the URL reputation check. Each detail hasfield,rule,url,stepOrderand, for a step you sent with anid,stepId.404 not_found: the segment does not exist in this workspace, it has no email sequence of its own, orsourceVersionIdis not one of that sequence's versions.409 conflict: another version save for this sequence is running. Retry shortly.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | The name to store in the version. Used only with sourceVersionId. Omit it to keep that version's name. |
isActive | boolean | optional | 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 | optional | 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) | optional | The id of a saved version of this sequence to start from. Omit it to save a copy of the live sequence. |
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
}
]
}'Response 200
data is a EmailSequenceVersionSave.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a segment's email sequence version
/v1/segments/{segmentId}/email-sequence/versions/{versionId}segment-email-sequences.get-version- Permission
- Campaigns view
- Rate limit
- 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
versionId | path | integer (int64) | required | The version's id, from the list of versions. |
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"Response 200
data is a EmailSequenceVersionDetail.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Restore a segment's email sequence version
/v1/segments/{segmentId}/email-sequence/versions/{versionId}/restoresegment-email-sequences.restore-version- Permission
- Campaigns edit
- Rate limit
- 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_failedwithlink_reputation_blockeddetails: a link failed the URL reputation check. Each detail'sfieldissteps.subjectorsteps.body, andstepIdis 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
versionId | path | integer (int64) | required | The id of the version to restore. |
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"Response 200
data is a SequenceRestore.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Campaigns:CampaignsEmail sequencesLinkedIn sequencesSegment LinkedIn sequencesSequence variablesSequences with conditionsSequence importSegmentsLead listsShare linksClient approvalsSending capacityAuto-pausesCampaign languagesLocalized stepsText translationMarket packsCountry complianceCampaign imagesAll resources