Email sequences
A campaign's email sequence: read, replace or delete it, preview it for one contact and send a test.
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 |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | The campaign'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 campaign's email sequence
/v1/campaigns/{campaignId}/email-sequenceemail-sequences.get- Permission
- Campaigns view
- Rate limit
- 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.
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"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 campaign's email sequence
/v1/campaigns/{campaignId}/email-sequenceemail-sequences.replace- Permission
- Campaigns edit
- Rate limit
- 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_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 campaign 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/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."
}'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 campaign's email sequence
/v1/campaigns/{campaignId}/email-sequenceemail-sequences.delete- Permission
- Campaigns edit
- Rate limit
- 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.
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"Response 204
HTTP/1.1 204 No ContentPreview a campaign's email sequence
/v1/campaigns/{campaignId}/email-sequence/previewemail-sequences.preview- Permission
- Campaigns view
- Rate limit
- 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: neithercontactIdnoruseRandom=truewas sent, orlanguageis 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
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/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"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 campaign's email sequence
/v1/campaigns/{campaignId}/email-sequence/test-sendemail-sequences.test-send- Permission
- Campaigns edit
- Rate limit
- 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,targetEmailshas more than 5 addresses or an invalid one, orlanguageis not a language tag.400 validation_failedwith detailinvalid_track:providerTrackis notgoogle,microsoftorother.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.refusalhascodeFREE_PLAN_SENDING_NEEDS_PLANandremedyUpgrade: 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.
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/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": "[email protected]",
"senderEmailId": 5530
}'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.
More in Campaigns:CampaignsLinkedIn sequencesSegment email sequencesSegment LinkedIn sequencesSequence variablesSequences with conditionsSequence importSegmentsLead listsShare linksClient approvalsSending capacityAuto-pausesCampaign languagesLocalized stepsText translationMarket packsCountry complianceCampaign imagesAll resources