Skip to Content
Deliverability

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.

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

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.

List placement tests

GET/v1/placement-testsplacement-tests.list
Permission
Delivery view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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 of campaignId, inboxId, domainId and domainIds, domainIds is not 1 to 50 positive ids, cursor is sent with domainIds, limit is not from 1 to 200 (1 to 20 with domainIds), or cursor is not valid.
  • 404 not_found: the campaign, inbox or domain is not in this workspace.

Requires Delivery view.

Parameters

NameInTypeRequiredDescription
campaignIdqueryinteger (int64)optionalCampaign whose placement tests to list.
inboxIdqueryinteger (int64)optionalInbox whose placement tests to list: tests it was the scope of or sent from, any campaign.
domainIdqueryinteger (int64)optionalDomain whose placement tests to list, any campaign.
domainIdsquerystringoptionalDomains 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.
limitqueryinteger (int32)optionalPage size: defaults to 50, maximum 200. With domainIds, the tests per domain: defaults to 20, maximum 20.
cursorquerystringoptionalOpaque cursor from a previous page.
Request
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

POST/v1/placement-testsplacement-tests.create
Permission
Delivery edit
Rate limit
10 requests a minute per API key

Try it on developer.ken.so

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: both inboxId and domainId, randomScope, only one of subject and body, or no campaignId where the copy or the scope needs one; a followUp with no body, a format other than plain or html or one the body does not match, or a delayMinutes outside 5 to 4320; a followUp while follow-ups are off (detail code follow_up_unavailable). Detail code open_tracking_unavailable on openPixel for openPixel: true.
  • 402 plan_limit_reached with error.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[].code sender_unavailable), or a test for this scope is still starting (placement_test_starting, try again in a minute).
  • 422 with the reason as the code: copy_unresolved, copy_not_neutral, copy_link_listed, copy_too_large, copy_brand_domain, copy_has_attachments, sender_blocked. details name the field or the inbox.
  • 429 rate_limited: an inbox's or the staff daily test cap (details[].code sender_daily_cap or staff_daily_cap).
  • 503 seed_network_busy, link_check_unavailable or placement_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: campaignId is missing, or the body has both or neither of domainId and inboxId while randomScope is 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 for randomScope, the provider refused the sending inboxes, or the workspace is a demo workspace.
  • 409 invalid_state with openPixel: the copy is plain text, neither link. nor unsub. 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_limited or 429 quota_exceeded: the workspace reached its placement test limit. Try again after the Retry-After seconds.
  • 503 service_unavailable: Kenso can't start placement tests right now. Try again later.

Requires Delivery edit.

Request body

application/json, optional.

FieldTypeRequiredDescription
campaignIdinteger (int64)optionalCampaign whose email Kenso tests. Required, except on the Kenso engine for a test of custom subject and body sent from an inboxId or domainId.
inboxIdinteger (int64)optionalInbox the test sends from. Send it or domainId, not both. Ignored when randomScope is true.
domainIdinteger (int64)optionalDomain whose inboxes send the test. Send it or inboxId, not both. Ignored when randomScope is true.
sequenceVersionIdinteger (int64)optionalSaved 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.
sampleVariablesmap of stringoptionalValues 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.
campaignSegmentIdinteger (int64)optionalCampaign 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.
contactIdinteger (int64)optionalContact 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.
randomSegmentbooleanoptionalWhen true and campaignSegmentId is omitted, Kenso tests the copy of a random segment of the campaign. Default false.
randomLeadbooleanoptionalWhen 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.
randomScopebooleanoptionalWhen true, Kenso sends from a random eligible domain in the workspace and ignores domainId and inboxId. Default false.
randomCopyVersionbooleanoptionalWhen true and sequenceVersionId is omitted, Kenso tests a random saved version of the sequence. Default false.
openPixelbooleanoptionalThe 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.
trackLinksbooleanoptionalKenso 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.
controlbooleanoptionalKenso 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.
subjectstringoptionalKenso engine only: custom copy to test instead of the campaign's. Give it with body.
bodystringoptionalKenso engine only: custom copy, HTML or plain text. Give it with subject.
followUpPlacementTestFollowUpRequestoptionalKenso 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.
Request
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

GET/v1/placement-tests/{placementTestId}placement-tests.get
Permission
Delivery view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
placementTestIdpathinteger (int64)requiredThe placement test's id.
Request
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

GET/v1/placement-tests/availabilityplacement-tests.availability
Permission
Delivery view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

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


On this page