{"openapi":"3.0.4","info":{"title":"Kenso API: Inboxes","version":"1.1","description":"The Inboxes 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":"inboxes","description":"An inbox is a mailbox that sends your campaign email and receives the replies. Connect a Gmail or Microsoft mailbox through a connect session, or any other mailbox over SMTP and IMAP, then verify or disconnect that connection. Change each inbox's sender name, signature, daily limit, tags, forwarding and pause on one inbox or up to 1,000 at once, read, pause or resume its warmup, and rename an inbox Kenso set up for you. Only inboxes whose `role` is `sending` join campaigns, and a member's own mailbox (`ownerMemberId` set) never does.","x-displayName":"Inboxes"}],"paths":{"/v1/inboxes":{"get":{"tags":["inboxes"],"summary":"List inboxes","description":"Returns the workspace's inboxes, a page at a time with `limit` and `cursor`. Filter them with\n`status`, `role` or `isPrimary`.\n            \nSet `availableForCampaignId` to list only the inboxes that campaign can be assigned: the inboxes Kenso can\nsend campaign email from now. That list ignores `status` and does not combine with `isPrimary` or\n`role`. Its items carry fewer fields, plus `isKenSendable` and `isIngestReady`.\n            \nErrors:\n            \n- `400 validation_failed`: `limit` is not from 1 to 200, `cursor` is invalid, `status` or\n`role` is not a known value, or `isPrimary` or `role` comes with `availableForCampaignId`.\n- `404 not_found`: the `availableForCampaignId` campaign is not in this workspace.\n            \nRequires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.list","parameters":[{"name":"status","in":"query","description":"Lists only inboxes with this `status`, such as `active` or `disconnected`.","schema":{"type":"string"}},{"name":"cursor","in":"query","description":"The `pagination.nextCursor` value from the previous page. Omit it for the first page.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"How many inboxes to return, from 1 to 200. Defaults to 50.","schema":{"maximum":200,"minimum":1,"type":"integer","format":"int32","default":50}},{"name":"availableForCampaignId","in":"query","description":"A campaign id. Lists only the inboxes that campaign can be assigned, and ignores `status`.","schema":{"type":"integer","format":"int64"}},{"name":"isPrimary","in":"query","description":"Set to `true` to list only primary inboxes (`isPrimary`: a member's own mailbox on one of the\nworkspace's domains), or `false` to list only the rest.","schema":{"type":"boolean"}},{"name":"role","in":"query","description":"Lists only inboxes with this `role`: `sending`, `replies` or `retired`. Combines with\n`status` and `isPrimary`, not with `availableForCampaignId`.","schema":{"type":"string"}},{"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/InboxListResponse"}}}},"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":"delivery","access":"view","summary":"Delivery view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"post":{"tags":["inboxes"],"summary":"Connect an SMTP inbox","description":"Connects a mailbox over SMTP and IMAP and returns it as an inbox. Use it for any mailbox you do not connect\nthrough a Gmail or Microsoft connect session.\n            \nSend `email` and `password`, plus `smtpHost`, `smtpPort`, `imapHost` and\n`imapPort`, or a `preset` that supplies the hosts and ports. `username` defaults to\n`email`, except with a preset whose provider uses a separate username. Kenso logs in to the mailbox before\nit creates the inbox, so a failed login creates nothing. When\nthe workspace already has an inbox with this address, Kenso connects that inbox instead of creating a new one.\nSet `ownerMemberId` to your own member id to connect your own mailbox instead of a shared campaign inbox.\n            \nErrors:\n            \n- `400 validation_failed`: a required field is missing, the SMTP or IMAP login failed, the\n`preset` is unknown or not available, `ownerMemberId` is set on a workspace without the\n`accounts` feature, or the existing inbox with this address is a Gmail or Microsoft connection or one\nKenso set up for you.\n- `402 plan_limit_reached`: on Kenso Lifetime, a new inbox would pass the license's inbox limit (one pool\nacross its workspaces). `error.refusal` carries the code `LIFETIME_INBOX_LIMIT_REACHED` and\n`error.details[0].code` is `lifetime_inbox_limit_reached`. Connecting an inbox the workspace already\nhas, or one that sends from Kenso's own provider account, is not refused.\n- `403 forbidden`: `ownerMemberId` is not your own member id, or `preset` is sent on a workspace\nwithout the `sending_providers` feature.\n- `409 conflict`: another inbox in Kenso already uses this address.\n- `503 service_unavailable`: Kenso could not check the login right now. Try again.\n            \nRequires Delivery edit.\n\nRate limit: 10 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.create","parameters":[{"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"}},{"name":"Idempotency-Key","in":"header","description":"A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the `Idempotent-Replayed: true` header, and Kenso does not run the action twice. The same key with a different request answers `422 idempotency_key_reused`. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get `503 service_unavailable` with `Retry-After`. Retry it with the same key. Kenso does not store a `4xx` or `5xx` response, so a retry after one runs the action again. Kenso leaves `password` out of what it compares and keeps no trace of it, so a repeat that changes only that gets the first response: send a new key when you change it.","schema":{"maxLength":200,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInboxRequest"}}}},"responses":{"201":{"description":"Created","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/InboxResponse"}}}},"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":["plan_limit_reached"]},"403":{"description":"Forbidden","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":["forbidden"]},"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":"Conflict","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"]},"422":{"description":"Unprocessable Content","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":["idempotency_key_reused"]},"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"]},"503":{"description":"Service Unavailable","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/ServiceUnavailableError"}}},"x-ken-error-codes":["service_unavailable"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":10,"windowSeconds":60,"per":"api_key"}}},"/v1/inboxes/{inboxId}":{"get":{"tags":["inboxes"],"summary":"Get an inbox","description":"Returns one inbox. Only this call includes `health`: today's sends against the inbox's daily cap, its\nramp, its warmup readiness and what blocks it now. Kenso includes `health` only when the workspace has the\n`agent_send` feature, and omits it when it could not read it.\n            \nErrors:\n            \n- `404 not_found`: no inbox with this id in the workspace.\n            \nRequires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.get","parameters":[{"name":"inboxId","in":"path","description":"The inbox'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/InboxResponse"}}}},"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":"delivery","access":"view","summary":"Delivery view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"patch":{"tags":["inboxes"],"summary":"Update an inbox","description":"Changes the fields you send and leaves the others unchanged. Null clears a text field or stops forwarding.\n            \nFields:\n            \n- `firstName`, `lastName`, `displayName`: the sender name. On an inbox Kenso set up for you,\nKenso also changes the name at the mailbox provider.\n- `signature`: the HTML signature.\n- `dailySendLimit`: the most emails the inbox sends per day, 0 or more. On an inbox bought as an SMTP inbox\na new limit is at most what the inbox has earned: 5 a day at the start, 1 more on each day it sends, up to 10.\n- `tagIds`: the inbox's full list of tag ids. It replaces the current tags, and an empty list removes them\nall.\n- `forwardingDestination`: an external email address that receives the inbox's incoming mail, or null to\nstop forwarding. Only inboxes Kenso set up for you can forward.\n- `paused`: `true` pauses outreach from the inbox and sets `pausedAt`, or keeps it when the inbox\nis already paused. Campaign steps, triggers and approved one-to-one Accounts email wait instead of sending, and\nKenso plans new contacts on the campaign's other inboxes. `false` resumes the inbox and clears\n`pausedAt`, and held sends go out on the next dispatch. Warmup, reply sync and replies a member sends keep\nrunning while it is paused, and campaign assignments stay.\n- `trackOpens`: the owner's open tracking for replies sent from their own mailbox. Only a member's own\nmailbox has it, and only its owner may change it. Open tracking is unavailable: Kenso adds no open-tracking pixel\nto email, so `true` is refused and `false` is accepted.\n- `profileImageUrl`: an https URL of the sender photo. Kenso fetches the image once, which uses one unit of\nthe workspace's image-from-URL quota, and saves it after the mailbox provider accepts it. A photo cannot be\nremoved, so null is refused. It needs the `inbox_photos` feature and an inbox whose\n`profilePhotoSupport` is `google` or `microsoft`.\n            \nThe update is not atomic. Kenso writes `trackOpens`, then the name, signature, limit and tag fields, then\nforwarding, then `paused`, then `profileImageUrl`, so a failure part way leaves the earlier changes\napplied. Each write is idempotent, so you can safely retry the same request. A body with no fields returns the\ninbox unchanged.\n            \nErrors:\n            \n- `400 validation_failed`: a field is unknown or has the wrong type, `trackOpens` is sent for a\nshared campaign inbox, `forwardingDestination` is not an external email address or the inbox cannot\nforward, the mailbox provider refused the new name, the inbox cannot take a photo, or `dailySendLimit`\nwould change an SMTP inbox's limit to more than it has earned (or to null). Detail code\n`feature_disabled` on `profileImageUrl` when the workspace does not have the `inbox_photos`\nfeature, and `open_tracking_unavailable` on `trackOpens` for `true` (opens are not tracked);\nnothing is saved.\n- `403 forbidden`: `trackOpens` from anyone but the mailbox's owner.\n- `404 not_found`: no inbox with this id in the workspace, or a `tagIds` entry is not a tag in this\nworkspace. Kenso checks tags before it writes anything.\n- `429 quota_exceeded`: the workspace used up its image-from-URL quota.\n- `503 service_unavailable`: the mailbox provider did not take the photo in time. Try again.\n            \nRequires Delivery edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.update","parameters":[{"name":"inboxId","in":"path","description":"The inbox'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":{}}}},"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/InboxResponse"}}}},"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"]},"403":{"description":"Forbidden","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":["forbidden"]},"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":["quota_exceeded","rate_limited"]},"503":{"description":"Service Unavailable","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/ServiceUnavailableError"}}},"x-ken-error-codes":["service_unavailable"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/inboxes/connect-sessions":{"post":{"tags":["inboxes"],"summary":"Start an inbox connect session","description":"Returns a Google or Microsoft sign-in link that connects a mailbox to the workspace. Open\n`authorizationUrl` before `expiresAt`. Kenso stores nothing until the connect finishes.\n            \nSend `provider` and `purpose`. A `campaign` connect adds a shared campaign mailbox through the\nKenso Mail app. A `primary` connect adds the caller's own mailbox through the Kenso Workspace app. It needs\nthe `accounts` feature and a signed-in member, or an API key that belongs to a member. If a Google or\nMicrosoft admin must trust the app first, send them to `adminUrl`.\n            \nThe connect finishes in the Kenso dashboard. After consent, the provider sends the browser there, and the member\nwho created the session (for an API key, the key's owner) must be signed in to this workspace. Kenso refuses\nanyone else and connects nothing, so an API key that belongs to no member cannot finish a connect. A\n`primary` grant for a mailbox other than the member's login email waits for a confirmation in the\ndashboard, which needs Delivery edit. Set `returnTo` to choose the dashboard page the finished connect\nopens.\n            \nAny member may call it. A member with Delivery edit can connect any mailbox. A member with only the\n`approve_own_sends` permission can connect only their own login email as a `primary` inbox, and\nonly when that address is on one of the workspace's domains.\n            \nErrors:\n            \n- `400 validation_failed`: `provider`, `purpose` or `returnTo` is missing or invalid.\n- `403 permission_denied`: the caller has neither Delivery edit nor `approve_own_sends`.\n- `403 forbidden`: a `primary` connect from an API key that belongs to no member, or detail code\n`own_inbox_only` when a member with only `approve_own_sends` asks for a `campaign` connect. A\nworkspace key gets it on any connect, before any field is checked: the connect finishes as the member who\nstarted it, and a workspace key is not a person.\n- `404 not_found`: a `primary` connect on a workspace without the `accounts` feature.\n- `409 invalid_state`: detail code `email_domain_mismatch` when a member with only\n`approve_own_sends` has a login email that is not on the workspace's domains (the message says how to fix\nit), or detail code `calendar_limit_reached` for a `primary` connect when the member already has 3\ncalendar accounts connected.\n            \nOpen to any workspace member.\n\nRate limit: 10 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.create-connect-session","parameters":[{"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/CreateInboxConnectSessionRequest"}}}},"responses":{"201":{"description":"Created","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/InboxConnectSessionResponse"}}}},"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"]},"403":{"description":"Forbidden","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":["forbidden","permission_denied"]},"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":"Conflict","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":["invalid_state"]},"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":"workspace_member","summary":"Any workspace member except a Network member"},"x-ken-rate-limit":{"limit":10,"windowSeconds":60,"per":"api_key"}}},"/v1/inboxes/{inboxId}/verify":{"post":{"tags":["inboxes"],"summary":"Verify an inbox connection","description":"Tests Kenso's stored connection to the mailbox and returns the inbox. Use it to confirm a connection works, for\nexample after its `connection.status` showed `error`.\n            \nErrors:\n            \n- `400 validation_failed`: the connection test failed, for example because the sign-in expired. The\nmessage says why.\n- `404 not_found`: no inbox with this id in the workspace, or the inbox has no Kenso connection.\n- `503 service_unavailable`: Kenso could not reach the mailbox provider. Try again.\n            \nRequires Delivery edit.\n\nRate limit: 10 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.verify","parameters":[{"name":"inboxId","in":"path","description":"The inbox'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/InboxResponse"}}}},"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"]},"503":{"description":"Service Unavailable","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/ServiceUnavailableError"}}},"x-ken-error-codes":["service_unavailable"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":10,"windowSeconds":60,"per":"api_key"}}},"/v1/inboxes/{inboxId}/disconnect":{"post":{"tags":["inboxes"],"summary":"Disconnect an inbox","description":"Removes Kenso's connection to the mailbox and returns the inbox with `status` `disconnected`. Kenso\nstops sending through that connection. To connect the mailbox again, use `POST /v1/inboxes` for an SMTP\nmailbox or `POST /v1/inboxes/connect-sessions` for Gmail and Microsoft.\n            \nErrors:\n            \n- `404 not_found`: no inbox with this id in the workspace, or the inbox has no Kenso connection.\n- `503 service_unavailable`: Kenso could not reach the mailbox provider. Try again.\n            \nRequires Delivery edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.disconnect","parameters":[{"name":"inboxId","in":"path","description":"The inbox'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/InboxResponse"}}}},"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"]},"503":{"description":"Service Unavailable","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/ServiceUnavailableError"}}},"x-ken-error-codes":["service_unavailable"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/inboxes/bulk-update":{"post":{"tags":["inboxes"],"summary":"Update many inboxes","description":"Applies the same change to up to 1,000 inboxes. Send `ids`, the inbox ids, and at least one field.\n            \nFields:\n            \n- `firstName`, `lastName`: the sender name. Null clears it.\n- `signature`: the HTML signature. Null clears it.\n- `dailySendLimit`: the most emails each inbox sends per day, 0 or more. On an inbox bought as an SMTP inbox\na new limit is at most what the inbox has earned: 5 a day at the start, 1 more on each day it sends, up to 10.\n- `tagIds`: tag ids to add to every inbox. Tags already on an inbox stay.\n- `forwardingDestination`: an external email address that receives each inbox's incoming mail, or null to\nstop forwarding. Only inboxes Kenso set up for you can forward.\n- `paused`: `true` pauses outreach from every inbox and `false` resumes it, as on\n`PATCH /v1/inboxes/{inboxId}`.\n- `profileImageUrl`: an https URL of one sender photo for every inbox, as on\n`PATCH /v1/inboxes/{inboxId}`. It takes at most 100 ids and no other field.\n            \n`displayName` and `trackOpens` are only on `PATCH /v1/inboxes/{inboxId}`. The response has\n`updatedCount`, the inboxes that took every change, and `failed`, one entry with the reason for each\ninbox that did not. An inbox in `failed` is never in `updatedCount`, and an id sent twice counts\nonce.\n            \nErrors:\n            \n- `400 validation_failed`: `ids` is empty or has more than 1,000 ids, a field is unknown or has the\nwrong type, `profileImageUrl` comes with another field or more than 100 ids, or\n`forwardingDestination` is not an external email address, or `dailySendLimit` would change an SMTP\ninbox in `ids` to more than it has earned (or to null), which the message names and which changes no\ninbox. Detail code `feature_disabled` on `profileImageUrl` when the workspace does not have the\n`inbox_photos` feature.\n- `404 not_found`: an id is not an inbox in this workspace, or a `tagIds` entry is not a tag in this\nworkspace. Kenso checks tags before it writes anything.\n- `429 quota_exceeded`: the workspace used up its image-from-URL quota for `profileImageUrl`.\n            \nRequires Delivery edit.\n\nRate limit: 480 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.bulk-update","parameters":[{"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":{}}}},"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/InboxBulkResultResponse"}}}},"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":["quota_exceeded","rate_limited"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":480,"windowSeconds":60,"per":"api_key"}}},"/v1/inboxes/{inboxId}/one-to-one-readiness":{"get":{"tags":["inboxes"],"summary":"Check whether an inbox can send a 1:1 email","description":"Says whether an approved 1:1 email that names this inbox goes out now: an account touch, or a workflow\n`send.email` step whose `fromInbox` is this inbox. It applies the checks the send applies, and sends and\nchanges nothing.\n            \n`senderKind` says how the inbox sends: `member_mailbox`, `shared_inbox` or\n`sending_identity`. When `canSend` is false, `reason` says why (`receive_only`,\n`not_connected`, `replies_not_read`, `not_cold_sender`, `not_primary` or `paused`) and\n`message` what fixes it. Such an email waits until the inbox can send.\n            \n`signatureWarning` is `brand_domain` when a member's mailbox has a saved signature that loads from or\nlinks to a Kenso domain the mailbox's own domain does not cover in a way the brand check refuses (an image, a\ntracking link). A 1:1 email from it still goes, without the signature; `signatureMessage` says what to remove.\nBoth are omitted otherwise.\n            \nErrors:\n            \n- `404 not_found`: no inbox with this id in the workspace.\n            \nRequires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.get-one-to-one-readiness","parameters":[{"name":"inboxId","in":"path","description":"The inbox'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/InboxOneToOneReadinessResponse"}}}},"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":"delivery","access":"view","summary":"Delivery view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/inboxes/{inboxId}/rename":{"post":{"tags":["inboxes"],"summary":"Rename an inbox","description":"Changes the inbox's username, the part of its address before the @. The domain stays the same. Only inboxes\nKenso set up for you can be renamed.\n            \nSend the new username as `localPart` (`jane.doe`, not `jane.doe@acme.com`). Kenso renames the\nmailbox at its provider first, then changes the inbox's `email`. When the inbox has a sending connection,\nKenso reconnects it under the new address: `reconnected` says whether that happened, and `warnings`\nlists any follow-up step that did not finish. The rename itself still succeeded. Renaming to the current\nusername returns the inbox unchanged.\n            \nErrors:\n            \n- `400 validation_failed` on `localPart`: detail code `invalid` when the username is missing or\ninvalid, or `provider_rejected` when the mailbox provider refused it, with the provider's reason in the\nmessage.\n- `404 not_found`: no inbox with this id in the workspace.\n- `409 invalid_state`, detail code `rename_not_supported`: Kenso did not set up this inbox, so it\ncannot rename it.\n- `409 conflict`, detail code `address_in_use`: another inbox already has the new address.\n- `503 service_unavailable`: the mailbox provider is not available. Try again.\n            \nRequires Delivery edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.rename","parameters":[{"name":"inboxId","in":"path","description":"The inbox'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/RenameInboxRequest"}}}},"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/InboxRenameResponse"}}}},"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":"Conflict","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","invalid_state"]},"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"]},"503":{"description":"Service Unavailable","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/ServiceUnavailableError"}}},"x-ken-error-codes":["service_unavailable"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/inboxes/{inboxId}/warmup":{"get":{"tags":["inboxes"],"summary":"Get an inbox's warmup","description":"Returns the inbox's warmup state and Kenso's readiness verdict: `readiness` shows how far any warmup has\nrun. It is evidence only, not a condition for sending.\n            \nWarmup is off by default: a new inbox reads `not_started` and ramps up its sends instead. `status` is\n`pending` while warmup the workspace bought waits to start, or after someone turned warmup on and Kenso\nhas not enrolled the inbox yet, and `paused` while it is paused. An Azure inbox with no warmup subscription\nreads `failed`, because Kenso cannot enroll Azure inboxes in warmup. Kenso omits `readiness` when it\ncould not read it. `pool` shows the inbox's place in the Kenso warmup pool when it is a member.\n            \nErrors:\n            \n- `404 not_found`: no inbox with this id in the workspace.\n            \nRequires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.get-warmup","parameters":[{"name":"inboxId","in":"path","description":"The inbox'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/InboxWarmupResponse"}}}},"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":"delivery","access":"view","summary":"Delivery view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"patch":{"tags":["inboxes"],"summary":"Turn an inbox's warmup on or off","description":"Send `enabled: false` to pause the inbox's warmup or `enabled: true` to turn it on. Warmup is off by\ndefault: new inboxes ramp up their sends instead. Turning it on resumes paused warmup, or, for a Google inbox\nKenso provided that has no warmup yet, answers with `status` `pending` while Kenso enrolls it, within\nabout 10 minutes. The response leaves out `readiness`: read it with\n`GET /v1/inboxes/{inboxId}/warmup`.\n            \nFor an inbox in the Kenso warmup pool, or a Google or Microsoft inbox of a workspace that joined it,\n`enabled: true` switches the inbox on for the pool and `enabled: false` switches it off.\n            \nErrors:\n            \n- `400 validation_failed` on `enabled`: `enabled` is missing or not a boolean, or Kenso could\nnot change this inbox's warmup. The message is the reason code, such as `not_found` (no inbox with this\nid in the workspace), `not_active` (pausing warmup that is not running), `not_paused`,\n`unknown_status` or `missing_uid` (turning on warmup for an inbox Kenso cannot enroll, such as the\nworkspace's own mailbox or an Outlook inbox) or `provider_error`.\n- `409 invalid_state`: the inbox's workspace is not in the warmup pool.\n- `503 service_unavailable`: the warmup pool could not take the change; retry later.\n            \nRequires Delivery edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.","operationId":"inboxes.update-warmup","parameters":[{"name":"inboxId","in":"path","description":"The inbox'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":{}}}},"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/InboxWarmupResponse"}}}},"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":"Conflict","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":["invalid_state"]},"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"]},"503":{"description":"Service Unavailable","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/ServiceUnavailableError"}}},"x-ken-error-codes":["service_unavailable"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":4800,"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."},"CreateInboxConnectSessionRequest":{"required":["provider","purpose"],"type":"object","properties":{"provider":{"type":"string","description":"The mailbox platform: `google` or `microsoft`. Required."},"purpose":{"type":"string","description":"What the mailbox is for: `campaign` (a shared campaign mailbox) or `primary` (your own mailbox, which\nneeds the `accounts` feature). Required."},"returnTo":{"type":"string","description":"The dashboard path to come back to after the connect, such as `/42/delivery?tab=inboxes&view=all`.\nIt must be a relative path that starts with one `/`, with no scheme, host, `//`, backslash or control\ncharacters, and at most 512 characters. Omit it to come back to the default page.","nullable":true}},"additionalProperties":false,"description":"The mailbox to connect through a Gmail or Microsoft sign-in."},"CreateInboxRequest":{"required":["email","password"],"type":"object","properties":{"email":{"type":"string","description":"The mailbox's email address. Required."},"username":{"type":"string","description":"The login username. Defaults to `email`, except with a `preset` whose provider uses a separate\nusername.","nullable":true},"password":{"type":"string","description":"The login password. Required. Kenso never returns it."},"smtpHost":{"type":"string","description":"The SMTP server's host name. Required unless you send a `preset`.","nullable":true},"smtpPort":{"type":"integer","description":"The SMTP server's port, such as 587. Required unless you send a `preset`.","format":"int32","nullable":true},"imapHost":{"type":"string","description":"The IMAP server's host name. Required unless you send a `preset`.","nullable":true},"imapPort":{"type":"integer","description":"The IMAP server's port, such as 993. Required unless you send a `preset`.","format":"int32","nullable":true},"smtpStartTls":{"type":"boolean","description":"Whether to send over STARTTLS. Defaults to `true`.","nullable":true},"ownerMemberId":{"type":"integer","description":"Your own member id, to connect your own mailbox instead of a shared campaign inbox. It must be your member id,\nand the workspace needs the `accounts` feature. Omit it for a shared campaign inbox.","format":"int64","nullable":true},"preset":{"type":"string","description":"A mailbox provider preset slug that Kenso gives you. The preset supplies the hosts,\nports and TLS, and Kenso ignores `smtpHost`, `smtpPort`, `imapHost`, `imapPort` and\n`smtpStartTls`. Needs the `sending_providers` feature.","nullable":true},"replyToInboxId":{"type":"integer","description":"With a preset that cannot read mail (no IMAP host): the id of the workspace inbox that receives the\nreplies. Required with such a preset, and ignored otherwise.","format":"int64","nullable":true}},"additionalProperties":false,"description":"A mailbox to connect over SMTP and IMAP."},"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`."},"Inbox":{"type":"object","properties":{"id":{"type":"integer","description":"The inbox id.","format":"int64"},"email":{"type":"string","description":"The inbox's email address."},"firstName":{"type":"string","description":"The sender's first name. Omitted when not set.","nullable":true},"lastName":{"type":"string","description":"The sender's last name. Omitted when not set.","nullable":true},"displayName":{"type":"string","description":"The sender name recipients see. Omitted when not set.","nullable":true},"signature":{"type":"string","description":"The HTML signature Kenso adds to email from this inbox. Omitted when not set.","nullable":true},"status":{"type":"string","description":"The inbox's state: `active`, `warmup`, `disconnected`, `paused`, `banned`,\n`connection_error`, `deleted`, `inactive` (its domain is about to expire), `replaced` (a\nrename gave the mailbox a new address, and this inbox keeps only its history) or `pending_provisioning`\n(Kenso is still setting up the mailbox). Only an `active` inbox sends campaign email. A pause shows in\n`pausedAt`, not here."},"role":{"type":"string","description":"What the inbox is for: `sending` (a campaign inbox), `replies` (the workspace's shared replies\ninbox, the address campaign replies go to) or `retired` (a campaign inbox Kenso switched to receive\nonly). A `replies` or `retired` inbox never joins a campaign or warmup, and Kenso keeps reading its\nmail."},"captureUntil":{"type":"string","description":"When a `retired` inbox's reply capture window ends, in UTC. Nothing changes automatically then: Kenso\nkeeps reading the inbox until it is deleted. Omitted unless the inbox is retired.","format":"date-time","nullable":true},"renewalEndsWindowEarly":{"type":"boolean","description":"For a `retired` inbox: true when its domain's registration expires before `captureUntil` and auto-renew\nis off. The domain can then lapse, and a new owner would get the replies. False when auto-renew is on, the\nregistration runs past `captureUntil`, or `captureUntil` has passed. Omitted when the inbox is not\nretired, or when Kenso does not know its domain or the registration's expiry.","nullable":true},"provider":{"type":"string","description":"The mailbox platform: `google`, `microsoft`, `azure` or `custom_smtp`.","nullable":true},"domainId":{"type":"integer","description":"The id of the inbox's domain in Kenso. Omitted when the domain is not one Kenso manages.","format":"int64","nullable":true},"dailySendLimit":{"type":"integer","description":"The most emails the inbox sends per day. Omitted when not set.","format":"int32","nullable":true},"forwarding":{"type":"string","description":"Where the inbox's incoming mail is forwarded: `ken_hosted` (to a Kenso address) or `client` (to\n`forwardingDestination`, an address of yours). Omitted when the inbox does not forward.","nullable":true},"forwardingDestination":{"type":"string","description":"The email address that receives the inbox's forwarded mail. Omitted when there is none.","nullable":true},"profileImageUrl":{"type":"string","description":"The URL of the inbox's sender photo: the photo Kenso set, else the photo the mailbox provider reports. Omitted\nwhen there is none.","nullable":true},"profilePhotoSupport":{"type":"string","description":"Whether Kenso can set this inbox's sender photo: `google` (a Google mailbox Kenso set up for you),\n`microsoft` (a Microsoft or Azure mailbox Kenso set up for you), `google_account` or\n`microsoft_account` (a member's own mailbox, whose photo only its owner can change) or `none`.\nSetting a photo also needs the workspace's `inbox_photos` feature.","nullable":true},"profilePhotoStatus":{"type":"string","description":"Whether the photo Kenso set reached the mailbox: `pending` (queued for a Microsoft or Azure mailbox and\nnot applied yet), `applied` or `failed` (no photo shows, and `profilePhotoError` says why).\nOmitted when Kenso set no photo, or set it before Kenso tracked this.","nullable":true},"profilePhotoStatusAt":{"type":"string","description":"When `profilePhotoStatus` last changed, in UTC. For `pending`, when the photo was queued.","format":"date-time","nullable":true},"profilePhotoError":{"type":"string","description":"Why the photo failed. Present only when `profilePhotoStatus` is `failed`.","nullable":true},"tagIds":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Ids of the workspace's tags on this inbox. Empty when it has none."},"createdAt":{"type":"string","description":"When the inbox was added to Kenso, in UTC.","format":"date-time","nullable":true},"updatedAt":{"type":"string","description":"When Kenso last synced the inbox's details, in UTC.","format":"date-time","nullable":true},"pausedAt":{"type":"string","description":"When a member paused outreach from this inbox, in UTC. Omitted when it is not paused. A paused inbox holds\ncampaign steps, triggers and approved one-to-one Accounts email, while warmup and reply sync keep running.\nSeparate from `status`.","format":"date-time","nullable":true},"isKenSendable":{"type":"boolean","description":"Whether Kenso can send campaign email from this inbox now. Present only on lists of the inboxes a campaign uses\nor can use.","nullable":true},"sendState":{"type":"string","description":"Whether the inbox can send now, and if not, the first reason why: `ready` (it sends), `gone`\n(deleted, replaced, turned off or banned, so it never sends again), `receive_only` (a `replies` or\n`retired` inbox), `needs_reconnect` (its sign-in failed or its connection is gone: reconnect it),\n`paused` (a member paused it, or its provider did), `warming` (warmup is not finished),\n`blocked_until` (a send block is in force until `sendBlock.until`) or `not_sendable` (Kenso\ncannot send from it for another reason, such as setup that is not finished or a daily limit of 0). For a shared\ncampaign inbox, `ready` means it is in the pool Kenso sends campaign email from, the same pool the launch\ncheck counts. For a member's own inbox, it means its owner can send from it. The warmup age gate and today's\ncap are separate (`warmup.daysLeft`, `health`). A paused inbox still sends the replies a member\nwrites. Omitted on the responses that create an inbox (read it again), and when Kenso could not work it out.","nullable":true},"oneToOneReadiness":{"allOf":[{"$ref":"#/components/schemas/InboxOneToOneReadiness"}],"description":"Whether an approved one-to-one email that names this inbox goes out now (an account's Sends from, or the From\nof a workflow's send step), and if not, why and what fixes it. The same answer as\n`GET /v1/inboxes/{inboxId}/one-to-one-readiness`. Separate from `sendState`, which is about campaign\nemail. Omitted on lists of the inboxes a campaign uses or can use, on the responses that create an inbox (read\nit again), and when Kenso could not work it out."},"sendingProvider":{"type":"string","description":"The slug of the provider account this inbox sends through, when the workspace connected that account itself.\nNull on every other inbox. An SMTP inbox Kenso runs reads `provider: custom_smtp` and no\n`sendingProvider`; Kenso staff get the slug on every provider inbox.","nullable":true},"isIngestReady":{"type":"boolean","description":"Whether Kenso can read replies from this inbox. An inbox can send before Kenso can read its replies. Present\nonly on lists of the inboxes a campaign uses or can use.","nullable":true},"ownerMemberId":{"type":"integer","description":"The member whose own mailbox this is. Omitted for a shared campaign inbox. A member's own mailbox never joins\na campaign or warmup.","format":"int64","nullable":true},"isPrimary":{"type":"boolean","description":"True when a member owns the inbox and its address is on one of the workspace's domains: its email domain or a\ndomain listed under Settings > Company. Kenso works it out on each read, so it follows later changes to that\nlist. Only a primary inbox sends the member's one-to-one Accounts email."},"isAccountsDefault":{"type":"boolean","description":"True on the one inbox per member that their accounts' one-to-one email goes out from when nothing names another:\ntheir lowest-id primary inbox that is connected and can send. An account's Sends from inbox, or the From of a\nworkflow's send step, picks another; left on Automatic, a workflow's email goes out from the account's Sends from\ninbox, else from this inbox of the account's owner. False on every other inbox, including a primary inbox that is\ndisconnected or not the member's first one."},"connectionApp":{"type":"string","description":"The Kenso app a Google or Microsoft connection was granted to: `ken_mail` (campaign mailboxes) or\n`ken_workspace` (a member's own mailbox). Omitted for SMTP and unconnected inboxes.","nullable":true},"trackOpens":{"type":"boolean","description":"The owner's open tracking option, off by default. Open tracking is unavailable: Kenso adds no open-tracking pixel\nto replies or to one-to-one Accounts email, and turning it on is refused (`open_tracking_unavailable`).\nPresent only on a member's own mailbox.","nullable":true},"usedBy":{"allOf":[{"$ref":"#/components/schemas/UsedBy"}],"description":"The live campaigns that send through this inbox, and whether Accounts uses it. Omitted when Kenso could not\nread it."},"warmup":{"allOf":[{"$ref":"#/components/schemas/InboxWarmupSummary"}],"description":"Warmup progress toward the minimum warmup age Kenso requires before cold sends. Omitted when no warmup sends\nwere reported for the inbox, unless an outreach bypass from Kenso covers it. The full warmup state is\n`GET /v1/inboxes/{inboxId}/warmup`."},"sendBlock":{"allOf":[{"$ref":"#/components/schemas/InboxSendBlock"}],"description":"The block that stops campaign sends from the inbox now. Omitted when the inbox is not blocked."},"healthScore":{"type":"integer","description":"Kenso's health score for the inbox, from 0 to 100, from the latest mailbox health check. Omitted when no check\nhas reported on the inbox.","format":"int32","nullable":true},"lastSentAt":{"type":"string","description":"The inbox's last send its mail server accepted, in UTC. Warmup sends do not count. Omitted when it sent\nnothing in the last 30 days, or when Kenso could not read it.","format":"date-time","nullable":true},"connection":{"allOf":[{"$ref":"#/components/schemas/InboxConnection"}],"description":"The health of Kenso's own connection to the mailbox. Omitted when Kenso has no connection of its own to the\nmailbox."},"health":{"allOf":[{"$ref":"#/components/schemas/InboxHealth"}],"description":"Today's sends against the inbox's daily cap, its ramp, its warmup readiness and what holds it back now. Only\non `GET /v1/inboxes/{inboxId}`, never on a list, and only when the workspace has the `agent_send`\nfeature. Omitted otherwise, and when Kenso could not read it."}},"additionalProperties":false,"description":"An inbox: a mailbox the workspace sends from and reads replies from. Which fields a response carries depends on\nthe call. Lists of the inboxes a campaign uses or can use carry fewer fields.","example":{"id":5530,"email":"alex@mail.example.com","firstName":"Alex","lastName":"Rivera","displayName":"Alex Rivera","signature":"Alex Rivera\nNorthwind Outbound","status":"active","role":"sending","provider":"google","domainId":640,"dailySendLimit":30,"profilePhotoSupport":"google","tagIds":[],"createdAt":"2026-08-31T10:15:00Z","updatedAt":"2026-10-14T09:41:27Z","isPrimary":false,"isAccountsDefault":false,"usedBy":{"campaigns":[{"id":4821,"name":"Q4 SaaS founders","status":"active"}],"accounts":false},"warmup":{"daysLeft":0},"healthScore":94,"lastSentAt":"2026-10-14T09:12:40Z"}},"InboxBulkFailure":{"type":"object","properties":{"id":{"type":"integer","description":"The inbox id.","format":"int64"},"message":{"type":"string","description":"Why the inbox was not updated."}},"additionalProperties":false,"description":"An inbox a bulk update did not change."},"InboxBulkResult":{"type":"object","properties":{"updatedCount":{"type":"integer","description":"How many inboxes were updated. With `profileImageUrl` or `forwardingDestination`, only the inboxes\nwhose mailbox took the change count, and the rest are in `failed`.","format":"int32"},"failed":{"type":"array","items":{"$ref":"#/components/schemas/InboxBulkFailure"},"description":"The inboxes that were not updated, each with the reason. Empty when every inbox was updated."}},"additionalProperties":false,"description":"The result of updating many inboxes in one call."},"InboxBulkResultResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/InboxBulkResult"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"InboxConnectSession":{"type":"object","properties":{"provider":{"type":"string","description":"The mailbox platform: `google` or `microsoft`."},"purpose":{"type":"string","description":"What the connection is for: `primary` (a member's own mailbox), `campaign` (a shared campaign\nmailbox) or `calendar` (a member's calendar alone, from\n`POST /v1/calendar-accounts/connect-sessions`)."},"appName":{"type":"string","description":"The name of the Kenso app the user grants access to: Kenso Workspace for `primary` and `calendar`,\nKenso Mail for `campaign`."},"clientId":{"type":"string","description":"The app's public OAuth client id, for an admin who has to trust the app first."},"authorizationUrl":{"type":"string","description":"The sign-in URL to open in a browser. It works until `expiresAt`."},"adminUrl":{"type":"string","description":"Where an admin trusts the app for the whole organization: the Google Admin console, or the Microsoft admin\nconsent URL."},"adminConsentUrl":{"type":"string","description":"The Microsoft admin consent URL for the app. Omitted for Google.","nullable":true},"expiresAt":{"type":"string","description":"When `authorizationUrl` stops working, in UTC.","format":"date-time"}},"additionalProperties":false,"description":"A Gmail or Microsoft connect session. Open `authorizationUrl` before `expiresAt` to grant Kenso access\nto the mailbox, or start a new session."},"InboxConnectSessionResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/InboxConnectSession"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"InboxConnection":{"type":"object","properties":{"status":{"type":"string","description":"Connection state: `connected`, `disconnected`, `auth_expired` (the mailbox must be signed in\nagain) or `error`."},"checkedAt":{"type":"string","description":"When Kenso last checked the connection with the mail provider (UTC). Omitted before the first check.","format":"date-time","nullable":true},"error":{"type":"string","description":"Short reason from the mail provider, at most 300 characters, when `status` is `auth_expired` or\n`error`. It never contains credentials. Omitted otherwise.","nullable":true}},"additionalProperties":false,"description":"The health of Kenso's own connection to a mailbox, which it uses to send and to read replies."},"InboxHealth":{"type":"object","properties":{"sentToday":{"type":"integer","description":"Emails the mail provider accepted from this inbox so far in its send day, from campaigns and one-to-one replies.","format":"int32"},"reservedToday":{"type":"integer","description":"Emails being sent right now, which already count against today's limit.","format":"int32"},"limit":{"type":"integer","description":"Today's limit: the inbox's daily limit after its ramp-up, its domain's ramp-up and the mail provider's maximum.","format":"int32"},"remaining":{"type":"integer","description":"Emails the inbox can still send today: `limit` minus `sentToday` and `reservedToday`, never below 0.","format":"int32"},"dayEndsAt":{"type":"string","description":"When the send day ends (UTC). The day follows the time zone of the inbox's campaigns, or New York when none\nsets one.","format":"date-time"},"rampDay":{"type":"integer","description":"Day of the ramp-up: 1 during the first 24 hours of sending, and still returned once the ramp-up is over. Omitted\nwhen the limit could not be worked out from send history.","format":"int32","nullable":true},"rampComplete":{"type":"boolean","description":"True when the ramp-up reached its target and no longer lowers the limit. False when `rampDay` is omitted."},"warmupReadiness":{"type":"string","description":"Whether warmup cleared the inbox to send, with the same values as `readiness.outcome` on\n`GET /v1/inboxes/{inboxId}/warmup`: `ready`, `too_young`, `unconfirmed`, `bypassed`,\n`provider_stale` or `unavailable` (no recent warmup data, or no result for the inbox)."},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/InboxHealthBlock"},"description":"What holds the inbox back now. Empty when nothing does."},"bounceRate7d":{"type":"number","description":"Hard bounces divided by accepted emails over the last 7 days, from 0 to 1. Omitted when nothing was accepted in\nthat window, and when `rampDay` is omitted.","format":"double","nullable":true},"notes":{"type":"array","items":{"$ref":"#/components/schemas/InboxHealthNote"},"description":"What the inbox's state shows that holds no send now. Empty when there is nothing to show. Not a block: the\ninbox keeps sending."}},"additionalProperties":false,"description":"An inbox's sending health today: what it sent, what it may still send, and what holds it back."},"InboxHealthBlock":{"type":"object","properties":{"kind":{"type":"string","description":"What holds it back: `paused` (a member paused the inbox), `send_blocked` (Kenso blocked it, for\nexample after a failed placement test) or `sending_paused` (a pause on the inbox, its domain or the\nworkspace, that holds sends now: an operator's pause, which stops campaign sends and new agent threads, or any\npause once capacity limits are enforced)."},"reason":{"type":"string","description":"Why, as recorded: usually a code such as `mailbox_hard_bounce_rate`. Omitted when no reason was recorded.","nullable":true},"until":{"type":"string","description":"When the block ends (UTC). Omitted for `paused`, which lasts until a member resumes the inbox.","format":"date-time","nullable":true}},"additionalProperties":false,"description":"One thing that holds an inbox back from sending."},"InboxHealthNote":{"type":"object","properties":{"kind":{"type":"string","description":"`sending_pause_observed`: an automatic pause (any pause Kenso opened itself, for example after a placement\ntest, bounces, complaints or a domain breach, and not an operator's) covers the inbox, its domain or the\nworkspace, but while capacity limits are not enforced it holds no send, so the inbox keeps sending."},"reason":{"type":"string","description":"Why, as recorded: usually a code such as `domain_bounce`. Omitted when no reason was recorded.","nullable":true},"until":{"type":"string","description":"When the pause ends (UTC).","format":"date-time","nullable":true}},"additionalProperties":false,"description":"Something an inbox's state shows that holds no send."},"InboxListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/Inbox"},"description":"The items on this page."},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"}],"description":"Where this page ends and how to get the next one."}},"additionalProperties":false,"description":"The body of a successful list operation: one page of results in `data`, and `pagination` to get the next\npage."},"InboxOneToOneReadiness":{"type":"object","properties":{"inboxId":{"type":"integer","description":"The inbox.","format":"int64"},"email":{"type":"string","description":"Its address."},"senderKind":{"type":"string","description":"How it sends a 1:1 email: `member_mailbox` (a member's own mailbox, only as their primary inbox),\n`shared_inbox` (a shared campaign inbox on a cold sending domain) or `sending_identity` (a sending\nprovider identity, through its provider connection)."},"canSend":{"type":"boolean","description":"True when an approved 1:1 email touch that names this inbox (an Accounts touch, or a workflow\n`send.email` step's `fromInbox`) goes out now, and its reply comes back to Kenso. False when the touch\nwould wait (`connect_inbox`, or `inbox_paused` for `paused`)."},"reason":{"type":"string","description":"Why it cannot send; omitted when canSend is true. `receive_only`: retired or the replies\ninbox. `not_connected`: its connection, or a sending identity's provider connection, cannot send now.\n`replies_not_read`: a sending identity whose replies would not reach Kenso. `not_cold_sender`: not on\none of the workspace's cold sending domains. `not_primary`: a member's mailbox off the workspace's domains.\n`paused`: a member paused it. Tolerate values not listed here.","nullable":true},"message":{"type":"string","description":"What fixes it, for a person; omitted when canSend is true.","nullable":true},"signatureWarning":{"type":"string","description":"`brand_domain` when the inbox is a member's mailbox whose saved signature loads from or links to a\nKenso domain the mailbox's own domain does not cover in a way the brand check refuses (an image, a Kenso tracking or\nsystem link), so a 1:1 email from it goes out without the signature (the email itself still goes). A plain link to a\nKenso site is allowed and is no warning. Omitted when the signature goes out as saved, or the inbox adds none.\nTolerate values not listed here.","nullable":true},"signatureMessage":{"type":"string","description":"What fixes the signature, for a person, naming what the check found; omitted with signatureWarning.","nullable":true}},"additionalProperties":false,"description":"Whether an inbox can send a 1:1 email now, and if not why."},"InboxOneToOneReadinessResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/InboxOneToOneReadiness"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"InboxRename":{"type":"object","properties":{"inbox":{"allOf":[{"$ref":"#/components/schemas/Inbox"}],"description":"The inbox as it is now, with its new `email`."},"reconnected":{"type":"boolean","description":"True when Kenso reconnected the inbox's sending connection under the new address."},"warnings":{"type":"array","items":{"type":"string"},"description":"Follow-up steps that did not finish (the reconnect, for example). The rename itself succeeded."}},"additionalProperties":false,"description":"The result of renaming an inbox."},"InboxRenameResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/InboxRename"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"InboxResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/Inbox"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"InboxSendBlock":{"type":"object","properties":{"reason":{"type":"string","description":"Why Kenso blocked the inbox, as a code such as `mailbox_hard_bounce_rate`. Omitted when a person set the\nblock, or a rename did.","nullable":true},"until":{"type":"string","description":"When the block ends, in UTC. The inbox sends no campaign email until then.","format":"date-time"}},"additionalProperties":false,"description":"A block that stops campaign sends from an inbox until a set time."},"InboxWarmup":{"type":"object","properties":{"status":{"type":"string","description":"The warmup state: `not_started`, `pending` (warmup is being switched on), `in_progress`,\n`paused`, `completed`, `maintenance`, `failed` or `degraded`. An Azure inbox with no\nwarmup plan is `failed`, because Kenso cannot start warmup on Azure."},"enabled":{"type":"boolean","description":"True when warmup is switched on: the inbox is warming up or its warmup is starting."},"startedAt":{"type":"string","description":"When warmup started, in UTC. When Kenso has no start time, the first day warmup sends were reported. Omitted\nwhen neither is known.","format":"date-time","nullable":true},"completedAt":{"type":"string","description":"When warmup completed, in UTC. Omitted until it does.","format":"date-time","nullable":true},"readiness":{"allOf":[{"$ref":"#/components/schemas/InboxWarmupReadiness"}],"description":"Whether the inbox is warm enough for cold sends. Only on `GET /v1/inboxes/{inboxId}/warmup`, not on the\nupdate response, and omitted when Kenso could not read it."},"pool":{"allOf":[{"$ref":"#/components/schemas/InboxWarmupPool"}],"description":"The inbox's place in the Kenso warmup pool. Present only when the inbox is a pool member. Unless its pool\n`status` is `off`, the `status` and `enabled` above come from the pool."}},"additionalProperties":false,"description":"An inbox's warmup: its state, its dates and whether it is warm enough for cold sends."},"InboxWarmupPool":{"type":"object","properties":{"status":{"type":"string","description":"The pool status: `waiting`, `probation`, `active`, `watch`, `throttled`,\n`quarantined`, `ejected`, `tapering`, `paused`, `not_eligible` or `off`."},"reasonCode":{"type":"string","description":"Why the inbox has this status, as a code such as `seed_spam`. Omitted when there is none.","nullable":true},"role":{"type":"string","description":"`full`, `reply_only` or `send_only`. Omitted until Kenso checked what the mailbox can do.","nullable":true},"isEnabled":{"type":"boolean","description":"True when the inbox is switched on for the pool."}},"additionalProperties":false,"description":"An inbox's place in the Kenso warmup pool."},"InboxWarmupReadiness":{"type":"object","properties":{"outcome":{"type":"string","description":"The verdict: `ready`, `bypassed` (an outreach bypass from Kenso covers the inbox),\n`unconfirmed` (no recent warmup sends reported), `too_young` (younger than\n`minimumWarmupDays`), `provider_stale` (the warmup service reported nothing recently, so the check\nholds nothing) or `unavailable` (no fresh warmup data, or the read failed, so the check holds nothing)."},"isReady":{"type":"boolean","description":"True when warmup is confirmed: the outcome is `ready` or `bypassed`."},"isHeld":{"type":"boolean","description":"True when the check keeps cold sends off this inbox, as long as `isEnforced` is true."},"isEnforced":{"type":"boolean","description":"True when the check holds inboxes now. When false, a held inbox still sends."},"firstWarmupSendDate":{"type":"string","description":"The first day warmup sends were reported, as YYYY-MM-DD in UTC. Omitted when none were.","nullable":true},"lastWarmupSendDate":{"type":"string","description":"The latest day warmup sends were reported with warmup on, as YYYY-MM-DD in UTC. Omitted when none were.","nullable":true},"daysInWarmup":{"type":"integer","description":"Whole days since the first reported warmup send. Omitted when none was reported.","format":"int32","nullable":true},"minimumWarmupDays":{"type":"integer","description":"The minimum warmup age, in days, the check requires before cold sends.","format":"int32"},"hasMinWeekOverride":{"type":"boolean","description":"True when Kenso waived the minimum warmup age for this inbox or its domain."},"hasOutreachBypass":{"type":"boolean","description":"True when Kenso granted an outreach bypass for this inbox or its domain, which skips the warmup check."}},"additionalProperties":false,"description":"The verdict of Kenso's warmup check, which keeps cold sends off an inbox until it is warm."},"InboxWarmupResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/InboxWarmup"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"InboxWarmupSummary":{"type":"object","properties":{"daysLeft":{"type":"integer","description":"Days until the inbox reaches the minimum warmup age, counted from its first reported warmup send. 0 once it\ngets there, or when Kenso waived the age for the inbox. An outreach bypass from Kenso reports 0 even before any\nwarmup send.","format":"int32","nullable":true}},"additionalProperties":false,"description":"An inbox's progress toward the minimum warmup age Kenso requires before cold sends."},"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."},"Pagination":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Send this value as `cursor` to get the next page. Omitted on the last page.","nullable":true},"hasMore":{"type":"boolean","description":"True when more items follow this page. Stop paging when it is false."},"total":{"type":"integer","description":"Deprecated: the same number as `totalCount`. Read `totalCount`.","format":"int32","nullable":true,"deprecated":true},"totalCount":{"type":"integer","description":"The number of items that match the list's filters, across all pages. Omitted when the list does not count them.","format":"int32","nullable":true},"isTotalCapped":{"type":"boolean","description":"True when `totalCount` stopped counting at its cap, so more items match than it says. Keep paging with\n`hasMore`. Omitted when `totalCount` is exact. Only `GET /v1/threads` with `q` caps its total.","nullable":true}},"additionalProperties":false,"description":"Where a list page ends and how to get the next page."},"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."},"RenameInboxRequest":{"type":"object","properties":{"localPart":{"type":"string","description":"The new part before the `@`, such as `jane.doe`, not `jane.doe@acme.com`. The domain stays the\nsame.","nullable":true}},"additionalProperties":false,"description":"The new address of an inbox."},"ServiceUnavailableError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The body of a `503`: the error body (`Failure`). When Kenso cannot check the API key, its code is `auth_unavailable`, with `Retry-After: 5`. Until November 2026 the API key check in front of the operations answered `{ \"error\": \"Authentication is temporarily unavailable\" }` (`ApiKeyError`) there instead, so handle both shapes. Retry after the `Retry-After` seconds."},"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."},"UsedBy":{"type":"object","properties":{"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/UsedByCampaign"},"description":"The live campaigns (scheduled, launching or sending) that use this inbox or LinkedIn account, ordered by id.\nEmpty when there are none."},"accounts":{"type":"boolean","description":"True when Accounts uses it for one-to-one outreach. An inbox counts when it is its member's primary inbox\n(`isPrimary`). A LinkedIn account counts when the member who connected it owns at least one live account\nin Accounts, because an account's LinkedIn steps go out from the LinkedIn account its owner connected.","nullable":true}},"additionalProperties":false,"description":"What an inbox or LinkedIn account is used for: the live campaigns that send through it, and whether Accounts\nuses it for one-to-one outreach."},"UsedByCampaign":{"type":"object","properties":{"id":{"type":"integer","description":"The campaign id.","format":"int64"},"name":{"type":"string","description":"The campaign's name."},"status":{"type":"string","description":"The campaign's status, with the same values as `GET /v1/campaigns`."}},"additionalProperties":false,"description":"A live campaign that uses an inbox or LinkedIn account."}}}}