Inboxes inboxes
Connected sending inboxes. create connects an SMTP/IMAP inbox (email, password). Pause, limits and other settings: update, or bulk-update for several (changes). Find inboxes by part of the email (a domain, hello@), sender display name or name: list with q, one call instead of paging the list.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through inboxes_read and changes through inboxes_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: bulk-update, inbox-order-intents-cancel, create, sending-plans-create, disconnect, inbox-order-intents-get, get, placement-seed-sharing-get, get-one-to-one-readiness, get-warmup, get-warmup-summary, list, list-labels, rename, update, placement-seed-sharing-update, update-warmup, inbox-order-intents-upsert, verify
bulk-update
Write. POST https://api.ken.so/v1/inboxes/bulk-update
Apply one field update to up to 1,000 inboxes. display_name is single-inbox only. paused pauses or resumes them all. profile_image_url sets one photo on up to 100 inboxes (inbox_photos flag). Requires Delivery edit access (owners, admins and editors by default).
POST /api/v1/inboxes/bulk-update. Public. Sends Ken-Version 1.1.
tag_ids adds tags: pass a non-empty list (null or [] is refused; clear tags
one inbox at a time with update).
paused (true or false) pauses or resumes sending from every listed inbox,
as the single-inbox update does: held sends go out after resume, warmup
and reply sync keep running. For these fields every id must be in the
workspace, else nothing changes.
forwarding_destination is set or cleared through the provider on each
inbox: an inbox the provider refused, or one it does not manage, is in
failed[{id, message}] and left out of updatedCount, while the rest still
update.
profile_image_url sets one photo, as on update, on up to 100 inboxes and
goes alone in changes. updatedCount counts the inboxes the provider accepted;
each other one, unknown ids included, is in failed[{id, message}] while
the rest still update. Split larger selections into calls of 100.
inbox-order-intents-cancel
Write. Early access: needs onboarding_v5 on for the workspace. DELETE https://api.ken.so/v1/inbox-order-intents
Cancel the workspace's Ken-managed inbox choice before its order runs.
DELETE /api/v1/inbox-order-intents. Internal route, behind onboarding_v5. Sends Ken-Version 1.1. Answers 204 also when there was nothing to cancel. conflict once the order is placed or running: cancel the domain order instead.
create
Write. POST https://api.ken.so/v1/inboxes
Body (json): email string, imapHost string, imapPort integer, ownerMemberId integer, password string, preset string, replyToInboxId integer, smtpHost string, smtpPort integer, smtpStartTls boolean, username string
Connect an SMTP inbox. Returns 201. Requires Delivery edit access (owners, admins and editors by default). smtp_start_tls defaults to true when omitted. With preset the hosts, ports and TLS come from the preset.
POST /api/v1/inboxes. Public. Sends Ken-Version 1.1. Without preset, smtp_host, smtp_port, imap_host and imap_port are required. preset is the slug of an SMTP preset listed by the sending_providers providers-list operation: it supplies the hosts, ports and TLS, and the four host and port fields are ignored. It needs the sending_providers feature on the workspace. A preset that takes no new inboxes is 400 validation_failed detail provider_retired.
sending-plans-create
Read. POST https://api.ken.so/v1/sending-capacity/plans
Body (json): domains array, goal object, inboxesPerDomain object, mix object, senders array
Plan the Kenso domains and inboxes for a sending goal: lines per provider, cost today, on connect and monthly in credits, credits short, new-payer limits, what checkout refuses now and when sending starts. Compute only: it buys nothing. Give people_per_month (with emails_per_person, default 3) or emails_per_day, not both. Quote usd as dollars; usdCents is US cents. With balance.creditsExempt true, quote only cost.registration. Internal.
POST /api/v1/sending-capacity/plans. Internal. Sends Ken-Version 1.1. Requires Delivery view. Returns 200.
Goal: people_per_month (1-1,000,000) x emails_per_person (1-20, default 3) / 21.7 weekdays, or emails_per_day
(1-100,000). The plan adds what the workspace's current inboxes do not cover (emailsPerDay.toAdd) at 25 emails a
day per Google or Microsoft inbox and 5 per Azure inbox.
mix: optional {"google": 0.67, "microsoft": 0.33, "azure": 0}, shares adding up to 1. Without it Kenso uses
Google and Microsoft 2:1 under 2,000 new emails a day, and 40% Azure, 40% Google, 20% Microsoft from 2,000 up.
inboxes_per_domain: optional {"google": 3, "microsoft": 3, "azure": 50} (Google and Microsoft 1-5, Azure 1-50).
Azure domains are always filled to their number.
Where SMTP inboxes are on for the workspace, mix and inboxes_per_domain also take "smtp" (1-20 inboxes a
domain, default 10), a domain's provider can be smtp (kind register only), and without a mix Kenso plans 50%
Google, 25% Microsoft, 25% SMTP. An SMTP inbox is planned at 10 emails a day and an SMTP domain costs 2,500
credits a month whatever its inbox count, so each is filled to its number. Elsewhere smtp is ignored, so a mix
that counts on its share does not add up to 1 and is refused, and an smtp domain is refused.
domains: optional names already picked, in order: [{"name": "tryacme.com", "provider": "google",
"kind": "register", "quote_usd_cents": 1040}]. provider is google, microsoft or azure (or smtp, register only,
where SMTP inboxes are on); kind is register (Kenso buys it) or import (the workspace owns it). quote_usd_cents is the registrar price from
domain_orders(operation="domain-orders-search"); without it each domain is estimated at $10.40 and
cost.dueTodayIsEstimate is true. With domains the plan returns cart, the exact body for
domain_orders(operation="domain-orders-create"), and importCart, the exact body for
domain_orders(operation="domain-imports-create").
senders: optional [{"first_name": "Jane", "last_name": "Doe", "nickname": "Janie"}] the mailbox usernames are
made from (first.last, nickname.last, first, firstlast, f.last, first.l, first.last2, never role names).
Without senders the workspace's delivery-default senders are used (saved, else the workspace owner; see
domain_setup(operation="delivery-defaults-get")). When no default sender can name every mailbox, cart and
importCart are left out and warnings has senders_required: pass senders.
The answer: emailsPerDay {target, existing, toAdd}; lines [{provider, domains, inboxes, inboxesPerDomain,
emailsPerDay}]; totals; cost {monthly, dueToday, dueOnConnect, registration, dueTodayIsEstimate} with each amount
{credits, usdCents, usd}; balance {paidCredits, shortfallCredits, packsToBuy, packsUsdCents, packsUsd,
creditsExempt}; limits {newPayer, maxCreditsPerCheckout, planDailyEnforced, plan, canBuy, buysFor, refusal};
capped (the new-payer limits cut the plan); timeline {startsSendingAt, fullVolumeAt}; cart; importCart; cartCost
(the same shape as cost, for what cart and importCart hold); unfilledSlots; warnings (capacity_sufficient,
new_payer_limit, azure_excluded_new_payer, quotes_estimated, senders_required, unfilled_slots).
cost.dueToday is what checkout charges for Kenso domains: their first year (cost.registration) and their inboxes'
first month. cost.dueOnConnect is the imported domains' inboxes' first month: nothing is charged at import, but the
import is refused unless the credits cover it, and it is charged when each domain is set up. cost.monthly is every
month. balance.shortfallCredits is cost.dueToday plus cost.dueOnConnect minus paidCredits: the credits to buy
before the order and the import. With domains it counts only the slots they fill (what the carts carry, cartCost),
and limits.refusal checks the same. balance.creditsExempt true means the workspace that pays is exempt from credit
charges: its inboxes are on its plan and it never needs credit packs, so quote no inbox month (cost.monthly,
cost.dueOnConnect) and only cost.registration, what checkout charges today. With domains, cartCost is what the
carts cost: quote it for the order. unfilled_slots in warnings (with unfilledSlots, the count) means the carts hold
fewer domains than the plan needs, so the order covers less than the goal: say so, or pick more names and plan
again.
limits.refusal is what checkout would refuse right now, as {code, message}: UPGRADE_REQUIRED,
NEW_PAYER_DOMAIN_LIMIT, NEW_PAYER_MAILBOX_LIMIT, DISPUTE_HOLD, INSUFFICIENT_CREDITS, FREE_CREDITS_NOT_ELIGIBLE,
PAID_PLAN_REQUIRED or FIRST_PAYMENT_PENDING. canBuy is true when nothing refuses or only a credit top-up is
needed. In a white-label child, limits.buysFor says whether the
order goes from the parent workspace (cart.targetWorkspaceId is the child) or only the agency can buy.
Money: usd and packsUsd are dollars as a decimal string ("416.00"): quote those as dollars. usdCents and
packsUsdCents are US cents (41600 is $416.00), never dollars: divide by 100. Credits are 50 to the dollar. Each
cart domain's price amount is in cents too, and is part of the order body: send it as it is, never quote it.
disconnect
Write. POST https://api.ken.so/v1/inboxes/{inboxId}/disconnect
Path: inboxId
Disconnect an inbox connection. Requires Delivery edit access (owners, admins and editors by default).
POST /api/v1/inboxes/{inboxId}/disconnect. Public. Sends Ken-Version 1.1.
inbox-order-intents-get
Read. Early access: needs onboarding_v5 on for the workspace. GET https://api.ken.so/v1/inbox-order-intents
Read the workspace's Ken-managed inbox choice and where its order stands. data.status is pending, ordered, skipped_insufficient_credits, skipped_new_payer_limit or failed.
GET /api/v1/inbox-order-intents. Internal route, behind onboarding_v5. Sends Ken-Version 1.1. not_found when the workspace never chose
Ken-managed inboxes (or cancelled the choice). Fields: id (ioi_), choice {domainCount, inboxesPerDomain,
provider, senderNames}, priceCredits and priceUsdCents (the quote when chosen; priceUsdCents is US cents, 2400 is
$24.00, so quote it / 100 as dollars), emailStartAt (when sending can
start, warmup included), status, domainOrderId once ordered, createdAt, updatedAt. skipped_insufficient_credits
means the workspace's paid or included credits did not cover it; free, bonus, connection and referral credits
never pay for inboxes.
get
Read. GET https://api.ken.so/v1/inboxes/{inboxId}
Path: inboxId
Return one inbox in the current workspace. A missing or cross-workspace id is not_found.
GET /api/v1/inboxes/{inboxId}. Public. Sends Ken-Version 1.1.
Requires Delivery view.
Carries role, ownerMemberId, isPrimary, isAccountsDefault, connectionApp,
usedBy, warmup, sendBlock, sendState, healthScore, tenantHost (staff callers only) and
sendingProvider (the workspace's own connected account only) as on
inboxes(operation="list").
health (get only, never on list) is the inbox's send day and what holds
it back. It appears only where agent sending is on for the workspace (the
agent_send feature flag); omitted otherwise and when it cannot be read:
- sentToday: sends the provider accepted today, campaign and 1:1 alike.
reservedToday: slots held by sends in flight.
- limit: today's effective cap (the daily limit after the ramp).
remaining = limit - sentToday - reservedToday, never below 0.
- dayEndsAt (UTC): when the day resets, in the zone of the inbox's
campaigns (New York when none names one).
- rampDay (1 on the first sending day, kept once the ramp completes) and
rampComplete (the ramp no longer lowers the cap). When the cap is not
read from send history (kill switch or a failed read), rampDay and
bounceRate7d are omitted and rampComplete is false.
- warmupReadiness: readiness.outcome as inboxes(operation="get-warmup")
serves it: ready, too_young, unconfirmed, bypassed, provider_stale, or
unavailable (no fresh provider evidence, or no verdict for the inbox).
- blocks: [{ kind, reason, until }], empty when nothing holds the inbox.
kind is paused (a member paused it; no until), send_blocked (Ken
blocked it, for example after a failed placement test) or
sending_paused (a pause over the inbox, its domain or the workspace
that holds sends now: an operator's pause, which stops campaign sends
and new agent threads from the inbox, or any pause once capacity
limits are enforced). Until a block ends, do not
start agent threads from the inbox. reason is why, as recorded
(usually a machine code such as mailbox_hard_bounce_rate), omitted
when none was; until is UTC.
- notes: [{ kind, reason, until }], empty when there is nothing to show.
A note holds no send. kind sending_pause_observed: an automatic pause
(any pause Kenso opened itself, for example after a placement test,
bounces, complaints or a domain breach, and not an operator's) covers
the inbox, its domain or the workspace, but while capacity limits are
not enforced it holds nothing, so the inbox keeps sending (campaigns
and agent threads). Do not skip the inbox because of a note.
- bounceRate7d: hard bounces over accepted sends in the last 7 days,
0 to 1; omitted with no accepted sends.
placement-seed-sharing-get
Read. GET https://api.ken.so/v1/placement-seed-sharing
Read whether Kenso may use the workspace's outreach inboxes as placement-test seeds for other workspaces. Internal. Requires Delivery view.
GET /api/v1/placement-seed-sharing. Sends Ken-Version 1.1. Requires Delivery view. No feature flag.
Returns {"data": {"shared": bool, "managedByKenso": bool}}. shared is true when Kenso may use the workspace's
outreach inboxes (never its primary inboxes) as seeds in other workspaces' placement tests. managedByKenso is
true when Kenso staff keep the workspace out of the seed network; the workspace cannot turn sharing back on then.
Change it with inboxes(operation="placement-seed-sharing-update", shared=...).
get-one-to-one-readiness
Read. GET https://api.ken.so/v1/inboxes/{inboxId}/one-to-one-readiness
Path: inboxId
Check whether an inbox can send a 1:1 email touch, without sending. canSend false comes with a reason. A missing or cross-workspace id is not_found.
GET /api/v1/inboxes/{inboxId}/one-to-one-readiness. Public. Sends Ken-Version 1.1.
Requires Delivery view. Never mutates and never sends (DEV-9622).
It answers by the rule an approved Accounts touch or a workflow send.email
step is held to when it names this inbox as its sender, so check it before
naming an inbox in an account's Sends from or a send.email fromInbox.
Returns data:
inboxId, email.
senderKind: member_mailbox (a member's own connected mailbox),
shared_inbox (a shared connected inbox on a cold sending domain) or
sending_identity (an identity on a sending provider connection).
canSend (bool).
reason (only when canSend is false): receive_only (a replies or retired
inbox), not_connected, replies_not_read (a sending identity whose
replies would not reach Kenso), not_cold_sender (a shared inbox or
identity on one of the workspace's own domains), not_primary (a
member's mailbox that is not their primary inbox) or paused (a member
paused the inbox; the touch waits until it is resumed). Tolerate
values not listed here.
message (only when canSend is false): what to fix, in words.
signatureWarning (DEV-10908, omitted when there is nothing to say):
brand_domain when a member's mailbox has a saved signature the brand
check refuses for it (an image or a tracking link on a Kenso domain the
mailbox's own domain does not cover). The 1:1 email still goes, without
the signature. A plain link to a Kenso site is no warning. Tolerate
values not listed here.
signatureMessage (with signatureWarning): what to remove, in words.
get-warmup
Read. GET https://api.ken.so/v1/inboxes/{inboxId}/warmup
Path: inboxId
Return warmup state for one inbox. status is not_started, pending, in_progress, paused, completed, maintenance, failed, or degraded.
GET /api/v1/inboxes/{inboxId}/warmup. Public. Sends Ken-Version 1.1.
Requires Delivery view.
status and enabled come from the live warmup provider's own status
(DEV-1456), not the old inbox warmup column. When two providers track
the inbox, it reads the one pause and resume act on. What to do:
- in_progress (enabled true): already warming and paid for. Do not call
enable or buy warmup.
- pending (enabled true): warmup was bought and is waiting to activate.
Leave it alone. Do not call enable or buy again.
- paused (enabled false): warmup is paused. Resume it with
inboxes(operation="update-warmup", enabled=True) (or
admin_warmup(operation="resume")). Do not call enable.
- failed (enabled false): the provider cannot warm it (connection or
enrollment failure, or billing past due), or it is an Azure inbox with
no vendor warmup subscription (Kenso cannot enroll Azure). Escalate to
staff. Enabling again does not fix it.
- not_started: only this status, with no provider tracking the inbox,
is a candidate for admin_warmup(operation="enable").
Status comes from the old inbox warmup column only when no provider
tracks the inbox.
readiness (omitted when it cannot be read) is the cold-send warmup gate's
own verdict from provider warmup snapshots - the one readiness answer
(DEV-1454). outcome is ready, bypassed, unconfirmed (no live-provider
warmup sends recently), too_young (warming fewer than minimumWarmupDays),
provider_stale, or unavailable (no fresh provider evidence; the gate holds
nothing). isHeld says the gate keeps cold sends off the inbox while
isEnforced is true. Also firstWarmupSendDate, lastWarmupSendDate
(YYYY-MM-DD), daysInWarmup, minimumWarmupDays, hasMinWeekOverride,
hasOutreachBypass. startedAt falls back to the first provider-reported
warmup send day when the inbox row has none.
enrollmentFailure (staff callers only; omitted for everyone else and when
the last attempt did not fail) is why the last pre-warmup enrollment of
this mailbox failed (DEV-1457). It often explains a failed status.
Fields: provider (a staff code for the warmup source), reason, status (for example enroll_failed),
failureCount (consecutive failed attempts), retryAt (next automatic
attempt) and isStopped (true when there is no retryAt).
- retryAt set: a scheduled enrollment job retries it at that time. No
action.
- isStopped: the attempt cap was reached. The scheduled job re-admits it
on its own only after the mailbox's connection carries a new stored
credential. inboxes(operation='verify') re-checks without changing
the credential, and admin_warmup(operation='admin-warmup-backfill')
does not clear it. Do not call enable: the status is failed, and enable
only repeats the same attempt, which fails again with the same
credential. Escalate to staff with the reason.
Reasons: imap_credentials and missing_password mean the mailbox password
is wrong or missing. The others (for example provider_5xx,
provider_rejected, transport, capacity, credential_lookup_failed,
missing_email, status_unconfirmed, account-health reasons) are provider,
lookup or account faults. Most retry on their own until the attempt cap
(capacity never stops); some account-health reasons stop at once.
get-warmup-summary
Read. GET https://api.ken.so/v1/inboxes/warmup-summary
Query: from date-time, to date-time
Return warmup sends per day and placement test results for the workspace, per domain and per inbox. Internal. Read-only. Rates are fractions from 0 to 1. Default window: the 30 days ending today (UTC).
GET /api/v1/inboxes/warmup-summary. Internal. Sends Ken-Version 1.1. client_id is sent as X-Ken-Workspace-Id. Requires Delivery view. from_date and to_date (YYYY-MM-DD, UTC days, inclusive) are sent as from and to: both or neither, at most 31 days. Without them the window is the 30 days ending today. Top level: from, to, inboxCount, domainCount, sentCount (warmup emails the inboxes reported sending) and daily (one row per day of the window: date, sentCount, inboxCount = inboxes that reported a send count that day; a day nobody reported is 0 and 0). domains (ordered by name): domainId (omitted when the domain is not managed in Kenso), domainName, inboxCount, sentCount, daily and placementTests (tests completed in the window on the domain or its inboxes, newest first). inboxes (ordered by email): inboxId, email, domainId, domainName, sentCount, reportedDayCount, lastSentDate (omitted with no sends), daily and latestPlacementTest (omitted when none). A placement result: placementTestId, type (weekly, on_demand or pre_launch), completedAt, inboxRate and spamRate (fractions, omitted when unknown). Lists every inbox warming up in the workspace and every inbox that reported warmup sends in the window. There is no warmup score: judge warmup on sends and placement results. One inbox's warmup state and send-gate verdict: inboxes(operation="get-warmup", ...).
list
Read. GET https://api.ken.so/v1/inboxes
Query: availableForCampaignId integer, cursor string, isPrimary boolean, limit integer, role string, status string
List inboxes in the current workspace, or find some by q. q: part of the email (a domain, hello@), sender display name or name, ignoring case; one call, no paging. status is lowercase snake_case. is_primary true: members' primary inboxes only. role: sending, replies, retired.
Requires Delivery view. role replies is the workspace's replies@ inbox.
q: the tool reads up to 10 pages of 200 (status, is_primary and role
apply first) and returns the matches as id, email, firstName, lastName,
displayName, status, role, domainId, dailySendLimit, pausedAt, isPrimary,
sendBlock, sendState and healthScore (get returns one whole). scanned counts the
rows read; pagination.nextCursor with the same q continues.
GET /api/v1/inboxes. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.
Each inbox carries ownerMemberId (the member whose own mailbox it is;
omitted for a shared campaign inbox), isPrimary (owned by a member and on
the workspace's primary domain), isAccountsDefault (true on the one inbox
per member that their accounts' one-to-one email goes out from when
nothing names another: their lowest-id primary inbox that is connected and
can send; a workflow send step left on Automatic From sends from the
account's Sends from inbox, else this inbox of the account's owner) and
connectionApp (ken_mail or ken_workspace; omitted for SMTP inboxes).
role is sending (a campaign inbox), replies: the workspace's shared
replies@ inbox that campaign replies go to, or retired: a campaign inbox
staff retired to receive-only. A replies or retired inbox only
receives: it never joins a campaign pool or warmup, and Kenso keeps
reading its mail. A retired inbox carries captureUntil (UTC), the end
of its reply capture window; nothing happens automatically then. It
also carries renewalEndsWindowEarly: true when its domain's
registration expires before captureUntil with auto-renew off (the
domain can lapse and a new owner would get the replies), false when it
renews, runs past captureUntil or captureUntil has passed; omitted when
the domain or its expiry is unknown.
usedBy is { campaigns: [{ id, name, status }], accounts }: the live
campaigns (scheduled, launching or sending) the inbox is assigned to, and
accounts true when it is a member's primary inbox. Omitted when it cannot
be read.
warmup is { daysLeft }: days until the inbox reaches the warmup gate's
minimum age, counted from the first provider warmup send. 0 means old
enough or waived by an override. Omitted when no provider reported
warmup sends, except that an outreach bypass always reports 0.
sendBlock is { reason, until } while an automatic or manual send block
is in force; omitted otherwise. reason is a machine code such as
mailbox_hard_bounce_rate (omitted when none was recorded), until is UTC.
sendState (DEV-9305) is the one answer to "can this inbox send now": ready,
or the first reason it cannot, in this order: gone (deleted, replaced,
turned off or banned), receive_only (replies or retired role),
needs_reconnect (sign-in failed or connection gone), paused (a member or
the provider paused it), warming (status warmup), blocked_until (sendBlock
in force) or not_sendable (any other reason, such as unfinished setup or a
daily limit of 0). ready on a shared inbox means it is in the pool Kenso
sends campaign email from, the pool launch counts; on a member's own inbox
it means its owner can send from it. The warmup age gate and today's cap
are separate (warmup.daysLeft, health). Read sendState instead of combining
status, connection, pausedAt and sendBlock yourself. Omitted when it could
not be worked out.
oneToOneReadiness (DEV-9626) is the get-one-to-one-readiness answer for the
inbox: { inboxId, email, senderKind, canSend, reason, message,
signatureWarning, signatureMessage }, whether an
approved 1:1 email that names it (an account's Sends from, a workflow
send.email fromInbox) goes out now, and if not why and what fixes it.
sendState is about campaign email; this is about 1:1 email. Omitted when it
could not be worked out, and not in the q match rows.
healthScore is the Ken Health Score, 0-100, from the inbox's latest
health snapshot; omitted when no health has been reported for the
inbox.
tenantHost (staff callers only; omitted for everyone else and until it
is resolved) is the Microsoft 365 tenant <x>.onmicrosoft.com of a
Microsoft or Azure inbox, read hourly from its domain's DKIM record
(DEV-2309). Inboxes with the same tenantHost share one tenant.
sendingProvider is the slug of the workspace's own connected provider
account the inbox sends through. It is omitted on every other inbox:
an SMTP inbox Kenso runs reads provider custom_smtp like any SMTP
inbox (staff callers get the slug on every provider inbox).
status: active, warmup, disconnected, paused, banned, connection_error,
deleted, inactive, replaced, pending_provisioning.
is_primary is sent as isPrimary and filters on that field before paging.
role filters on that field before paging and combines with status and
is_primary.
list-labels
Read. GET https://api.ken.so/v1/inboxes/{inboxId}/labels
Path: inboxId
List a connected Gmail inbox's labels, for a Mailbox label workflow source. Only the inbox's owner can read them. Not for the Client role.
GET /api/v1/inboxes/{inboxId}/labels. Internal. Sends Ken-Version 1.1.
Requires workflows view; then only the member whose mailbox the inbox is,
Kenso staff included (forbidden mailbox_not_owned for anyone else).
Items: id (Gmail's label id, e.g. Label_11 or INBOX), name (as Gmail shows
it; a nested label carries its parents, e.g. Clients/Acme) and type (user
for the owner's own labels, system for Gmail's; absent when Gmail sends
none). The owner's labels come first, then Gmail's, each sorted by name.
One page holds every label. Pass a user label's name or id as with.label
of a trigger.mailbox_label@1 source; publish refuses a system label.
Reads no message. Costs no Kenso credits.
not_found when the inbox is not connected to the workspace, or while the
mailbox_label_trigger feature is off for it. conflict inbox_not_supported
when the inbox is not a Google inbox connected in Kenso; conflict
mailbox_not_connected when it is not connected or Gmail refused Kenso's
access (reconnect it in Settings). gmail_unavailable (503) when Gmail does
not answer: try again.
rename
Write. POST https://api.ken.so/v1/inboxes/{inboxId}/rename
Path: inboxId
Body (json): localPart string
Change the username of an inbox Kenso bought, the part of its address before the @. The domain stays. Requires Delivery edit access (owners, admins and editors by default).
POST /api/v1/inboxes/{inboxId}/rename. Public. Sends Ken-Version 1.1.
local_part is the new username only (jane.doe, not jane.doe@acme.com). The mail
provider renames the mailbox first; Kenso then changes the inbox's email and, when
the inbox has a sending connection, reconnects it. Returns {inbox, reconnected,
warnings}: warnings lists follow-up steps that did not finish (the rename
succeeded). Renaming to the current username changes nothing. Only inboxes Kenso
bought: any other inbox is 409 invalid_state. 409 conflict (address_in_use) when
another live inbox has the new address. 400 validation_failed on localPart
(invalid, or provider_rejected with the provider's message). 503
service_unavailable: the provider did not answer or refused Kenso's request, the
name was not changed, retry later. An inbox of another workspace is 404
not_found. Display, first and last names are inboxes(operation="update", ...).
update
Write. PATCH https://api.ken.so/v1/inboxes/{inboxId}
Path: inboxId
Update an inbox. Absent fields stay unchanged. Null clears text fields and forwarding. paused pauses or resumes sending. profile_image_url sets the sender photo (inbox_photos flag). Requires Delivery edit access (owners, admins and editors by default).
PATCH /api/v1/inboxes/{inboxId}. Public. Sends Ken-Version 1.1.
Fields: first_name, last_name, display_name, signature, daily_send_limit,
forwarding_destination, tag_ids, track_opens, paused, profile_image_url.
signature is the outbound signature campaign emails from this inbox carry:
plain text, or HTML reduced on save to bold, italic, links (http, https,
mailto) and line breaks. A link to a Kenso main domain is validation_failed
on the signature field.
profile_image_url (https, not null) is fetched once (image-from-URL
quota) and pushed to the mailbox; kept only if the provider accepts it,
else validation_failed with the reason (service_unavailable when the
provider fails: retry). Only an inbox whose profilePhotoSupport is google or
microsoft takes one, and it needs the inbox_photos flag (else detail code
feature_disabled); a refused photo changes nothing. A microsoft photo is
applied later: profilePhotoStatus reads pending until the daily mailbox
sync sees it applied, and failed (reason in profilePhotoError) when it was
not, after which the inbox shows no photo.
track_opens (boolean) is the owner's Track opens option on a member's own mailbox
(ownerMemberId set), off by default. Open tracking is unavailable: Kenso adds no
open-tracking pixel to replies or 1:1 Accounts email, so track_opens=True is
validation_failed with details code open_tracking_unavailable and nothing is saved;
False is accepted. Asked to turn it on, decline and say opens are not tracked. On a
shared campaign inbox it is validation_failed. Only the mailbox's owner can change
it; anyone else gets forbidden.
paused (true or false): true stops campaign steps, triggers and approved
1:1 Accounts email from this inbox. They are held, not failed or skipped,
and go out after paused false. Warmup, reply sync and replies a person
sends keep running. New campaigns do not pick a paused inbox; existing
campaign assignments stay. Pausing a paused inbox keeps its first
pausedAt. The inbox returns pausedAt (UTC) while paused; the field is
absent when it is not paused.
placement-seed-sharing-update
Write. PATCH https://api.ken.so/v1/placement-seed-sharing
Body (json): shared boolean
Share the workspace's outreach inboxes as placement-test seeds, or opt out of the seed network. Internal. Requires Delivery edit. Ask the user first.
PATCH /api/v1/placement-seed-sharing. Sends Ken-Version 1.1. Requires Delivery edit. No feature flag.
shared (required, true or false): false opts the workspace out; the next hourly seed sweep removes its seeds.
true lifts the workspace's own opt-out; the next sweep adds its outreach inboxes that qualify. When Kenso staff
keep the workspace out (managedByKenso), true answers 409 invalid_state and the user has to contact support.
Get the user's yes before changing it.
Returns {"data": {"shared": bool, "managedByKenso": bool}}, the state after the change.
update-warmup
Write. PATCH https://api.ken.so/v1/inboxes/{inboxId}/warmup
Path: inboxId
Pause or resume warmup for one inbox. enabled true resumes. enabled false pauses. Requires Delivery edit access (owners, admins and editors by default).
PATCH /api/v1/inboxes/{inboxId}/warmup. Public. Sends Ken-Version 1.1.
It never enrolls an inbox that has no warmup subscription (status
not_started). Staff enroll with admin_warmup operation enable (DEV-1490).
inbox-order-intents-upsert
Write. Early access: needs onboarding_v5 on for the workspace. PUT https://api.ken.so/v1/inbox-order-intents
Body (json): domainCount integer, inboxesPerDomain integer, provider string, senderNames array
Choose Ken-managed inboxes for the workspace: priced now, ordered later from credits. Buys nothing now. Full docs: describe_tools(['api_inbox_order_intents_upsert'])
PUT /api/v1/inbox-order-intents. Internal route, behind onboarding_v5. Sends Ken-Version 1.1. domain_count 1 to 10, inboxes_per_domain 1 to 5, provider google or microsoft, sender_names 1 to 5 "First Last" names the mailboxes are created under. Answers the intent with its price in credits and dollars and the date sending can start. A pending choice is replaced in place; a skipped or failed one is replaced by a new pending choice; conflict once the order is placed or running. The order runs hourly once the workspace is on Platform, Active, with this month's included credits. Until 14 days after its first payment a workspace holds at most 3 Kenso domains and 10 Kenso inboxes, counting what it holds already (the new-payer limits): a larger choice is validation_failed with details[0].code new_payer_limit, and the message names both limits.
verify
Write. POST https://api.ken.so/v1/inboxes/{inboxId}/verify
Path: inboxId
Re-check an inbox connection. Requires Delivery edit access (owners, admins and editors by default).
POST /api/v1/inboxes/{inboxId}/verify. Public. Sends Ken-Version 1.1.