{"openapi":"3.0.4","info":{"title":"Kenso API: Email sequences","version":"1.1","description":"The Email sequences endpoints of the Kenso API, with every component they use. The full spec is https://api.ken.so/v1/docs/openapi.json. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`."},"servers":[{"url":"https://api.ken.so"}],"security":[{"Bearer":[]}],"tags":[{"name":"sequences","description":"A sequence is the series of steps Kenso sends to each contact in a campaign: an email sequence holds the emails, and a LinkedIn sequence holds LinkedIn actions timed around those emails. A campaign has one of each, and each segment can have its own, so a segment without its own sequence sends the campaign's. Read and replace either sequence, delete an email sequence, and list the variables subjects and bodies can use with `GET /v1/sequence-variables`. Preview and test send show what a contact will get, and saved versions keep copies you can restore later.","x-displayName":"Sequences"}],"paths":{"/v1/campaigns/{campaignId}/email-sequence":{"get":{"tags":["sequences"],"summary":"Get a campaign's email sequence","description":"Returns the campaign's own email sequence with its steps. Contacts in a segment that has no email sequence of\nits own get this one.\n            \nErrors:\n            \n- `404 not_found`: the campaign does not exist in this workspace, or it has no email sequence.\n            \nRequires Campaigns view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"email-sequences.get","parameters":[{"name":"campaignId","in":"path","description":"The campaign's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSequenceResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"view","summary":"Campaigns view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"put":{"tags":["sequences"],"summary":"Replace a campaign's email sequence","description":"Replaces the campaign's own email sequence with the steps you send, and creates it when the campaign has none.\nSend the `modifiedAt` from your last read as `expectedModifiedAt`, so you do not overwrite an edit made since.\n            \n`steps` is required and is the whole list. A step with the `id` of an existing step updates that step, and a\nstep without an `id` is new. Kenso deletes the existing steps you leave out and drops a step whose `id` is not on\nthis sequence. An empty list deletes every step.\n            \n`steps` holds at most 30 entries. `stepOrder` starts at 1, each `stepOrder` and `variant` pair appears once,\nand each `stepOrder` needs at least one active variant. Variants of one step must differ in subject or body.\nEach `{variable}` must be one that `GET /v1/sequence-variables` lists for the campaign.\n            \nKenso runs every link through its URL reputation check and every step through its content policy.\n`contentWarnings` in the response lists the content policy findings. When the workspace needs client approval\nof copy, the change goes to the client, and Kenso pauses a sending campaign until the client approves it.\n            \nErrors:\n            \n- `400 validation_failed`: a step breaks a rule above.\n- `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`.\n- `404 not_found`: the campaign does not exist in this workspace.\n- `409 conflict` with a `stale_write` detail on `expectedModifiedAt`: the sequence changed since your read, or it no longer exists.\n            \nRequires Campaigns edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.","operationId":"email-sequences.replace","parameters":[{"name":"campaignId","in":"path","description":"The campaign's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceEmailSequenceRequest"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSequenceResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"409":{"description":"The sequence changed since your read, or it no longer exists: `conflict` with a `stale_write` detail on `expectedModifiedAt`. Read the sequence again and resend.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["conflict"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}},"delete":{"tags":["sequences"],"summary":"Delete a campaign's email sequence","description":"Deletes the campaign's own email sequence and its steps. Segments that have their own email sequence keep it.\nWhen the workspace needs client approval of copy, Kenso pauses a sending campaign until the client approves\nthe change.\n            \nErrors:\n            \n- `404 not_found`: the campaign does not exist in this workspace, or it has no email sequence.\n            \nRequires Campaigns edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.","operationId":"email-sequences.delete","parameters":[{"name":"campaignId","in":"path","description":"The campaign's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"No Content","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/campaigns/{campaignId}/email-sequence/preview":{"get":{"tags":["sequences"],"summary":"Preview a campaign's email sequence","description":"Shows each step of the campaign's email sequence as Kenso would send it to one contact, with the variables\nfilled in. Pass `contactId`, or `useRandom=true` to pick a random contact of the campaign.\n            \nA contact whose language has an approved translation sees that translation, with its `language`, the English\n`mirrorSubject` and `mirrorBody`, and `qaScore`. Pass `language` to preview as a contact in that language.\n            \nPass `senderEmailId` to preview from one of the campaign's inboxes, as a test send from it would look: its\nnames, signature and unsubscribe link fill the steps. Without it, or with an inbox the campaign does not use,\nKenso uses the campaign's first inbox by email address. `sender` names the inbox used.\n            \nErrors:\n            \n- `400 validation_failed`: neither `contactId` nor `useRandom=true` was sent, or `language` is not a language tag.\n- `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.\n            \nRequires Campaigns view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"email-sequences.preview","parameters":[{"name":"campaignId","in":"path","description":"The campaign's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"contactId","in":"query","description":"The id of the contact to preview as. The contact must be in the campaign. Send this or `useRandom`.","schema":{"type":"integer","format":"int64"}},{"name":"useRandom","in":"query","description":"Set to true to preview as a random contact of the campaign, or of the segment for a segment preview. Kenso\nignores it when you pass `contactId`. Defaults to false.","schema":{"type":"boolean"}},{"name":"language","in":"query","description":"A language or locale tag, such as `fr` or `fr-FR`. The preview shows the steps as a contact in that language\nwould get them. Omit it to use the contact's own language. The campaign's source language shows the original\ntext.","schema":{"type":"string"}},{"name":"senderEmailId","in":"query","description":"The id of the inbox to preview from. Its names, signature and unsubscribe link fill the steps. When you omit it,\nor it is not one of the campaign's inboxes, Kenso uses the campaign's first inbox by email address.","schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSequencePreviewResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"view","summary":"Campaigns view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/campaigns/{campaignId}/email-sequence/test-send":{"post":{"tags":["sequences"],"summary":"Test a campaign's email sequence","description":"Sends the campaign's email sequence to up to 5 addresses, filled with one contact's data, so you can check the\nemails in a real inbox. Kenso sends every step and variant that has a subject or body, in step order, from the\ninbox in `senderEmailId`.\n            \n`contactId`, `targetEmails` and `senderEmailId` are required. The contact must be in the campaign. Once the\ncampaign has inboxes, `senderEmailId` must be one of them. Each step goes out in the contact's language, or in\n`language` when you send it. `notes` lists steps that went out differently from the step as written, such as an\napproved translation or a handwritten letter sent as normal text.\n            \nEach address and step pair counts as one email against the workspace's daily test send limit. When some\nemails fail, the call still answers `200`: read `emailsSent` and `failures`.\n            \n`providerTrack` (`google`, `microsoft` or `other`) tests the email as that provider track sends it: recipients\non Google get plain text. Ignored when the campaign is not on provider tracks.\n            \nErrors:\n            \n- `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.\n- `400 validation_failed` with detail `invalid_track`: `providerTrack` is not `google`, `microsoft` or `other`.\n- `400 validation_failed`: an address is on the workspace blocklist or has hard bounced.\n- `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.\n- `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.\n- `404 not_found`: the campaign does not exist in this workspace, or the contact is not in the campaign.\n- `429 rate_limited`: the workspace has used its test emails for today.\n            \nRequires Campaigns edit.\n\nRate limit: 200 calls a minute per API key, on top of the workspace limits.","operationId":"email-sequences.test-send","parameters":[{"name":"campaignId","in":"path","description":"The campaign's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestSendSequenceRequest"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSequenceTestSendResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"402":{"description":"Payment Required","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["free_plan_sending_needs_plan"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":200,"windowSeconds":60,"per":"api_key"}}}},"components":{"securitySchemes":{"Bearer":{"type":"http","description":"Enter: Bearer {your Kenso API key}. Create one in the Kenso app under Settings > Integrations > API Keys.","scheme":"bearer","bearerFormat":"Opaque API key"}},"headers":{"RateLimit-Limit":{"description":"The request limit of the rate limit this request is closest to reaching: your plan's limit for this kind of call, your API key's own limit, or the operation's own limit, whichever has the fewest requests left.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The requests left under that limit. `0` on a `429`.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The seconds until that limit resets.","schema":{"type":"integer"}}},"schemas":{"ApiKeyError":{"required":["error"],"type":"object","properties":{"error":{"type":"string","description":"A sentence for people that says what went wrong. It can change, so do not parse it."}},"additionalProperties":false,"description":"The body the API key check in front of the operations answered until November 2026, instead of the error body (`Failure`): `{ \"error\": \"Invalid or revoked API key\" }` on a `401`, `{ \"error\": \"Rate limit exceeded\" }` on a `429` and `{ \"error\": \"Authentication is temporarily unavailable\" }` on a `503`. It has no `code`, so branch on the HTTP status."},"EmailSequence":{"type":"object","properties":{"id":{"type":"integer","description":"The email sequence's id.","format":"int64"},"campaignId":{"type":"integer","description":"The id of the campaign the sequence belongs to.","format":"int64"},"segmentId":{"type":"integer","description":"The id of the segment that owns the sequence. Null for the campaign's own sequence.","format":"int64","nullable":true},"name":{"type":"string","description":"The sequence's name."},"isActive":{"type":"boolean","description":"Whether the sequence is on."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/EmailSequenceStep"},"description":"Every step and variant of the sequence, in step order."},"createdAt":{"type":"string","description":"When the sequence was created, in UTC (ISO 8601).","format":"date-time"},"modifiedAt":{"type":"string","description":"When the sequence last changed, in UTC (ISO 8601). Send it as `expectedModifiedAt` on your next replace so you\ndo not overwrite someone else's change.","format":"date-time"},"contentWarnings":{"type":"array","items":{"$ref":"#/components/schemas/EmailSequenceContentWarning"},"description":"What Kenso's content checks found in the steps you saved, such as a link whose text names another site. Only a\nreplace response with findings carries it. Omitted otherwise.","nullable":true}},"additionalProperties":false,"description":"The emails Kenso sends to each contact of a campaign or segment, in step order. A step can have up to four\nvariants for A/B testing.","example":{"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 {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}],"createdAt":"2026-09-23T15:02:11Z","modifiedAt":"2026-10-14T09:41:27Z"}},"EmailSequenceContentWarning":{"type":"object","properties":{"stepOrder":{"type":"integer","description":"The `stepOrder` of the step the finding is about.","format":"int32"},"variant":{"type":"string","description":"The variant of the step the finding is about: `a`, `b`, `c` or `d`."},"code":{"type":"string","description":"The rule that found it, as a stable snake_case code such as `link_host_mismatch` (a link's text is a web\naddress that differs from where the link goes)."},"severity":{"type":"string","description":"How serious the finding is: `warning`, `hard_warning` or `block`, from least to most serious."},"path":{"type":"string","description":"The part of the step the finding is about, such as `subject` or `body.links`."},"message":{"type":"string","description":"A sentence that explains the finding."},"policyVersion":{"type":"string","description":"The version of the content rules that produced the finding."}},"additionalProperties":false,"description":"One finding of Kenso's content checks on a saved email step."},"EmailSequencePreview":{"type":"object","properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/EmailSequencePreviewStep"},"description":"Every step and variant of the sequence, inactive ones included, in step order."},"contact":{"allOf":[{"$ref":"#/components/schemas/EmailSequencePreviewContact"}],"description":"The contact the preview is filled in for."},"sender":{"allOf":[{"$ref":"#/components/schemas/EmailSequencePreviewSender"}],"description":"The mailbox whose names, signature and domain fill the preview: the `senderEmailId` you passed when it is one\nof the campaign's mailboxes, else the first in `senders`. Omitted when the campaign has no mailboxes."},"senders":{"type":"array","items":{"$ref":"#/components/schemas/EmailSequencePreviewSender"},"description":"Up to 50 of the campaign's mailboxes, ordered by email address. The mailbox you passed as `senderEmailId` is\nalways included. Empty when the campaign has no mailboxes."}},"additionalProperties":false,"description":"An email sequence filled in for one contact, the way Kenso would send it.","example":{"steps":[{"stepNumber":1,"subject":"Onboarding new engineers at Northwind Labs","body":"Hi Amanda,\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\nAlex","waitDays":0,"variables":[{"name":"firstName","type":"lead_variable","value":"Amanda"},{"name":"company","type":"lead_variable","value":"Northwind Labs"},{"name":"sender_first_name","type":"system_variable","value":"Alex"}]},{"stepNumber":2,"subject":"","body":"Hi Amanda, following up on this. Happy to send a 2-minute video instead if that is easier.\n\nAlex","waitDays":3,"variables":[{"name":"firstName","type":"lead_variable","value":"Amanda"},{"name":"sender_first_name","type":"system_variable","value":"Alex"}]}],"contact":{"id":90125,"fullName":"Amanda Chen","company":"Northwind Labs","title":"VP of Engineering","email":"amanda.chen@northwind.example.com"},"sender":{"id":5530,"email":"alex@mail.example.com","status":"active","warmupReputation":98,"healthScore":94},"senders":[{"id":5530,"email":"alex@mail.example.com","status":"active","warmupReputation":98,"healthScore":94}]}},"EmailSequencePreviewContact":{"type":"object","properties":{"id":{"type":"integer","description":"The contact's id.","format":"int64"},"fullName":{"type":"string","description":"The contact's full name.","nullable":true},"company":{"type":"string","description":"The name of the contact's company. Omitted when unknown.","nullable":true},"title":{"type":"string","description":"The contact's job title. Omitted when unknown.","nullable":true},"email":{"type":"string","description":"The address Kenso would send to. Omitted when the contact has no address Kenso can send to.","nullable":true}},"additionalProperties":false,"description":"The contact a preview is filled in for."},"EmailSequencePreviewResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/EmailSequencePreview"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"EmailSequencePreviewSender":{"type":"object","properties":{"id":{"type":"integer","description":"The mailbox's id, the value to pass as `senderEmailId`.","format":"int32"},"email":{"type":"string","description":"The mailbox's email address."},"status":{"type":"string","description":"The mailbox's state: `active`, `warmup`, `disconnected`, `paused`, `banned`, `connection_error`, `deleted`,\n`inactive`, `replaced` or `pending_provisioning`."},"warmupReputation":{"type":"integer","description":"The mailbox's reputation from its latest warmup data. Omitted when there is none.","format":"int32","nullable":true},"healthScore":{"type":"number","description":"The mailbox's health score, from its delivery score or else its latest warmup score. Omitted when neither is known.","format":"double","nullable":true}},"additionalProperties":false,"description":"A mailbox the campaign sends from."},"EmailSequencePreviewStep":{"type":"object","properties":{"stepNumber":{"type":"integer","description":"The step's `stepOrder`. Variants of one step share it.","format":"int32"},"subject":{"type":"string","description":"The subject as the contact would get it, with spintax picked and variables filled in. An AI variable with no\nvalue shows a placeholder in brackets."},"body":{"type":"string","description":"The body as the contact would get it, with spintax picked, variables filled in and tracked links shown as their\ntarget URLs. The unsubscribe link is a sample that unsubscribes nobody."},"waitDays":{"type":"integer","description":"Days Kenso waits after the previous step is sent before it sends this one.","format":"int32"},"variables":{"type":"array","items":{"$ref":"#/components/schemas/EmailSequencePreviewVariable"},"description":"The variables found in the subject and body, with what Kenso filled in."},"language":{"type":"string","description":"The language tag of the approved translation the contact gets, such as `fr-FR`. Omitted when the contact gets\nthe text as written.","nullable":true},"mirrorSubject":{"type":"string","description":"An English translation of the translated subject, filled in like `subject`. Only set with `language`.","nullable":true},"mirrorBody":{"type":"string","description":"An English translation of the translated body, filled in like `body`. Only set with `language`.","nullable":true},"qaScore":{"type":"integer","description":"The quality score Kenso gave the translation, from 0 to 100. Only set with `language`.","format":"int32","nullable":true},"sendsPlainText":{"type":"boolean","description":"Segment previews only: true when this step goes out as plain text for the requested provider track.","nullable":true}},"additionalProperties":false,"description":"One step and variant filled in for the contact."},"EmailSequencePreviewVariable":{"type":"object","properties":{"name":{"type":"string","description":"The variable's name as written in the step."},"type":{"type":"string","description":"The kind of variable: `lead_variable`, `ai_variable` or `system_variable`."},"value":{"type":"string","description":"The value Kenso filled in. Omitted when there is none.","nullable":true},"placeholder":{"type":"string","description":"The text the preview shows in place of an AI variable that has no value yet, such as\n`[name - Not available]`. Omitted otherwise.","nullable":true},"lineId":{"type":"integer","description":"The id of the lead's AI line whose text `value` shows, the same id the contact's AI lines list. Omitted for every\nother value: lead fields, the lead's own custom variables, placeholders and prompt defaults.","format":"int64","nullable":true}},"additionalProperties":false,"description":"A variable found in a step, and what Kenso filled in for it."},"EmailSequenceResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/EmailSequence"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"EmailSequenceStep":{"type":"object","properties":{"id":{"type":"integer","description":"The step's id. Send it back in a replace to update this step.","format":"int64"},"campaignId":{"type":"integer","description":"The campaign whose email sequence holds this step. Omitted on sequence reads, which carry it on the sequence.","format":"int64","nullable":true},"stepOrder":{"type":"integer","description":"The step's position in the sequence, starting at 1. The variants of one step share it.","format":"int32"},"variant":{"type":"string","description":"The variant of the step for A/B testing: `a`, `b`, `c` or `d`."},"name":{"type":"string","description":"A label for the step. Null when none is set.","nullable":true},"subject":{"type":"string","description":"The subject line, with variables such as `{firstName}` not yet filled in. An empty subject on step 2 or later\nsends the email as a reply in the thread of the previous email."},"body":{"type":"string","description":"The email body, with variables not yet filled in. `bodyFormat` says how to read it."},"bodyFormat":{"type":"string","description":"How `body` is written: `plain`, `markdown` or `html`."},"waitDays":{"type":"integer","description":"Days Kenso waits after the previous step is sent before it sends this step. Step 1 ignores it and is usually 0.","format":"int32"},"isActive":{"type":"boolean","description":"Whether Kenso sends this variant. An inactive variant is kept but not sent."},"openTrackingEnabled":{"type":"boolean","description":"Stored and returned for compatibility; it does not affect sending. The campaign's `trackOpens` decides whether a\nsend carries the open pixel."},"handwrittenEnabled":{"type":"boolean","description":"Whether Kenso sends the letter part of the body as an image of a handwritten letter. The letter part is the\nbody above the sender signature or the unsubscribe link."},"handwrittenBackground":{"type":"string","description":"The paper behind the handwritten letter: `walnut`, `linen`, `kraft`, `marble`, `deckle` or `notepad`. Null\nmeans `walnut`.","nullable":true},"handwrittenIntro":{"type":"string","description":"The line of normal text above the handwritten letter. Null means Kenso's default line, which names the\ncontact and the sender.","nullable":true},"warnings":{"type":"array","items":{"type":"string"},"description":"Advice about this step that never stops a save. An `html` step can carry `html_on_mailbox_inbox` (the campaign\nsends from a Google or Microsoft mailbox), `html_size_near_cap` (the body is over 80% of the size limit) and\n`html_external_image:<host>` (an image loads from another site). A replace response can add\n`html_removed:<what>` for markup Kenso removed, and `studio_pin_removed` on any step whose Studio email\nthe replace unpinned. Null when there is nothing to report.","nullable":true},"studioTemplateVersionId":{"type":"integer","description":"The Studio email version this step sends, filled in for each contact. Null when the step does not send a\nStudio email.","format":"int64","nullable":true},"studioPin":{"allOf":[{"$ref":"#/components/schemas/StudioPin"}],"description":"The state of the Studio email this step sends. Null when the step does not send one."}},"additionalProperties":false,"description":"One variant of one email step in a sequence."},"EmailSequenceTestSend":{"type":"object","properties":{"stepsSent":{"type":"integer","description":"Steps that reached every address in `targetEmails`. Each variant counts as a step.","format":"int32"},"emailsAttempted":{"type":"integer","description":"Emails Kenso tried to send, at most one per step and address.","format":"int32"},"emailsSent":{"type":"integer","description":"Emails that went out.","format":"int32"},"sentTo":{"type":"array","items":{"type":"string"},"description":"The addresses that got at least one email, in alphabetical order."},"failures":{"type":"array","items":{"type":"string"},"description":"One message for each email or step that did not go out. Each message starts with the step number."},"notes":{"type":"array","items":{"type":"string"},"description":"Notes on emails that went out differently from the step as written, such as a handwritten letter sent as\nnormal text. These emails did go out."}},"additionalProperties":false,"description":"The result of a test send.","example":{"stepsSent":2,"emailsAttempted":2,"emailsSent":2,"sentTo":["jordan.patel@northwind-outbound.example.com"],"failures":[],"notes":[]}},"EmailSequenceTestSendResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/EmailSequenceTestSend"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"ErrorAccount":{"type":"object","properties":{"accountId":{"type":"integer","description":"The account's id.","format":"int64"},"name":{"type":"string","description":"The account's name."},"stakeholderId":{"type":"integer","description":"The person's stakeholder id on this account.","format":"int64"}},"additionalProperties":false,"description":"An account named in an error detail."},"ErrorBody":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code, such as `validation_failed` or `not_found`. Branch on this value."},"message":{"type":"string","description":"A sentence for people that explains the error. It can change, so do not parse it."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"},"description":"One entry per problem, naming the field or limit it is about. Omitted when there are none.","nullable":true},"requestId":{"type":"string","description":"The id of this request: the same value as the `X-Correlation-Id` response header. Quote it when you write\nto contact@ken.so."},"docUrl":{"type":"string","description":"The page on this code in the developer docs, which says what it means and how to fix it. The errors guide for a\ncode that has no page of its own.","readOnly":true},"refusal":{"allOf":[{"$ref":"#/components/schemas/Refusal"}],"description":"On a `402`, the plan rule or usage limit that refused the request and how to lift it. Omitted otherwise."},"impact":{"allOf":[{"$ref":"#/components/schemas/InvalidationImpact"}],"description":"On a `409` that refuses a change because it would clear stored AI output (a prompt edit, a restore or a\nreset), how much the change would clear. Omitted otherwise."},"surface":{"type":"string","description":"Set only by the voice ticket's `409` (code `voice_conversation_active`): the chat the person's other\nvoice conversation runs in, `support`, `ken` or `onboarding`. Omitted on every other error.","nullable":true}},"additionalProperties":false,"description":"What went wrong in a request."},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","description":"The request field, header or limit the problem is about, such as `name` or `Ken-Version`."},"code":{"type":"string","description":"Stable code for this problem, such as `required` or `invalid`."},"message":{"type":"string","description":"A sentence for people that explains this problem."},"count":{"type":"integer","description":"On `export_limit_exceeded`, how many rows match the export. Omitted otherwise.","format":"int32","nullable":true},"index":{"type":"integer","description":"The position of the refused item in the request's list. Omitted otherwise.","format":"int32","nullable":true},"limit":{"type":"integer","description":"On `export_limit_exceeded`, the row limit the export ran with. On a `quota_exceeded` detail whose\n`field` names a quota, that quota's limit. On a `rate_limited` detail from your workspace's rate\nlimits, the limit that was hit. Omitted otherwise.","format":"int32","nullable":true},"resetAt":{"type":"string","description":"On some `quota_exceeded` details, when the quota frees up, in UTC. It is the same instant as the top-level\n`quotaResetAt`. On a `rate_limited` detail from your workspace's rate limits, when that limit resets.\nOmitted otherwise.","format":"date-time","nullable":true},"retryAfterSeconds":{"type":"integer","description":"On those `quota_exceeded` details and on most `rate_limited` details, the seconds to wait. It is the\nsame value as the `Retry-After` header. Omitted otherwise.","format":"int32","nullable":true},"inboxId":{"type":"integer","description":"The inbox the problem is about. Omitted otherwise.","format":"int64","nullable":true},"domainId":{"type":"integer","description":"The domain the problem is about. Omitted otherwise.","format":"int64","nullable":true},"domainName":{"type":"string","description":"The name of that domain, or the domain name the request gave. Omitted otherwise.","nullable":true},"accountId":{"type":"integer","description":"On `domain_taken`, `already_stakeholder` and `previously_removed`, the existing account to use\ninstead. Omitted otherwise.","format":"int64","nullable":true},"personId":{"type":"integer","description":"On `email_taken` and `linkedin_url_taken`, the existing person to use instead. Omitted otherwise.","format":"int64","nullable":true},"stakeholderId":{"type":"integer","description":"The account stakeholder the problem is about. Omitted otherwise.","format":"int64","nullable":true},"championId":{"type":"integer","description":"Not used. Always omitted.","format":"int64","nullable":true},"callTaskId":{"type":"integer","description":"On `call_task_exists`, the open call task that already holds the person's slot. Omitted otherwise.","format":"int64","nullable":true},"status":{"type":"string","description":"On `invalid_transition`, the current status. Omitted otherwise.","nullable":true},"allowed":{"type":"array","items":{"type":"string"},"description":"On `out_of_range`, the allowed values. On `invalid_transition`, the statuses the change is allowed\nfrom. Omitted otherwise.","nullable":true},"scope":{"type":"string","description":"On a `permission_denied` for an account owner change, the account scope the call needs (`all`). On\n`sending_paused`, what the pause covers: `inbox`, `domain` or `workspace`. Omitted otherwise.","nullable":true},"removedAt":{"type":"string","description":"On `previously_removed`, when a person removed the stakeholder, in UTC. Omitted otherwise.","format":"date-time","nullable":true},"page":{"type":"string","description":"On `permission_denied`, the page the call needs, such as `campaigns`. Omitted otherwise.","nullable":true},"required":{"type":"string","description":"On `permission_denied`, the access `page` needs: `view` or `edit`. Omitted otherwise.","nullable":true},"feature":{"type":"string","description":"On `permission_denied`, the permission the call needs, such as `launch`. Omitted otherwise.","nullable":true},"runId":{"type":"integer","description":"On `committee_run_active` and `run_not_finding`, the committee run the problem is about. Omitted\notherwise.","format":"int64","nullable":true},"mergedIntoId":{"type":"integer","description":"On `person_merged`, the person the merged person now lives on. On `account_merged`, the account the\nmerged account now lives on. Omitted otherwise.","format":"int64","nullable":true},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ErrorAccount"},"description":"On `person_on_accounts`, the accounts that block the change. Omitted otherwise.","nullable":true},"stage":{"type":"string","description":"On `stage_in_use` and `system_stage`, the opportunity stage key the problem is about. Omitted otherwise.","nullable":true},"opportunityCount":{"type":"integer","description":"On `stage_in_use`, how many opportunities are in that stage. Omitted otherwise.","format":"int32","nullable":true},"rule":{"type":"string","description":"On `guardrail_violation`, the contact limit rule the change breaks. Omitted otherwise.","nullable":true},"nextAllowedAt":{"type":"string","description":"On `guardrail_violation`, the first `dueAt` that passes every contact limit, in UTC. On a refused\nsend, when to retry. Omitted otherwise, and when waiting does not clear it.","format":"date-time","nullable":true},"fix":{"type":"string","description":"On a refused send, what to do next, in plain words. Omitted otherwise.","nullable":true},"opensAt":{"type":"string","description":"On `outside_calling_hours`, when the person's calling window opens, in UTC. Omitted otherwise.","format":"date-time","nullable":true},"currentVersion":{"type":"integer","description":"On a knowledge file's `version_conflict`, the file's current version. Omitted otherwise.","format":"int32","nullable":true},"provider":{"type":"string","description":"On a CRM connection error (`provider_error`, `exchange_failed`, `already_connected`,\n`account_mismatch` or `provider_unavailable`), the CRM it is about. Omitted otherwise.","nullable":true},"sharedWithMaster":{"type":"boolean","description":"True on a `quota_exceeded` detail when the shared limit of the white-label master workspace was hit, so\n`limit` is the limit of the whole white-label account. Omitted otherwise. The master's id is never sent.","nullable":true},"stepId":{"type":"integer","description":"On `link_reputation_blocked`, the saved sequence step that holds the blocked link. Omitted otherwise, and\nfor a step the save would have created.","format":"int64","nullable":true},"stepOrder":{"type":"integer","description":"On `link_reputation_blocked`, the `stepOrder` of that step. Omitted otherwise.","format":"int32","nullable":true},"url":{"type":"string","description":"On `link_reputation_blocked`, the blocked link as the step's copy writes it. Omitted otherwise.","nullable":true},"key":{"type":"string","description":"On `unfilled_template_key`, the template key the text still holds, such as `first_name` for\n`{first_name}`. Omitted otherwise.","nullable":true},"marker":{"type":"string","description":"On `unfilled_template_key`, that key as the text writes it, such as `{first_name}` or `[company]`.\nOmitted otherwise.","nullable":true},"retryAt":{"type":"string","description":"On a warm path Start's `guardrail_connector_monthly`, `guardrail_account_monthly`,\n`guardrail_connector_cooldown` and `guardrail_handoff_weekly`, when the limit frees up, in UTC. Omitted\notherwise.","format":"date-time","nullable":true},"workspaceId":{"type":"integer","description":"On `last_admin`, a workspace that needs a new admin before the account can be deleted. On\n`new_admin_not_found`, the workspace of the refused choice. Omitted otherwise.","format":"int64","nullable":true},"workspaceName":{"type":"string","description":"On `last_admin`, the name of that workspace. Omitted otherwise.","nullable":true},"class":{"type":"string","description":"On a `rate_limited` detail from your workspace's rate limits, the class of call that hit its limit:\n`read`, `write`, `bulk`, `heavy` or `sensitive`. Omitted otherwise.","nullable":true},"window":{"type":"string","description":"On that detail, the window whose limit was hit: `minute`, `day` or `bulkItemsDay`. Omitted\notherwise.","nullable":true}},"additionalProperties":false,"description":"One problem in an error: the field or limit it is about, a stable `code` and a `message`. The other fields\nappear only with the codes their descriptions name."},"Failure":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false on an error."},"error":{"allOf":[{"$ref":"#/components/schemas/ErrorBody"}],"description":"What went wrong."},"quotaResetAt":{"type":"string","description":"When the quota that refused the request frees up, in UTC. Set on some quota refusals. Omitted otherwise.","format":"date-time","nullable":true},"currentVersion":{"type":"integer","description":"The current revision of a workflow draft, on a draft save's `409 version_conflict`. Read the workflow\nagain, then send this value as `baseVersion`. Omitted otherwise.","format":"int32","nullable":true},"current":{"allOf":[{"$ref":"#/components/schemas/MeetingRepNotesCurrent"}],"description":"Your meeting notes and their version as stored now, on a meeting notes save's `409 version_conflict`.\nMerge your change, then save again with `baseVersion` set to `current.repNotesVersion`. Omitted\notherwise."},"refusal":{"allOf":[{"$ref":"#/components/schemas/Refusal"}],"description":"A copy of `error.refusal`, set on some billing refusals. Omitted otherwise."},"message":{"type":"string","description":"A copy of `error.message`, set together with `refusal`. Omitted otherwise.","nullable":true},"lookalikeSeeds":{"description":"How Kenso read each seed of a lookalike search, on its `422 no_usable_seeds`:\n`{resolved: [{input, companyId, personId, name, domain}], unresolved: [{input, reason}]}`. Use it to show\nwhy no seed was usable. Omitted otherwise."}},"additionalProperties":false,"description":"The body of every error, with a 4xx or 5xx status. Branch on `error.code`."},"InvalidationImpact":{"type":"object","properties":{"qualificationResponses":{"type":"integer","description":"Stored qualification answers the change would clear.","format":"int32"},"qualifiedFlags":{"type":"integer","description":"Contacts whose qualified result the change would clear.","format":"int32"},"segmentationReasoning":{"type":"integer","description":"Stored segmentation explanations the change would clear.","format":"int32"},"segmentationAssignmentsKept":{"type":"integer","description":"Contacts that keep their segment.","format":"int32"},"segmentationAssignmentsReset":{"type":"integer","description":"Contacts that go back to the default segment.","format":"int32"},"personalizationLines":{"type":"integer","description":"Personalized lines the change would clear.","format":"int32"},"personalizationLeads":{"type":"integer","description":"Contacts that would lose their personalized lines.","format":"int32"},"rewritingLines":{"type":"integer","description":"Rewritten lines the change would clear.","format":"int32"},"rewritingLeads":{"type":"integer","description":"Contacts that would lose their rewritten lines.","format":"int32"}},"additionalProperties":false,"description":"How much stored AI output a change would clear in each AI step of a campaign, and how many segment assignments it\nkeeps or resets."},"MeetingRepNotesCurrent":{"type":"object","properties":{"repNotes":{"type":"string","description":"Your notes as stored now. Empty before your first save."},"repNotesVersion":{"type":"integer","description":"The stored notes' version. Send it as `baseVersion` when you save again.","format":"int32"}},"additionalProperties":false,"description":"Your meeting notes as Kenso stores them now, sent with a `409 version_conflict` on a notes save."},"RateLimitedText":{"type":"string","description":"The gateway's plain-text body of a `429` over the operation's own limit, until November 2026: `Number of requests exceeded. Please try again later.`","example":"Number of requests exceeded. Please try again later."},"Refusal":{"type":"object","properties":{"code":{"type":"string","description":"Stable refusal code in upper case, such as `CAMPAIGN_LIMIT_REACHED` or `INSUFFICIENT_CREDITS`."},"metric":{"type":"string","description":"What the limit counts: `Campaigns`, `Leads`, `Emails`, `LinkedInSeats` or `AiCredits`,\n`jobs_export_rows` or `funding_export_rows` for an export allowance, `credit_pack_credits`,\n`credit_spend_usd_7d`, `domains` or `mailboxes` for a limit on a new paying workspace, or for a\nKenso Lifetime cap its key: `workspaces`, `inboxes`, `contacts`, `email_verifications_day`,\n`email_verifications_month`, `people_results_day`, `company_results_day`,\n`funding_results_day`, `job_post_results_day`, `website_visits_month` or\n`visitor_lookups_day`. Omitted when a plan rule, not a count, refused the request.","nullable":true},"used":{"type":"integer","description":"How much of the limit is used, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"limit":{"type":"integer","description":"The limit, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"remaining":{"type":"integer","description":"How much of the limit is left, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"planType":{"type":"string","description":"The workspace's plan as its snake plan id, for example `free`, `legacy_core` or `growth`."},"remedy":{"type":"string","description":"What lifts the refusal: `Upgrade`, `BuyAddOn`, `UpdatePaymentMethod` or `ContactSupport`.\n`None` means no action of yours lifts it."},"unlocksAt":{"type":"string","description":"When the limit lifts by itself, in UTC: for a limit on a new paying workspace once it has paid an invoice, and for\na Kenso Lifetime daily or monthly cap its reset (00:00 UTC, or the 1st of the month). Omitted on every other\nrefusal.","format":"date-time","nullable":true},"requiredMillicredits":{"type":"integer","description":"On a credit refusal, the millicredits the action needed. 1,000 millicredits are one credit. Omitted on every\nother refusal.","format":"int64","nullable":true},"availableMillicredits":{"type":"integer","description":"On a credit refusal, the millicredits available. On `FREE_CREDITS_NOT_ELIGIBLE`, only the credits that may\npay for inboxes and domains. Omitted on every other refusal.","format":"int64","nullable":true},"restrictedMillicredits":{"type":"integer","description":"On `FREE_CREDITS_NOT_ELIGIBLE`, the free and bonus millicredits in the balance that cannot pay for inboxes\nand domains. Omitted on every other refusal.","format":"int64","nullable":true},"feature":{"type":"string","description":"On `PLAN_FEATURE_NOT_AVAILABLE`, the plan feature the plan does not include, in snake case (for example\n`website_visitor_id`). Omitted on every other refusal.","nullable":true},"requiredPlan":{"type":"string","description":"On `PLAN_FEATURE_NOT_AVAILABLE`, the cheapest plan that includes `feature`, in snake case (for example\n`growth`). For a feature the self-serve trial locks (`browser_runs`), the trial's own plan,\nwhich paying for unlocks it. Omitted on every other refusal.","nullable":true},"requiredTier":{"type":"integer","description":"On a Kenso Lifetime refusal, the lowest tier that lifts it: the next tier with a higher cap, or the lowest tier\nthat includes `feature`. Omitted at the top tier, when no tier includes the feature, and on every other\nrefusal.","format":"int32","nullable":true},"upgradeUrl":{"type":"string","description":"On a Kenso Lifetime refusal that a higher tier lifts, the AppSumo page where the buyer upgrades their license.\nOmitted until Kenso has read that page from AppSumo, when no tier lifts the refusal, and on every other refusal.","nullable":true}},"additionalProperties":false,"description":"Why a plan rule or usage limit refused the request, and how to lift it."},"ReplaceEmailSequenceRequest":{"required":["steps"],"type":"object","properties":{"name":{"type":"string","description":"The sequence's name. Omit it to keep the current name, or to name a new sequence \"Email Sequence\".","nullable":true},"isActive":{"type":"boolean","description":"Whether the sequence is on. Defaults to true."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/ReplaceEmailSequenceStepRequest"},"description":"Every step and variant the sequence should have, at most 30 entries. Required. A step with an `id` updates\nthat step, a step without one is added, and existing steps you leave out are deleted. An empty list deletes\nevery step."},"expectedModifiedAt":{"type":"string","description":"The `modifiedAt` from your last read, in UTC (ISO 8601), compared to the second. When the sequence changed\nsince then, Kenso refuses the replace with `409 conflict` and a `stale_write` detail, so you do not overwrite\nsomeone else's change. Omit it to replace without the check.","format":"date-time","nullable":true},"instruction":{"type":"string","description":"The person's request that led to this change, in their own words when you have them. Optional. Kenso keeps it\nwith the edit history of the steps this save changes, marked as reported by your agent, and keeps the first\n2,000 characters. Leave it out when no person asked for the change; never invent one.","nullable":true}},"additionalProperties":false,"description":"The whole email sequence to save. The steps you send replace every step of the sequence.","example":{"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."}},"ReplaceEmailSequenceStepRequest":{"type":"object","properties":{"id":{"type":"integer","description":"The id of the step to update. Omit it to add a new step. Kenso skips a step whose id is not in this sequence.","format":"int64","nullable":true},"stepOrder":{"type":"integer","description":"The step's position, starting at 1. Each `stepOrder` and `variant` pair can appear once, and each `stepOrder`\nneeds at least one active variant.","format":"int32"},"variant":{"type":"string","description":"The variant for A/B testing: `a`, `b`, `c` or `d`. Defaults to `a`. The variants of one step cannot be\nidentical.","nullable":true},"name":{"type":"string","description":"A label for the step. Omit it to leave the step without one.","nullable":true},"subject":{"type":"string","description":"The subject line. A variable in single braces, such as `{firstName}`, must be a contact variable or one of the\ncampaign's custom variables, as `GET /v1/sequence-variables` lists them. Leave the subject empty on step 2 or\nlater to send the email as a reply in the thread of the previous email.","nullable":true},"body":{"type":"string","description":"The email body, written as `bodyFormat` says. Variables follow the same rules as in `subject`.","nullable":true},"bodyFormat":{"type":"string","description":"How `body` is written: `plain`, `markdown` or `html`. Defaults to `plain`. `html` needs the `html_steps`\nfeature.","nullable":true},"waitDays":{"type":"integer","description":"Days Kenso waits after the previous step is sent before it sends this step. Step 1 ignores it. Defaults to 0.","format":"int32"},"isActive":{"type":"boolean","description":"Whether Kenso sends this variant. Defaults to true."},"openTrackingEnabled":{"type":"boolean","description":"Stored and returned for compatibility; it does not affect sending. The campaign's `trackOpens` decides whether a\nsend carries the open pixel. Defaults to false, so a replace that leaves it out turns it off. Saved versions do not\nkeep it."},"handwrittenEnabled":{"type":"boolean","description":"Set to true to send the letter part of the body as an image of a handwritten letter. The letter part is the body\nabove the sender signature (`{sender_signature}`) or the unsubscribe link, and it cannot contain links. Defaults\nto false, so a replace that leaves it out turns the letter off. While the `handwritten_letters` feature is off\nfor the workspace, the step sends as normal text."},"handwrittenBackground":{"type":"string","description":"The paper behind the handwritten letter: `walnut`, `linen`, `kraft`, `marble`, `deckle` or `notepad`. Null or\nomitted means `walnut`.","nullable":true},"handwrittenIntro":{"type":"string","description":"The line of normal text above the handwritten letter: at most 200 characters on one line, with no HTML, links\nor spintax. Null or omitted means Kenso's default line, which names the contact and the sender.","nullable":true},"studioTemplateVersionId":{"type":"integer","description":"A published Studio email version for this step to send. The step becomes `html` and stores the version's\nsubject and body, so `subject`, `body` and `bodyFormat` sent with it are ignored. Null or omitted unpins the\nstep. Needs the `studio`, `studio_email` and `html_steps` features. Only a sequence replace reads it. A saved\nversion ignores it, so restoring that version unpins the step.","format":"int64","nullable":true}},"additionalProperties":false,"description":"One variant of one email step to save."},"StudioPin":{"type":"object","properties":{"versionId":{"type":"integer","description":"The id of the Studio email version.","format":"int64"},"templateId":{"type":"integer","description":"The id of the Studio email the version belongs to. Null when that email no longer exists.","format":"int64","nullable":true},"state":{"type":"string","description":"`ok`, or `stale` when the version is no longer published, is not an email, or its Studio email\n            was deleted. A `stale` step sends the subject and body stored on the step instead."}},"additionalProperties":false,"description":"The Studio email version a step sends, and whether it can still be sent."},"TestSendSequenceRequest":{"required":["contactId","targetEmails","senderEmailId"],"type":"object","properties":{"contactId":{"type":"integer","description":"The id of the contact whose details fill the variables. Required, and the contact must be in the campaign.","format":"int64"},"targetEmails":{"type":"string","description":"The addresses to send the test to, separated by commas or semicolons, at most 5. Required. Addresses on the\nworkspace's blocklist or with a hard bounce are refused."},"senderEmailId":{"type":"integer","description":"The id of the inbox to send from. Required. Once the campaign has inboxes, it must be one of them, and it must be\nable to send.","format":"int64"},"language":{"type":"string","description":"A language or locale tag, such as `fr` or `fr-FR`. Kenso sends the steps as a contact in that language would get\nthem. Omit it to use the contact's own language. The campaign's source language sends the original text.","nullable":true},"providerTrack":{"type":"string","description":"`google`, `microsoft` or `other`. Kenso sends the steps as that provider track sends them: recipients on Google\nget plain text. On a segment, a track's own `sequenceSegmentId` implies its track. Ignored when the campaign is\nnot on provider tracks.","nullable":true}},"additionalProperties":false,"description":"What to test, and where to send it.","example":{"contactId":90125,"targetEmails":"jordan.patel@northwind-outbound.example.com","senderEmailId":5530}},"TooManyRequestsError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The JSON body of a `429`: the error body (`Failure`), with code `rate_limited` or `quota_exceeded`, over your workspace's rate limits, your API key's own limit, the operation's own limit or a usage quota. Until November 2026, over your API key's own limit the API key check answered `{ \"error\": \"Rate limit exceeded\" }` (`ApiKeyError`), and over the operation's own limit the gateway answered plain text (`RateLimitedText`): `Number of requests exceeded. Please try again later.` A client built against those answers keeps working: handle each shape. Wait the `Retry-After` seconds."},"UnauthorizedError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The body of a `401`: the error body (`Failure`), whose `code` says what is wrong with the credential. Until November 2026, when the API key was not valid (unknown, expired or revoked, or its member no longer active), the API key check in front of the operations answered `{ \"error\": \"Invalid or revoked API key\" }` (`ApiKeyError`), and a request with no API key got a `401` that has no body. A client built against those answers keeps working: handle both shapes and a `401` with no body."}}}}