Placement tests
Placement tests show where a campaign's email lands: the inbox, a promotions tab, spam, or nowhere. Kenso sends the campaign's first email from your inboxes to seed mailboxes at Gmail, Google Workspace, Outlook and Microsoft 365, then records where each copy arrived. Start a test, poll it until it completes, then read the results by provider, sending inbox and seed. Kenso also tests your sending domains every week, and a campaign's list includes those weekly tests for the domains it sends from. Where GET /v1/placement-tests/availability answers enabled: true, the workspace's tests run on the Kenso seed network.
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. |
List placement tests
/v1/placement-testsplacement-tests.list- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
Lists the placement tests of one campaign, one inbox or one domain, newest first. A campaign's list holds the tests started for the campaign and Kenso's weekly tests of the domains the campaign sends from, even when a weekly test belongs to another campaign. An inbox's list holds the tests of that inbox (its scope or one of its senders) and a domain's list the tests of that domain, from any campaign and either engine.
Send exactly one of the campaignId, inboxId, domainId and domainIds query parameters. Each item has the test's rates, each a fraction from 0 to 1 and omitted until the test completes. For the results by provider, sending inbox and seed, get one test with GET /v1/placement-tests/{placementTestId}.
domainIds lists several domains in one call: 1 to 50 domain ids, comma-separated, such as domainIds=4,9,12. Each domain gets its newest limit tests, the ones the first page of its own domainId list holds; with domainIds, limit is from 1 to 20 and defaults to 20. The items come grouped by domain in the order of domainIds, each domain's tests newest first. An id that is not a domain of this workspace has no items, where domainId answers 404. This list takes no cursor and has no further pages (pagination.hasMore is false): to read a domain's older tests, list it with domainId.
Errors:
400 validation_failed: not exactly one ofcampaignId,inboxId,domainIdanddomainIds,domainIdsis not 1 to 50 positive ids,cursoris sent withdomainIds,limitis not from 1 to 200 (1 to 20 withdomainIds), orcursoris not valid.404 not_found: the campaign, inbox or domain is not in this workspace.
Requires Delivery view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | query | integer (int64) | optional | Campaign whose placement tests to list. |
inboxId | query | integer (int64) | optional | Inbox whose placement tests to list: tests it was the scope of or sent from, any campaign. |
domainId | query | integer (int64) | optional | Domain whose placement tests to list, any campaign. |
domainIds | query | string | optional | Domains whose placement tests to list: 1 to 50 domain ids, comma-separated. Each domain gets its newest limit tests, as domainId gives its first page. Takes no cursor. |
limit | query | integer (int32) | optional | Page size: defaults to 50, maximum 200. With domainIds, the tests per domain: defaults to 20, maximum 20. |
cursor | query | string | optional | Opaque cursor from a previous page. |
curl -X GET "https://api.ken.so/v1/placement-tests?limit=1" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of PlacementTest. Each item has these fields. The response also carries pagination.
Show the 39 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Start a placement test
/v1/placement-testsplacement-tests.create- Permission
- Delivery edit
- Rate limit
- 10 requests a minute per API key
Sends an email to seed mailboxes and records where each copy lands. The call returns the test at once. Poll GET /v1/placement-tests/{placementTestId} until status is completed or failed; results arrive in about an hour. A workspace runs its tests on one of two engines: the Kenso seed network where GET /v1/placement-tests/availability answers enabled: true, the mailbox provider's engine everywhere else.
Kenso seed network (paid plans only): the seed network covers Google Workspace at launch; Microsoft 365 joins when it has enough seeds, and providers[].tested says which ran. Scope: inboxId tests one inbox, domainId the domain's inboxes, neither the campaign's senders (needs campaignId). Copy: the campaign's (campaignId), or custom subject and body together. control: true also sends a plain message from the same senders to tell a copy problem from a domain problem. openPixel: true is refused: open tracking is unavailable, Kenso adds no open-tracking pixel. trackLinks: false sends the body's links as written instead of as tracked links (default true); the test's trackLinks says which it used. A 200 keeps the running test's settings, so run a tracked and an untracked test one after the other or from different scopes. followUp also sends each seed a second email from the same inbox in the first email's thread (body, format, delayMinutes 5 to 4320, optional subject), only once the first email was sent. The test, its verdict and its scope stay busy until the follow-up is read, up to the delay plus about an hour: a create for the same scope meanwhile answers 200 with this test, so compare two follow-ups from different inboxes. followUp and seeds[].followUp hold its results. Example: { "domainId": 1369, "campaignId": 8865, "control": true }. Answers 201 with the new test, or 200 with the test already running for that scope; the body is the detail model, or only the test's own fields when the read replica has not caught up yet (poll the detail). An id of 0 counts as absent. Budget: placementTestCreatesNative (10 a day, 60 in 30 days), placementTestCreatesNativeTrial while trialing (2 a day, 8 in 30 days); over it 429 quota_exceeded naming the limit, with Retry-After. Kenso staff have a daily cap instead.
Errors on the Kenso seed network:
400 validation_failed: bothinboxIdanddomainId,randomScope, only one ofsubjectandbody, or nocampaignIdwhere the copy or the scope needs one; afollowUpwith nobody, aformatother thanplainorhtmlor one the body does not match, or adelayMinutesoutside 5 to 4320; afollowUpwhile follow-ups are off (detail codefollow_up_unavailable). Detail codeopen_tracking_unavailableonopenPixelforopenPixel: true.402 plan_limit_reachedwitherror.refusal: the plan has no placement tests.404 not_found: the campaign, inbox or domain is not in this workspace.409 demo_workspace;409 control_unavailable: not enough seeds for the control arm;409 invalid_state: no inbox can send (details[].codesender_unavailable), or a test for this scope is still starting (placement_test_starting, try again in a minute).422with the reason as the code:copy_unresolved,copy_not_neutral,copy_link_listed,copy_too_large,copy_brand_domain,copy_has_attachments,sender_blocked.detailsname the field or the inbox.429 rate_limited: an inbox's or the staff daily test cap (details[].codesender_daily_caporstaff_daily_cap).503seed_network_busy,link_check_unavailableorplacement_native_paused: try again later.
The mailbox provider's engine: send campaignId and exactly one of domainId or inboxId; control, subject, body, trackLinks and followUp are ignored. With domainId, Kenso sends from the domain's inboxes. With inboxId, it sends from that inbox only. With randomScope set to true, Kenso picks a random eligible domain in the workspace and ignores both. The test can only send from active inboxes that Kenso manages. Example: { "campaignId": 812, "inboxId": 44 }.
Kenso tests the first active step of the campaign's sequence and fills its variables from a sample contact. The other body fields choose which copy and which contact. With openPixel set to true, the copy carries the campaign open pixel, so you can compare placement with the pixel on and off. The answer's openPixelHost names the host the pixel loads from.
If a test of the same campaign on the same inbox, or for a domain test the same domain, is still pending or running, Kenso returns that test instead of starting a second one.
Tests cost the workspace no credits, so Kenso limits how many tests a workspace can start per day and per 30 days. A call that fails before the test starts does not count against the limit.
Errors on the mailbox provider's engine:
400 validation_failed:campaignIdis missing, or the body has both or neither ofdomainIdandinboxIdwhilerandomScopeis false.404 not_found: the campaign, contact, domain or inbox is not in this workspace.409 invalid_state: Kenso cannot build or send the test, and the message says why. The campaign has no email copy, no contact has its personalization filled yet, the copy has a broken{spin:...}block, the domain or inbox has no active inbox that Kenso manages, the workspace has no eligible domain forrandomScope, the provider refused the sending inboxes, or the workspace is a demo workspace.409 invalid_statewithopenPixel: the copy is plain text, neitherlink.norunsub.on the sending domain serves the pixel, or a test with the other pixel setting is already running for the campaign and domain.429 rate_limitedor429 quota_exceeded: the workspace reached its placement test limit. Try again after theRetry-Afterseconds.503 service_unavailable: Kenso can't start placement tests right now. Try again later.
Requires Delivery edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
campaignId | integer (int64) | optional | Campaign whose email Kenso tests. Required, except on the Kenso engine for a test of custom subject and body sent from an inboxId or domainId. |
inboxId | integer (int64) | optional | Inbox the test sends from. Send it or domainId, not both. Ignored when randomScope is true. |
domainId | integer (int64) | optional | Domain whose inboxes send the test. Send it or inboxId, not both. Ignored when randomScope is true. |
sequenceVersionId | integer (int64) | optional | Saved version of the campaign's sequence to test. When set, Kenso ignores campaignSegmentId, randomSegment and randomCopyVersion to choose the copy. Omitted tests the sequence as it is saved now. |
sampleVariables | map of string | optional | Values for the copy's variables, keyed by variable name, such as {"firstName": "Dana"}. They win over the sample contact's values. Kenso ignores blank keys and values. |
campaignSegmentId | integer (int64) | optional | Campaign segment whose copy to test. A segment without its own copy uses the campaign's default copy. Omitted uses the sample contact's segment, or the default copy when there is no sample contact. |
contactId | integer (int64) | optional | Contact in the campaign whose data fills the copy's variables. If the copy uses a variable this contact has no value for yet, the call answers 409 invalid_state. |
randomSegment | boolean | optional | When true and campaignSegmentId is omitted, Kenso tests the copy of a random segment of the campaign. Default false. |
randomLead | boolean | optional | When true and contactId is omitted, Kenso fills the copy from a sample contact of the campaign, and prefers contacts whose AI personalization is filled. Default false. Without it, Kenso uses a sample contact only when the copy has variables that need one. |
randomScope | boolean | optional | When true, Kenso sends from a random eligible domain in the workspace and ignores domainId and inboxId. Default false. |
randomCopyVersion | boolean | optional | When true and sequenceVersionId is omitted, Kenso tests a random saved version of the sequence. Default false. |
openPixel | boolean | optional | The mailbox provider's engine only: when true, the copy carries the campaign open pixel, loaded from link. or unsub. on the sending domain, whichever serves it first. On the Kenso seed network open tracking is unavailable: Kenso adds no open-tracking pixel, so true is 400 validation_failed with detail code open_tracking_unavailable and no test starts. Default false. |
trackLinks | boolean | optional | Kenso engine only: when false, every send of the test carries the body's links as written, with no click tracking. Default true: links go through tracked links on the sending domain. |
control | boolean | optional | Kenso engine only: also send a plain control message from the same senders to a second set of seeds, to tell a copy problem from a domain problem. Default false. |
subject | string | optional | Kenso engine only: custom copy to test instead of the campaign's. Give it with body. |
body | string | optional | Kenso engine only: custom copy, HTML or plain text. Give it with subject. |
followUp | PlacementTestFollowUpRequest | optional | Kenso engine only: a second email each seed gets from the same inbox, in the first email's thread, once the first email was sent and delayMinutes passed. Omitted sends only the first email. The test, its verdict and its scope stay busy until the follow-up is read, so compare two follow-ups from different inboxes. |
curl -X POST "https://api.ken.so/v1/placement-tests" \
-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 '{
"campaignId": 812,
"inboxId": 812,
"domainId": 812,
"sequenceVersionId": 812,
"sampleVariables": {
"key": "string"
},
"campaignSegmentId": 812,
"contactId": 812,
"randomSegment": true,
"randomLead": true,
"randomScope": true,
"randomCopyVersion": true,
"openPixel": true,
"trackLinks": true,
"control": true,
"subject": "string",
"body": "string",
"followUp": {
"body": "string",
"format": "plain",
"delayMinutes": 1,
"subject": "string"
}
}'Response 201
Also answers 200. data is a PlacementTest.
Show the 39 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a placement test
/v1/placement-tests/{placementTestId}placement-tests.get- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
Returns one placement test with its full results. Poll it after you start a test, until status is completed or failed.
Besides the fields in the list, the test has type, senderInboxIds, the subject and body it sent, and openPixelHost when it carried the open pixel. Once the test completes, it also has startedAt, sentCount, counts, and the results per seed provider (providers), per sending inbox (senders) and per seed mailbox (seeds), plus any errors the provider reported. Seed addresses are masked. Rates are fractions from 0 to 1.
The earlierTests list holds up to 10 earlier tests of the same campaignId and domainId, whichever are set, newest first, so you can show a trend. A test of one inbox that has no domain has no earlier tests.
Errors:
404 not_found: the placement test is not in this workspace.
Requires Delivery view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
placementTestId | path | integer (int64) | required | The placement test's id. |
curl -X GET "https://api.ken.so/v1/placement-tests/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a PlacementTest.
Show the 39 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Return what the start dialog needs to offer a Kenso placement test
/v1/placement-tests/availabilityplacement-tests.availability- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
Always 200. enabled: false means this workspace keeps the mailbox provider's engine. planAllowed: the plan can start Kenso tests. providers: each seed provider and whether it runs tests now. control: whether a test can add the control arm, and why not. The test counters are what the workspace's budget leaves today and this month (omitted when unknown); senderTestsPerDay is the cap per sending inbox. Requires Delivery view.
curl -X GET "https://api.ken.so/v1/placement-tests/availability" \
-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 PlacementAvailability.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Deliverability:DomainsDomain health checksDelivery settingsTracking linksOutbound domain pagesInfrastructure findingsDeliverability rulesAll resources