> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/placement-tests/openapi.json](/docs/api/placement-tests/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Placement tests: Start a placement test

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

One endpoint of [Placement tests](/docs/api/placement-tests.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Start a placement test

`POST /v1/placement-tests` - operationId `placement-tests.create`

| Permission | Rate limit |
| --- | --- |
| Delivery edit | 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`: 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.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/placement-tests/POST/v1/placement-tests)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `campaignId` | integer (int64) | no | 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) | no | Inbox the test sends from. Send it or `domainId`, not both. Ignored when `randomScope` is true. |
| `domainId` | integer (int64) | no | Domain whose inboxes send the test. Send it or `inboxId`, not both. Ignored when `randomScope` is true. |
| `sequenceVersionId` | integer (int64) | no | 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 | no | 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) | no | 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) | no | 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 | no | When true and `campaignSegmentId` is omitted, Kenso tests the copy of a random segment of the campaign. Default false. |
| `randomLead` | boolean | no | 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 | no | When true, Kenso sends from a random eligible domain in the workspace and ignores `domainId` and `inboxId`. Default false. |
| `randomCopyVersion` | boolean | no | When true and `sequenceVersionId` is omitted, Kenso tests a random saved version of the sequence. Default false. |
| `openPixel` | boolean | no | 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 | no | 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 | no | 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 | no | Kenso engine only: custom copy to test instead of the campaign's. Give it with `body`. |
| `body` | string | no | Kenso engine only: custom copy, HTML or plain text. Give it with `subject`. |
| `followUp` | PlacementTestFollowUpRequest | no | 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. |

### Response 201

Also answers `200`. `data` is a `PlacementTest`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | Placement test id. |
| `campaignId` | integer (int64) | Campaign the test belongs to. In a campaign's list, a weekly domain test can belong to another campaign that sends from the same domain. |
| `listedForCampaignId` | integer (int64) | The campaign whose list this item is in, when you list several campaigns with `campaignIds`. Omitted everywhere else. |
| `inboxId` | integer (int64) | Inbox the test was limited to. Omitted for a test of a whole domain. |
| `domainId` | integer (int64) | Domain the test sent from. Omitted when the test has no domain. |
| `sequenceId` | integer (int64) | Sequence whose copy the test sent. Omitted in the answer to a start and when not recorded. |
| `sequenceVersionId` | integer (int64) | Saved sequence version the test sent. Omitted when the test sent the sequence as it was saved at the time. |
| `status` | string | Test status: `pending` (waiting to send), `running` (sent, and Kenso is checking the seed mailboxes), `completed` or `failed`. |
| `inboxRate` | number (double) | Share of the seed copies that landed in the inbox, a fraction from 0 to 1. Omitted until the test completes. |
| `spamRate` | number (double) | Share of the seed copies that landed in spam, a fraction from 0 to 1. Omitted until the test completes. |
| `categoryRate` | number (double) | Share of the seed copies that landed in a promotions or other category tab, a fraction from 0 to 1. Omitted until the test completes. |
| `missingRate` | number (double) | Share of the seed copies that never arrived, a fraction from 0 to 1. Omitted until the test completes. |
| `code` | string | The testing provider's reference for this test. Omitted when there is none. |
| `openPixelHost` | string | Host the campaign open pixel loaded from, for a test started with `openPixel` set to true. Returned when you start a test and when you get one, not in the list. Omitted when the test carried no pixel. |
| `provider` | string | Name of the testing provider that ran the test, in lowercase, such as `kenso` for a test on the Kenso seed network. Omitted when not recorded. Prefer providerKind. |
| `providerKind` | string | The testing provider in neutral words: `kenso` for the Kenso seed network, `mailbox_provider` for the mailbox provider's engine, or `other` (older tests). Omitted when not recorded. |
| `scope` | string | Kenso tests: `inbox`, `domain` or `campaign` (the campaign's senders). Omitted otherwise. |
| `verdict` | PlacementVerdict | Kenso tests: the scored cause and its one-line summary. Omitted until the test completes. |
| `hasControl` | boolean | Kenso tests: true when the test also sent the plain control message. Omitted on other tests. |
| `trackLinks` | boolean | Kenso tests: false when the test sent the body's links as written, true when it sent them as tracked links. Omitted on other tests. |
| `providersTested` | array of string | Kenso tests: the seed providers it sent to, `google_workspace` and `microsoft_365`. |
| `dataPoints` | array of PlacementProviderBreakdown | Inbox rate by type of seed mailbox, as a list with one entry. Omitted when the test has no results by provider. |
| `createdAt` | string (date-time) | When the test was created, in UTC. |
| `completedAt` | string (date-time) | When the test completed, in UTC. Omitted until then. |
| `type` | string | Kind of test: `weekly` (Kenso's weekly test of a sending domain), `on_demand` (a test someone started) or `pre_launch` (a test run before a campaign launched). Only when you get one test. |
| `startedAt` | string (date-time) | When the provider started sending the test, in UTC. Omitted until the test completes. |
| `sentCount` | integer (int32) | Test emails the provider sent. 0 when it sent none, for example because it refused every sending inbox (see `errors`). Omitted until the test completes. |
| `failureReason` | string | Why the test failed, when `status` is `failed`. Omitted otherwise. |
| `senderInboxIds` | array of integer (int64) | Ids of the inboxes the test sent from. Omitted when not recorded. |
| `subject` | string | Subject line the test sent, with its variables filled. Omitted for older tests that did not store it. |
| `body` | string | Body the test sent, with its variables filled. Omitted for older tests that did not store it. |
| `counts` | PlacementCounts | Seed copies per placement across the whole test. Omitted until the test completes. |
| `providers` | array of PlacementProviderResult | Seed copies per placement for each seed mailbox provider, in the order `gmail`, `google_workspace`, `outlook`, `microsoft_365`, then any other. Omitted until the test completes. |
| `senders` | array of PlacementSenderResult | Seed copies per placement for each sending inbox, including an inbox whose mail reached no seed. Omitted until the test completes. |
| `seeds` | array of PlacementSeedResult | One row per seed mailbox and sending inbox. Omitted until the test completes. |
| `errors` | array of PlacementTestError | Errors the provider reported, such as a sending inbox it could not use, oldest first and at most 50. On a Kenso test, the seed providers it skipped and the sends and reads that failed. Omitted when there are none. |
| `control` | PlacementControl | Kenso detail with `hasControl`: the control arm's rates, counts and providers. |
| `progress` | PlacementProgress | Kenso detail: sends by state and when the final read is due. |
| `followUp` | PlacementFollowUp | Kenso tests started with `followUp`: its settings, and on one test its body and results. The other result fields describe the first email. Omitted on other tests. |
| `earlierTests` | array of PlacementTestTrend | Up to 10 earlier tests of the same `campaignId` and `domainId`, whichever are set, newest first. Empty for a test of one inbox that has no domain. Only when you get one test. |

### Request

```bash
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"
  }
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "campaignId": 812,
    "listedForCampaignId": 812,
    "inboxId": 812,
    "domainId": 812,
    "sequenceId": 812,
    "sequenceVersionId": 812,
    "status": "string",
    "inboxRate": 0.5,
    "spamRate": 0.5,
    "categoryRate": 0.5,
    "missingRate": 0.5,
    "code": "string",
    "openPixelHost": "string",
    "provider": "kenso",
    "providerKind": "string",
    "scope": "inbox",
    "verdict": {
      "cause": "string",
      "summary": "string"
    },
    "hasControl": true,
    "trackLinks": true,
    "providersTested": [
      "string"
    ],
    "dataPoints": [
      {
        "googleWorkspace": 0.5,
        "googlePersonal": 0.5,
        "outlookWorkspace": 0.5,
        "outlookPersonal": 0.5
      }
    ],
    "createdAt": "2026-09-23T15:02:11Z",
    "completedAt": "2026-09-23T15:02:11Z",
    "type": "string",
    "startedAt": "2026-09-23T15:02:11Z",
    "sentCount": 1,
    "failureReason": "string",
    "senderInboxIds": [
      812
    ],
    "subject": "string",
    "body": "string",
    "counts": {
      "inbox": 1,
      "promotions": 1,
      "other": 1,
      "spam": 1,
      "missing": 1,
      "total": 1
    },
    "providers": [
      {
        "provider": "gmail",
        "inbox": 1,
        "promotions": 1,
        "other": 1,
        "spam": 1,
        "missing": 1,
        "total": 1,
        "tested": true,
        "folders": {
          "key": 1
        },
        "authentication": {
          "checked": 1,
          "spfPass": 1,
          "dkimPass": 1,
          "dmarcPass": 1,
          "compauthPass": 1,
          "allPass": 1
        },
        "microsoft": {
          "scored": 1,
          "bulkHigh": 1,
          "medianBcl": 0.5,
          "medianScl": 0.5
        },
        "medianArrivalSeconds": 1
      }
    ],
    "senders": [
      {
        "email": "jane@example.com",
        "inbox": 1,
        "promotions": 1,
        "other": 1,
        "spam": 1,
        "missing": 1,
        "total": 1
      }
    ],
    "seeds": [
      {
        "seed": "d***@gmail.com",
        "provider": "gmail",
        "senderEmail": "jane@example.com",
        "placement": "inbox",
        "folder": "SPAM",
        "detectedAt": "2026-09-23T15:02:11Z",
        "arm": "main",
        "status": "waiting",
        "tab": "primary",
        "authentication": {
          "spf": "string",
          "dkim": "string",
          "dmarc": "string",
          "compauth": "string"
        },
        "microsoft": {
          "scl": 1,
          "bcl": 1,
          "cat": "string",
          "sfv": "string"
        },
        "arrivalSeconds": 1,
        "followUp": {}
      }
    ],
    "errors": [
      {
        "message": "string",
        "at": "2026-09-23T15:02:11Z"
      }
    ],
    "control": {
      "inboxRate": 0.5,
      "spamRate": 0.5,
      "categoryRate": 0.5,
      "missingRate": 0.5,
      "counts": {
        "inbox": 1,
        "promotions": 1,
        "other": 1,
        "spam": 1,
        "missing": 1,
        "total": 1
      },
      "providers": [
        {
          "provider": "gmail",
          "inbox": 1,
          "promotions": 1,
          "other": 1,
          "spam": 1,
          "missing": 1,
          "total": 1,
          "tested": true,
          "folders": {
            "key": 1
          },
          "authentication": {
            "checked": 1,
            "spfPass": 1,
            "dkimPass": 1,
            "dmarcPass": 1,
            "compauthPass": 1,
            "allPass": 1
          },
          "microsoft": {
            "scored": 1,
            "bulkHigh": 1,
            "medianBcl": 0.5,
            "medianScl": 0.5
          },
          "medianArrivalSeconds": 1
        }
      ]
    },
    "progress": {
      "planned": 1,
      "sent": 1,
      "read": 1,
      "waiting": 1,
      "failed": 1,
      "finalBy": "2026-09-23T15:02:11Z"
    },
    "followUp": {
      "format": "plain",
      "delayMinutes": 1,
      "subject": "string",
      "body": "string",
      "counts": {
        "inbox": 1,
        "promotions": 1,
        "other": 1,
        "spam": 1,
        "missing": 1,
        "total": 1
      },
      "providers": [
        {
          "provider": "gmail",
          "inbox": 1,
          "promotions": 1,
          "other": 1,
          "spam": 1,
          "missing": 1,
          "total": 1,
          "tested": true,
          "folders": {
            "key": 1
          },
          "authentication": {
            "checked": 1,
            "spfPass": 1,
            "dkimPass": 1,
            "dmarcPass": 1,
            "compauthPass": 1,
            "allPass": 1
          },
          "microsoft": {
            "scored": 1,
            "bulkHigh": 1,
            "medianBcl": 0.5,
            "medianScl": 0.5
          },
          "medianArrivalSeconds": 1
        }
      ]
    },
    "earlierTests": [
      {
        "id": 812,
        "campaignId": 812,
        "inboxId": 812,
        "domainId": 812,
        "status": "pending",
        "inboxRate": 0.5,
        "spamRate": 0.5,
        "categoryRate": 0.5,
        "missingRate": 0.5,
        "createdAt": "2026-09-23T15:02:11Z",
        "completedAt": "2026-09-23T15:02:11Z"
      }
    ]
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### PlacementTestFollowUpRequest

The follow-up of a Kenso placement test. The test's `openPixel` and `trackLinks` apply to it too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | string | yes | The follow-up's body, HTML or plain text. Required. |
| `format` | string | no | `plain` or `html`, and it must match the body. Omitted reads it from the body. |
| `delayMinutes` | integer (int32) | no | Minutes after the first email was sent, 5 to 4320 (3 days). |
| `subject` | string | no | The follow-up's subject. Omitted sends "Re: " and the first email's subject. |

### PlacementVerdict

A Kenso test's verdict. `cause`: `auth_failing`, `copy`, `reputation`, `microsoft_bulk`, `one_provider`, `healthy` or `mixed`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cause` | string | no |  |
| `summary` | string | no |  |

### PlacementProviderBreakdown

Inbox rate by type of seed mailbox, each a fraction from 0 to 1. A field is omitted when the test had no seed mailboxes of that type.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `googleWorkspace` | number (double) | no | Inbox rate at Google Workspace seed mailboxes. |
| `googlePersonal` | number (double) | no | Inbox rate at personal Gmail seed mailboxes. |
| `outlookWorkspace` | number (double) | no | Inbox rate at Microsoft 365 seed mailboxes. |
| `outlookPersonal` | number (double) | no | Inbox rate at personal Outlook seed mailboxes. |

### PlacementCounts

Seed copies per placement. `total` is the sum of the other five counts.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inbox` | integer (int32) | no | Copies that landed in the inbox (the primary tab in Gmail). |
| `promotions` | integer (int32) | no | Copies that landed in the promotions tab or another category tab. |
| `other` | integer (int32) | no | Copies that landed in any other folder. |
| `spam` | integer (int32) | no | Copies that landed in spam or junk. |
| `missing` | integer (int32) | no | Copies that never arrived. |
| `total` | integer (int32) | no | All copies, the sum of the five counts. |

### PlacementProviderResult

Seed copies per placement at one seed mailbox provider.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | string | no | Seed mailbox provider, such as `gmail`, `google_workspace`, `outlook` or `microsoft_365`. `unknown` when the testing provider did not say. |
| `inbox` | integer (int32) | no | Copies that landed in the inbox (the primary tab in Gmail). |
| `promotions` | integer (int32) | no | Copies that landed in the promotions tab or another category tab. |
| `other` | integer (int32) | no | Copies that landed in any other folder. |
| `spam` | integer (int32) | no | Copies that landed in spam or junk. |
| `missing` | integer (int32) | no | Copies that never arrived. |
| `total` | integer (int32) | no | All copies to this provider, the sum of the five counts. |
| `tested` | boolean | no | Kenso: false when the test sent nothing to this provider (not in the seed network yet), with zero counts. |
| `folders` | map of integer (int32) | no | Kenso: found messages per folder or tab, such as `primary` or `junk`, plus `missing`. |
| `authentication` | PlacementAuthSummary | no | Kenso: SPF, DKIM, DMARC and compauth over the found messages that carry them. |
| `microsoft` | PlacementMicrosoftSummary | no | Kenso, `microsoft_365` only: Microsoft's spam (SCL) and bulk (BCL) scores. |
| `medianArrivalSeconds` | integer (int32) | no | Kenso: median seconds from send to arrival over found messages. |

### PlacementSenderResult

Seed copies per placement for one sending inbox.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | no | Address of the sending inbox, in lowercase. |
| `inbox` | integer (int32) | no | Copies that landed in the inbox (the primary tab in Gmail). |
| `promotions` | integer (int32) | no | Copies that landed in the promotions tab or another category tab. |
| `other` | integer (int32) | no | Copies that landed in any other folder. |
| `spam` | integer (int32) | no | Copies that landed in spam or junk. |
| `missing` | integer (int32) | no | Copies that never arrived. |
| `total` | integer (int32) | no | All copies from this inbox, the sum of the five counts. 0 when its mail reached no seed. |

### PlacementSeedResult

Where one seed mailbox received the copy from one sending inbox.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seed` | string | no | Seed address, masked to its first letter and its domain, such as `d***@gmail.com`. Kenso staff see it in full. |
| `provider` | string | no | Seed mailbox provider, such as `gmail`, `google_workspace`, `outlook` or `microsoft_365`. |
| `senderEmail` | string | no | Address of the sending inbox, in lowercase. |
| `placement` | string | no | Where the copy landed: `inbox`, `promotions`, `other`, `spam` or `missing`, or `pending` on a Kenso seed not read yet. |
| `folder` | string | no | Gmail label or Outlook folder the copy landed in, such as `SPAM` or `Junk Email`. Omitted when not reported. |
| `detectedAt` | string (date-time) | no | When the copy was found in the seed mailbox, in UTC. Omitted when not reported. |
| `arm` | string | no | Kenso: `main` or `control`. |
| `status` | string | no | Kenso: `waiting`, `found`, `missing`, `send_failed` or `read_failed`. |
| `tab` | string | no | Kenso: the folder or tab the message was in, such as `primary`, `promotions` or `junk`. |
| `authentication` | PlacementSeedAuth | no | One message's authentication results: `pass`, `fail`, `softfail`, `none` and the like. |
| `microsoft` | PlacementSeedMicrosoft | no | Kenso, Microsoft 365 seeds: the message's SCL, BCL, CAT and SFV. |
| `arrivalSeconds` | integer (int32) | no |  |
| `followUp` | PlacementSeedResult | no | Kenso, a test with a follow-up: where the follow-up to this seed landed, in this same shape. Omitted otherwise. |

### PlacementTestError

An error the testing provider reported for a placement test.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | no | The provider's error text, at most 500 characters. |
| `at` | string (date-time) | no | When the error happened, in UTC. Omitted when not reported. |

### PlacementControl

The control arm: the same senders sent a plain message. Rates are fractions from 0 to 1.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inboxRate` | number (double) | no |  |
| `spamRate` | number (double) | no |  |
| `categoryRate` | number (double) | no |  |
| `missingRate` | number (double) | no |  |
| `counts` | PlacementCounts | no | Seed copies per placement. `total` is the sum of the other five counts. |
| `providers` | array of PlacementProviderResult | no |  |

### PlacementProgress

A Kenso test's sends by state: `read` found or missing, `waiting` not read yet, `failed` not sent or not readable. `finalBy` is when the last read is due while anything waits.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `planned` | integer (int32) | no |  |
| `sent` | integer (int32) | no |  |
| `read` | integer (int32) | no |  |
| `waiting` | integer (int32) | no |  |
| `failed` | integer (int32) | no |  |
| `finalBy` | string (date-time) | no |  |

### PlacementFollowUp

A Kenso test's follow-up, sent from the same inbox to the same seed in the first email's thread.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `format` | string | no | `plain` or `html`. |
| `delayMinutes` | integer (int32) | no | Minutes after the first email was sent that the follow-up went out. |
| `subject` | string | no | Subject the follow-up sent, before its variables were filled. |
| `body` | string | no | Body the follow-up sent, before its variables were filled. Only when you get one test. |
| `counts` | PlacementCounts | no | Follow-ups per placement. Only when you get one test. |
| `providers` | array of PlacementProviderResult | no | The follow-up's results by seed provider. Only when you get one test. |

### PlacementTestTrend

An earlier placement test, for a trend. Rates are fractions from 0 to 1.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | Placement test id. |
| `campaignId` | integer (int64) | no | Campaign the earlier test belongs to. |
| `inboxId` | integer (int64) | no | Inbox the earlier test was limited to. Omitted for a test of a whole domain. |
| `domainId` | integer (int64) | no | Domain the earlier test sent from. Omitted when it has no domain. |
| `status` | string | no | Test status: `pending`, `running`, `completed` or `failed`. |
| `inboxRate` | number (double) | no | Share of the seed copies that landed in the inbox, a fraction from 0 to 1. Omitted until the test completes. |
| `spamRate` | number (double) | no | Share of the seed copies that landed in spam, a fraction from 0 to 1. Omitted until the test completes. |
| `categoryRate` | number (double) | no | Share of the seed copies that landed in a promotions or other category tab, a fraction from 0 to 1. Omitted until the test completes. |
| `missingRate` | number (double) | no | Share of the seed copies that never arrived, a fraction from 0 to 1. Omitted until the test completes. |
| `createdAt` | string (date-time) | no | When the earlier test was created, in UTC. |
| `completedAt` | string (date-time) | no | When the earlier test completed, in UTC. Omitted until then. |

### PlacementAuthSummary

Found messages that carry authentication results, and how many passed each check.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checked` | integer (int32) | no |  |
| `spfPass` | integer (int32) | no |  |
| `dkimPass` | integer (int32) | no |  |
| `dmarcPass` | integer (int32) | no |  |
| `compauthPass` | integer (int32) | no |  |
| `allPass` | integer (int32) | no | Messages where SPF, DKIM and DMARC all passed. |

### PlacementMicrosoftSummary

Microsoft's scores over found Microsoft 365 messages. `bulkHigh`: messages with a high bulk score.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scored` | integer (int32) | no |  |
| `bulkHigh` | integer (int32) | no |  |
| `medianBcl` | number (double) | no |  |
| `medianScl` | number (double) | no |  |

### PlacementSeedAuth

One message's authentication results: `pass`, `fail`, `softfail`, `none` and the like.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `spf` | string | no |  |
| `dkim` | string | no |  |
| `dmarc` | string | no |  |
| `compauth` | string | no |  |

### PlacementSeedMicrosoft

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scl` | integer (int32) | no |  |
| `bcl` | integer (int32) | no |  |
| `cat` | string | no |  |
| `sfv` | string | no |  |
