Inboxes
Your sending inboxes: connect Gmail, Microsoft or SMTP, update settings, verify, disconnect and control warmup.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
inboxId | path | integer (int64) | required | The inbox's id. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List inboxes
/v1/inboxesinboxes.list- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
Returns the workspace's inboxes, a page at a time with limit and cursor. Filter them with status, role or isPrimary.
Set availableForCampaignId to list only the inboxes that campaign can be assigned: the inboxes Kenso can send campaign email from now. That list ignores status and does not combine with isPrimary or role. Its items carry fewer fields, plus isKenSendable and isIngestReady.
Errors:
400 validation_failed:limitis not from 1 to 200,cursoris invalid,statusorroleis not a known value, orisPrimaryorrolecomes withavailableForCampaignId.404 not_found: theavailableForCampaignIdcampaign is not in this workspace.
Requires Delivery view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
status | query | string | optional | Lists only inboxes with this status, such as active or disconnected. |
cursor | query | string | optional | The pagination.nextCursor value from the previous page. Omit it for the first page. |
limit | query | integer (int32) | optional | How many inboxes to return, from 1 to 200. Defaults to 50. |
availableForCampaignId | query | integer (int64) | optional | A campaign id. Lists only the inboxes that campaign can be assigned, and ignores status. |
isPrimary | query | boolean | optional | Set to true to list only primary inboxes (isPrimary: a member's own mailbox on one of the workspace's domains), or false to list only the rest. |
role | query | string | optional | Lists only inboxes with this role: sending, replies or retired. Combines with status and isPrimary, not with availableForCampaignId. |
curl -X GET "https://api.ken.so/v1/inboxes?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of Inbox. Each item has these fields. The response also carries pagination.
Show the 41 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Connect an SMTP inbox
/v1/inboxesinboxes.create- Permission
- Delivery edit
- Rate limit
- 10 requests a minute per API key
Connects a mailbox over SMTP and IMAP and returns it as an inbox. Use it for any mailbox you do not connect through a Gmail or Microsoft connect session.
Send email and password, plus smtpHost, smtpPort, imapHost and imapPort, or a preset that supplies the hosts and ports. username defaults to email, except with a preset whose provider uses a separate username. Kenso logs in to the mailbox before it creates the inbox, so a failed login creates nothing. When the workspace already has an inbox with this address, Kenso connects that inbox instead of creating a new one. Set ownerMemberId to your own member id to connect your own mailbox instead of a shared campaign inbox.
Errors:
400 validation_failed: a required field is missing, the SMTP or IMAP login failed, thepresetis unknown or not available,ownerMemberIdis set on a workspace without theaccountsfeature, or the existing inbox with this address is a Gmail or Microsoft connection or one Kenso set up for you.403 forbidden:ownerMemberIdis not your own member id, orpresetis sent on a workspace without thesending_providersfeature.409 conflict: another inbox in Kenso already uses this address.503 service_unavailable: Kenso could not check the login right now. Try again.
Requires Delivery edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | 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. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | required | The mailbox's email address. Required. |
username | string | optional | The login username. Defaults to email, except with a preset whose provider uses a separate username. |
password | string | required | The login password. Required. Kenso never returns it. |
smtpHost | string | optional | The SMTP server's host name. Required unless you send a preset. |
smtpPort | integer (int32) | optional | The SMTP server's port, such as 587. Required unless you send a preset. |
imapHost | string | optional | The IMAP server's host name. Required unless you send a preset. |
imapPort | integer (int32) | optional | The IMAP server's port, such as 993. Required unless you send a preset. |
smtpStartTls | boolean | optional | Whether to send over STARTTLS. Defaults to true. |
ownerMemberId | integer (int64) | optional | Your own member id, to connect your own mailbox instead of a shared campaign inbox. It must be your member id, and the workspace needs the accounts feature. Omit it for a shared campaign inbox. |
preset | string | optional | A mailbox provider preset slug that Kenso gives you. The preset supplies the hosts, ports and TLS, and Kenso ignores smtpHost, smtpPort, imapHost, imapPort and smtpStartTls. Needs the sending_providers feature. |
replyToInboxId | integer (int64) | optional | With a preset that cannot read mail (no IMAP host): the id of the workspace inbox that receives the replies. Required with such a preset, and ignored otherwise. |
curl -X POST "https://api.ken.so/v1/inboxes" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"username": "email",
"password": "string",
"smtpHost": "string",
"smtpPort": 1,
"imapHost": "string",
"imapPort": 1,
"smtpStartTls": true,
"ownerMemberId": 812,
"preset": "string",
"replyToInboxId": 812
}'Response 201
data is a Inbox.
Show the 41 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get an inbox
/v1/inboxes/{inboxId}inboxes.get- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
Returns one inbox. Only this call includes health: today's sends against the inbox's daily cap, its ramp, its warmup readiness and what blocks it now. Kenso includes health only when the workspace has the agent_send feature, and omits it when it could not read it.
Errors:
404 not_found: no inbox with this id in the workspace.
Requires Delivery view.
curl -X GET "https://api.ken.so/v1/inboxes/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Inbox.
Show the 41 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update an inbox
/v1/inboxes/{inboxId}inboxes.update- Permission
- Delivery edit
- Rate limit
- 4,800 requests a minute per API key
Changes the fields you send and leaves the others unchanged. Null clears a text field or stops forwarding.
Fields:
firstName,lastName,displayName: the sender name. On an inbox Kenso set up for you, Kenso also changes the name at the mailbox provider.signature: the HTML signature.dailySendLimit: the most emails the inbox sends per day, 0 or more. On an inbox bought as an SMTP inbox a 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.tagIds: the inbox's full list of tag ids. It replaces the current tags, and an empty list removes them all.forwardingDestination: an external email address that receives the inbox's incoming mail, or null to stop forwarding. Only inboxes Kenso set up for you can forward.paused:truepauses outreach from the inbox and setspausedAt, or keeps it when the inbox is already paused. Campaign steps, triggers and approved one-to-one Accounts email wait instead of sending, and Kenso plans new contacts on the campaign's other inboxes.falseresumes the inbox and clearspausedAt, and held sends go out on the next dispatch. Warmup, reply sync and replies a member sends keep running while it is paused, and campaign assignments stay.trackOpens: the owner's open tracking for replies sent from their own mailbox. Only a member's own mailbox has it, and only its owner may change it. Open tracking is unavailable: Kenso adds no open-tracking pixel to email, sotrueis refused andfalseis accepted.profileImageUrl: an https URL of the sender photo. Kenso fetches the image once, which uses one unit of the workspace's image-from-URL quota, and saves it after the mailbox provider accepts it. A photo cannot be removed, so null is refused. It needs theinbox_photosfeature and an inbox whoseprofilePhotoSupportisgoogleormicrosoft.
The update is not atomic. Kenso writes trackOpens, then the name, signature, limit and tag fields, then forwarding, then paused, then profileImageUrl, so a failure part way leaves the earlier changes applied. Each write is idempotent, so you can safely retry the same request. A body with no fields returns the inbox unchanged.
Errors:
400 validation_failed: a field is unknown or has the wrong type,trackOpensis sent for a shared campaign inbox,forwardingDestinationis not an external email address or the inbox cannot forward, the mailbox provider refused the new name, the inbox cannot take a photo, ordailySendLimitwould change an SMTP inbox's limit to more than it has earned (or to null). Detail codefeature_disabledonprofileImageUrlwhen the workspace does not have theinbox_photosfeature, andopen_tracking_unavailableontrackOpensfortrue(opens are not tracked); nothing is saved.403 forbidden:trackOpensfrom anyone but the mailbox's owner.404 not_found: no inbox with this id in the workspace, or atagIdsentry is not a tag in this workspace. Kenso checks tags before it writes anything.429 quota_exceeded: the workspace used up its image-from-URL quota.503 service_unavailable: the mailbox provider did not take the photo in time. Try again.
Requires Delivery edit.
Request body
application/json, optional: object.
curl -X PATCH "https://api.ken.so/v1/inboxes/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{}'Response 200
data is a Inbox.
Show the 41 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Start an inbox connect session
/v1/inboxes/connect-sessionsinboxes.create-connect-session- Permission
- Any workspace member except a Network member
- Rate limit
- 10 requests a minute per API key
Returns a Google or Microsoft sign-in link that connects a mailbox to the workspace. Open authorizationUrl before expiresAt. Kenso stores nothing until the connect finishes.
Send provider and purpose. A campaign connect adds a shared campaign mailbox through the Kenso Mail app. A primary connect adds the caller's own mailbox through the Kenso Workspace app. It needs the accounts feature and a signed-in member, or an API key that belongs to a member. If a Google or Microsoft admin must trust the app first, send them to adminUrl.
The connect finishes in the Kenso dashboard. After consent, the provider sends the browser there, and the member who created the session (for an API key, the key's owner) must be signed in to this workspace. Kenso refuses anyone else and connects nothing, so an API key that belongs to no member cannot finish a connect. A primary grant for a mailbox other than the member's login email waits for a confirmation in the dashboard, which needs Delivery edit. Set returnTo to choose the dashboard page the finished connect opens.
Any member may call it. A member with Delivery edit can connect any mailbox. A member with only the approve_own_sends permission can connect only their own login email as a primary inbox, and only when that address is on one of the workspace's domains.
Errors:
400 validation_failed:provider,purposeorreturnTois missing or invalid.403 permission_denied: the caller has neither Delivery edit norapprove_own_sends.403 forbidden: aprimaryconnect from an API key that belongs to no member, or detail codeown_inbox_onlywhen a member with onlyapprove_own_sendsasks for acampaignconnect.404 not_found: aprimaryconnect on a workspace without theaccountsfeature.409 invalid_state: detail codeemail_domain_mismatchwhen a member with onlyapprove_own_sendshas a login email that is not on the workspace's domains (the message says how to fix it), or detail codecalendar_limit_reachedfor aprimaryconnect when the member already has 3 calendar accounts connected.
Open to any workspace member.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
provider | string | required | The mailbox platform: google or microsoft. Required. |
purpose | string | required | What the mailbox is for: campaign (a shared campaign mailbox) or primary (your own mailbox, which needs the accounts feature). Required. |
returnTo | string | optional | The dashboard path to come back to after the connect, such as /42/delivery?tab=inboxes&view=all. It must be a relative path that starts with one /, with no scheme, host, //, backslash or control characters, and at most 512 characters. Omit it to come back to the default page. |
curl -X POST "https://api.ken.so/v1/inboxes/connect-sessions" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"provider": "google",
"purpose": "string",
"returnTo": "/42/delivery?tab=inboxes&view=all"
}'Response 201
data is a InboxConnectSession.
Show the 8 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Verify an inbox connection
/v1/inboxes/{inboxId}/verifyinboxes.verify- Permission
- Delivery edit
- Rate limit
- 10 requests a minute per API key
Tests Kenso's stored connection to the mailbox and returns the inbox. Use it to confirm a connection works, for example after its connection.status showed error.
Errors:
400 validation_failed: the connection test failed, for example because the sign-in expired. The message says why.404 not_found: no inbox with this id in the workspace, or the inbox has no Kenso connection.503 service_unavailable: Kenso could not reach the mailbox provider. Try again.
Requires Delivery edit.
curl -X POST "https://api.ken.so/v1/inboxes/812/verify" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Inbox.
Show the 41 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Disconnect an inbox
/v1/inboxes/{inboxId}/disconnectinboxes.disconnect- Permission
- Delivery edit
- Rate limit
- 4,800 requests a minute per API key
Removes Kenso's connection to the mailbox and returns the inbox with status disconnected. Kenso stops sending through that connection. To connect the mailbox again, use POST /v1/inboxes for an SMTP mailbox or POST /v1/inboxes/connect-sessions for Gmail and Microsoft.
Errors:
404 not_found: no inbox with this id in the workspace, or the inbox has no Kenso connection.503 service_unavailable: Kenso could not reach the mailbox provider. Try again.
Requires Delivery edit.
curl -X POST "https://api.ken.so/v1/inboxes/812/disconnect" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Inbox.
Show the 41 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update many inboxes
/v1/inboxes/bulk-updateinboxes.bulk-update- Permission
- Delivery edit
- Rate limit
- 480 requests a minute per API key
Applies the same change to up to 1,000 inboxes. Send ids, the inbox ids, and at least one field.
Fields:
firstName,lastName: the sender name. Null clears it.signature: the HTML signature. Null clears it.dailySendLimit: the most emails each inbox sends per day, 0 or more. On an inbox bought as an SMTP inbox a 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.tagIds: tag ids to add to every inbox. Tags already on an inbox stay.forwardingDestination: an external email address that receives each inbox's incoming mail, or null to stop forwarding. Only inboxes Kenso set up for you can forward.paused:truepauses outreach from every inbox andfalseresumes it, as onPATCH /v1/inboxes/{inboxId}.profileImageUrl: an https URL of one sender photo for every inbox, as onPATCH /v1/inboxes/{inboxId}. It takes at most 100 ids and no other field.
displayName and trackOpens are only on PATCH /v1/inboxes/{inboxId}. The response has updatedCount, the inboxes that took every change, and failed, one entry with the reason for each inbox that did not. An inbox in failed is never in updatedCount, and an id sent twice counts once.
Errors:
400 validation_failed:idsis empty or has more than 1,000 ids, a field is unknown or has the wrong type,profileImageUrlcomes with another field or more than 100 ids, orforwardingDestinationis not an external email address, ordailySendLimitwould change an SMTP inbox inidsto more than it has earned (or to null), which the message names and which changes no inbox. Detail codefeature_disabledonprofileImageUrlwhen the workspace does not have theinbox_photosfeature.404 not_found: an id is not an inbox in this workspace, or atagIdsentry is not a tag in this workspace. Kenso checks tags before it writes anything.429 quota_exceeded: the workspace used up its image-from-URL quota forprofileImageUrl.
Requires Delivery edit.
Request body
application/json, optional: object.
curl -X POST "https://api.ken.so/v1/inboxes/bulk-update" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{}'Response 200
data is a InboxBulkResult.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Check whether an inbox can send a 1:1 email
/v1/inboxes/{inboxId}/one-to-one-readinessinboxes.get-one-to-one-readiness- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
Says whether an approved 1:1 email that names this inbox goes out now: an account touch, or a workflow send.email step whose fromInbox is this inbox. It applies the checks the send applies, and sends and changes nothing.
senderKind says how the inbox sends: member_mailbox, shared_inbox or sending_identity. When canSend is false, reason says why (receive_only, not_connected, replies_not_read, not_cold_sender, not_primary or paused) and message what fixes it. Such an email waits until the inbox can send.
signatureWarning is brand_domain when a member's mailbox has a saved signature that loads from or links to a Kenso domain the mailbox's own domain does not cover in a way the brand check refuses (an image, a tracking link). A 1:1 email from it still goes, without the signature; signatureMessage says what to remove. Both are omitted otherwise.
Errors:
404 not_found: no inbox with this id in the workspace.
Requires Delivery view.
curl -X GET "https://api.ken.so/v1/inboxes/812/one-to-one-readiness" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a InboxOneToOneReadiness.
Show the 8 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Rename an inbox
/v1/inboxes/{inboxId}/renameinboxes.rename- Permission
- Delivery edit
- Rate limit
- 4,800 requests a minute per API key
Changes the inbox's username, the part of its address before the @. The domain stays the same. Only inboxes Kenso set up for you can be renamed.
Send the new username as localPart (jane.doe, not [email protected]). Kenso renames the mailbox at its provider first, then changes the inbox's email. When the inbox has a sending connection, Kenso reconnects it under the new address: reconnected says whether that happened, and warnings lists any follow-up step that did not finish. The rename itself still succeeded. Renaming to the current username returns the inbox unchanged.
Errors:
400 validation_failedonlocalPart: detail codeinvalidwhen the username is missing or invalid, orprovider_rejectedwhen the mailbox provider refused it, with the provider's reason in the message.404 not_found: no inbox with this id in the workspace.409 invalid_state, detail coderename_not_supported: Kenso did not set up this inbox, so it cannot rename it.409 conflict, detail codeaddress_in_use: another inbox already has the new address.503 service_unavailable: the mailbox provider is not available. Try again.
Requires Delivery edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
localPart | string | optional | The new part before the @, such as jane.doe, not [email protected]. The domain stays the same. |
curl -X POST "https://api.ken.so/v1/inboxes/812/rename" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"localPart": "jane.doe"
}'Response 200
data is a InboxRename.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get an inbox's warmup
/v1/inboxes/{inboxId}/warmupinboxes.get-warmup- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
Returns the inbox's warmup state and Kenso's readiness verdict. Kenso's send gate keeps cold campaign email off an inbox until its warmup has run long enough: readiness shows where the inbox stands.
status is pending while warmup the workspace bought waits to start, and paused while it is paused. An Azure inbox with no warmup subscription reads failed, because Kenso cannot enroll Azure inboxes in warmup. Kenso omits readiness when it could not read it.
Errors:
404 not_found: no inbox with this id in the workspace.
Requires Delivery view.
curl -X GET "https://api.ken.so/v1/inboxes/812/warmup" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a InboxWarmup.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Pause or resume an inbox's warmup
/v1/inboxes/{inboxId}/warmupinboxes.update-warmup- Permission
- Delivery edit
- Rate limit
- 4,800 requests a minute per API key
Send enabled: false to pause the inbox's warmup or enabled: true to resume it. Neither enrolls a mailbox that has no warmup subscription. The response leaves out readiness: read it with GET /v1/inboxes/{inboxId}/warmup.
Errors:
400 validation_failedonenabled:enabledis missing or not a boolean, or Kenso could not change this inbox's warmup. The message is the reason code, such asnot_found(no inbox with this id in the workspace),not_active(pausing warmup that is not running),not_paused(resuming warmup that is not paused) orprovider_error.
Requires Delivery edit.
Request body
application/json, optional: object.
curl -X PATCH "https://api.ken.so/v1/inboxes/812/warmup" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{}'Response 200
data is a InboxWarmup.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Inbox:ThreadsReply templatesScheduled messagesAttachmentsInbox importsLinkedIn accountsWhatsApp accountsWhatsApp settingsAll resources