Skip to Content
Campaigns

Email sequences

A campaign's email sequence: read, replace or delete it, preview it for one contact and send a test.

Campaigns5 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
campaignIdpathinteger (int64)requiredThe campaign'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 campaign's email sequence

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

Try it on developer.ken.so

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.

Request
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

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

Try it on developer.ken.so

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_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 campaign 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/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

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

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Preview a campaign's email sequence

GET/v1/campaigns/{campaignId}/email-sequence/previewemail-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 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.

Parameters

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

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

Try it on developer.ken.so

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, targetEmails has more than 5 addresses or an invalid one, or language is not a language tag.
  • 400 validation_failed with detail invalid_track: providerTrack is not google, microsoft or other.
  • 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.refusal has code FREE_PLAN_SENDING_NEEDS_PLAN and remedy Upgrade: 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.

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


On this page