Skip to Content
Campaigns

Segment email sequences

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

Campaigns9 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
segmentIdpathinteger (int64)requiredThe segment's id.

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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

GET/v1/segments/{segmentId}/email-sequencesegment-email-sequences.get
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

PUT/v1/segments/{segmentId}/email-sequencesegment-email-sequences.replace
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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

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

Errors:

  • 400 validation_failed: a step breaks a sequence rule.
  • 400 validation_failed with link_reputation_blocked details: a link failed the URL reputation check. Each detail has field (steps[i].subject or steps[i].body), rule, url, stepOrder and, for a saved step, stepId.
  • 404 not_found: the segment does not exist in this workspace.
  • 409 conflict with a stale_write detail on expectedModifiedAt: the sequence changed since your read, or it no longer exists.

Requires Campaigns edit.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringoptionalThe sequence's name. Omit it to keep the current name, or to name a new sequence "Email Sequence".
isActivebooleanoptionalWhether the sequence is on. Defaults to true.
stepsarray of ReplaceEmailSequenceStepRequestrequiredEvery 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.
expectedModifiedAtstring (date-time)optionalThe 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.
instructionstringoptionalThe 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.
Request
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

DELETE/v1/segments/{segmentId}/email-sequencesegment-email-sequences.delete
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Preview a segment's email sequence

GET/v1/segments/{segmentId}/email-sequence/previewsegment-email-sequences.preview
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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

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

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

Errors:

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

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
providerTrackquerystringoptionalgoogle, 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.
contactIdqueryinteger (int64)optionalThe id of the contact to preview as. The contact must be in the campaign. Send this or useRandom.
useRandomquerybooleanoptionalSet 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.
languagequerystringoptionalA 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.
senderEmailIdqueryinteger (int64)optionalThe 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.
Request
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

POST/v1/segments/{segmentId}/email-sequence/test-sendsegment-email-sequences.test-send
Permission
Campaigns edit
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

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

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

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

Errors:

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

Requires Campaigns edit.

Request body

application/json, optional.

FieldTypeRequiredDescription
contactIdinteger (int64)requiredThe id of the contact whose details fill the variables. Required, and the contact must be in the campaign.
targetEmailsstringrequiredThe 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.
senderEmailIdinteger (int64)requiredThe 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.
languagestringoptionalA 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.
providerTrackstringoptionalgoogle, 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.
Request
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

GET/v1/segments/{segmentId}/email-sequence/versionssegment-email-sequences.list-versions
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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

Errors:

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

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalVersions per page, from 1 to 100. Defaults to 20.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
Request
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

POST/v1/segments/{segmentId}/email-sequence/versionssegment-email-sequences.save-version
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

Saves a version of the segment's own email sequence that you can restore later. The call does not change the live sequence.

Without sourceVersionId, the version is a copy of the live sequence, and Kenso does not store the name, isActive or steps you send. With sourceVersionId, the version starts from that saved version: name and isActive replace its values when you send them, and a non-empty steps list replaces its steps.

Kenso checks any steps you send with the rules of PUT /v1/segments/{segmentId}/email-sequence, links included, because a restore makes them live.

Errors:

  • 400 validation_failed: a step breaks a sequence rule.
  • 400 validation_failed with link_reputation_blocked details: a link failed the URL reputation check. Each detail has field, rule, url, stepOrder and, for a step you sent with an id, stepId.
  • 404 not_found: the segment does not exist in this workspace, it has no email sequence of its own, or sourceVersionId is not one of that sequence's versions.
  • 409 conflict: another version save for this sequence is running. Retry shortly.

Requires Campaigns edit.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringoptionalThe name to store in the version. Used only with sourceVersionId. Omit it to keep that version's name.
isActivebooleanoptionalWhether the sequence is on, as stored in the version. Used only with sourceVersionId. Omit it to keep that version's value.
stepsarray of ReplaceEmailSequenceStepRequestoptionalThe 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.
sourceVersionIdinteger (int64)optionalThe id of a saved version of this sequence to start from. Omit it to save a copy of the live sequence.
Request
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

GET/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

Try it on developer.ken.so

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

NameInTypeRequiredDescription
versionIdpathinteger (int64)requiredThe version's id, from the list of versions.
Request
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

POST/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

Try it on developer.ken.so

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

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

Errors:

  • 400 validation_failed: the version has no steps while the live sequence has some, or a step breaks today's sequence rules.
  • 400 validation_failed with link_reputation_blocked details: a link failed the URL reputation check. Each detail's field is steps.subject or steps.body, and stepId is the live step the restore would overwrite.
  • 404 not_found: the segment does not exist in this workspace, it has no email sequence of its own, or the version is not one of that sequence's versions.
  • 409 conflict: another version save for this sequence is running. Retry shortly.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
versionIdpathinteger (int64)requiredThe id of the version to restore.
Request
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.


On this page