Kenso MCP tools

Domain Setup domain_setup

Domain and inbox setup. move_workspace moves domains between workspaces: source_client_id, target_client_id, domain_ids (a list, never domain_id), dry_run. placement-tests-availability says whether a Kenso placement test can run and how many are left; delivery-settings-get and -update hold the placement auto-pause; delivery-defaults-get and -update hold the redirect, senders, reply forwarding and signature new domains and mailboxes start from.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through domain_setup_read and changes through domain_setup_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: placement-tests-availability, clear-reply-to, inbox-imports-create, inbox-stock-create-claim, inboxes-create-connect-session, inboxes-delete, delivery-defaults-get, delivery-settings-get, inbox-stock-get, setup-reply-to, delivery-defaults-update, delivery-settings-update

placement-tests-availability

Read. GET https://api.ken.so/v1/placement-tests/availability

Whether a Kenso placement test can run in this workspace now, and how many are left. Internal. Read it before placement-tests-create.

GET /api/v1/placement-tests/availability. Internal. Sends Ken-Version 1.1. Requires Delivery view.
Listed to workspace admins, and to every member with Delivery view where placement_tests_public or
placement_native is on. Always 200.

Returns {"data": {enabled, planAllowed, providers, seedsPerArm, control, testsLeftToday,
testsLeftThisMonth, testsPerDay, testsPerMonth, senderTestsPerDay}}:
- enabled: tests run on Kenso's seed network here. false means the workspace keeps the older
  engine (rules in the placement-tests-create docs), or Kenso tests are paused (a create answers 503).
- planAllowed: the workspace's plan can start Kenso tests (paid plans only; while false a create is 402).
- providers: [{provider, active}] for google_workspace then microsoft_365. Google Workspace only at
  launch; Microsoft 365 joins when the network has enough seeds.
- seedsPerArm: seed inboxes each message goes to across the active providers (10 per provider).
- control: {available, reason}: whether a test can add the copy check (control=True), and why not.
- testsLeftToday, testsLeftThisMonth, testsPerDay, testsPerMonth: what the workspace's budget allows
  and leaves (omitted when unknown; staff and Kenso workspaces have no month counter). Paid plans get
  10 a day and 60 in 30 days, a trialing workspace 2 a day and 8 in 30 days. Retests and weekly tests
  do not count; only tests people start do.
- senderTestsPerDay: tests one sending inbox can be part of in 24 hours (3).

clear-reply-to

Write. DELETE https://api.ken.so/v1/workspaces/{workspaceId}/reply-to

Path: workspaceId

Clear the workspace Reply-To default. The replies@ inbox stays. Empty success means the default was cleared.

DELETE /api/v1/workspaces/{workspaceId}/reply-to with Ken-Version 1.1.
Internal exposure. The backend requires the workspace settings permission and
returns 204 with an empty body. Off (not_found) without the reply_to_default flag.
The same as workspace(operation="update", workspace_id=..., reply_to=""): campaigns
without their own Reply-To send without one again. The replies@ inbox is not deleted.

inbox-imports-create

Write. POST https://api.ken.so/v1/inbox-imports

Body (json): rows array

Connect up to 500 SMTP/IMAP inboxes in the background and return the import job. Each row: email, password, smtp_host, smtp_port, imap_host, imap_port. Poll jobs get with job_type inbox_import.

POST /api/v1/inbox-imports. Public. Sends Ken-Version 1.1. The backend
requires delivery edit (workspace Admin or Editor), the same as inboxes
create, and the inbox_csv_import feature flag, which is off by default:
while it is off for the caller the call fails with 404 not_found (the route
answers as if it did not exist), and 403 forbidden without delivery edit.
Returns 202 and an inbox_import job.

rows is a list of 1 to 500 objects, snake_case or camelCase keys:
email, password, smtp_host, smtp_port, imap_host, imap_port (required);
username (defaults to email), smtp_start_tls (defaults to true).
first_name and last_name (the mailbox's sender names, 1 to 40 characters
each, blank means none) and daily_send_limit (a whole number of 1 or more)
are optional: Kenso sets them on the mailbox once it connects, the way
inboxes update does. A limit above the mailbox's provider ceiling (50 for
Google and Microsoft, 30 for custom SMTP and Azure) is stored at the ceiling
and the row carries the warning daily_limit_clamped. A row with a name over
40 characters or a limit that is not a whole number of 1 or more fails on its
own (validation_failed) before any login, with details[].field naming the
column. If the mailbox connects but these cannot be saved, the row is still
connected with the warning settings_not_applied: use inboxes update.

Values are checked per row before the call: text fields must be strings,
smtp_port, imap_port and daily_send_limit whole numbers (587 or "587"),
smtp_start_tls true or false, and every key known. A row that fails a check
is not sent: it goes as an empty row so the other rows keep their index,
the job reports it failed (validation_failed, "Row is empty."), and this
response adds rowErrors: [{index, message}] naming the field. When no row
passes, nothing is sent and the call fails with the first errors.

Each row runs the same connect as inboxes create, four at a time: the
consumer-host guard, the white-label mailbox cap and a live SMTP AUTH and
IMAP LOGIN probe. A row with a missing field fails, and so does a row that
reuses an earlier row's username on the same smtp_host or imap_host with
another password. An
email an earlier row has is skipped (duplicate_in_file). An email the workspace already has is
skipped (already_exists), unless that inbox is a disconnected SMTP inbox,
which the row reconnects. A row logs in before its inbox is created, so a
failed probe creates no inbox. An email another inbox in Kenso holds fails
(email_in_use), which is only reported after a successful login. After 5 refused logins
on one host, or 3 timeouts or connection failures in a row, the import stops
probing that host: its remaining rows fail with host_failure_limit and are
not tried.

Both are checked again before each row. Once the flag is off, or the caller
is no longer a member with delivery edit, the import stops: every row it had
not started is skipped with errorCode feature_disabled or forbidden, and the
job fails with that error.code. A row whose permission check could not run
fails with service_unavailable without a login, and the import goes on.

Poll with jobs get, job_id from this response and job_type inbox_import.
data.status is queued, running, succeeded (every row processed) or failed:
error.code feature_disabled or forbidden (stopped as above), or interrupted
(no progress for 10 minutes. A row without a result may still have
connected: send the rows again, and those that did connect are skipped as
already_exists). data.progress has completed and total. data.inboxImport
has connectedCount, failedCount, skippedCount, startedAt, updatedAt,
completedAt and rows: index (zero-based position in rows), email, status
(connected, failed or skipped), inboxId, errorCode, message, and on a
connected row that set them firstName, lastName and dailySendLimit (as
stored), warnings, and on a failed column check details. rows is empty
until the first row has a result, and jobs get leaves it out for a caller
without Delivery view. Passwords are never returned. Envelope: success plus data.

A workspace can have 2 imports queued or running at once. A third gets
409 conflict: wait for one to finish, then send it again. Each row that
passes the checks above counts toward 1,000 rows per workspace per rolling
day; an import over that gets 429 quota_exceeded with Retry-After and
nothing runs. Send fewer rows, or wait.

inbox-stock-create-claim

Write. POST https://api.ken.so/v1/inbox-stock/claims

Body (json): mailboxType string, mailboxes array

Claim a warmed Kenso inbox: one pre-warmed domain with 1 to 5 mailboxes. Spends credits. Internal. mailbox_type is gmail or outlook. Each mailbox is { username, first_name, last_name }. idempotency_key is required: reuse it to retry the same claim.

POST /api/v1/inbox-stock/claims. Internal. Sends Ken-Version 1.1. Returns 201 with
{ domainId, domainName, inboxes: [InboxModel] }.
Price: 200 credits a month per inbox plus a 300-credit pre-warmed fee per inbox.
Needs a paid plan. Requires Delivery edit and the `billing` permission (admins by default).
A claim takes up to a few minutes. It claims one domain per call, so every mailbox
in the call lands on the same domain.
The mailboxes read warmup until Kenso activates them, then active.
Refusals:
- 402 plan_limit_reached, refusal UPGRADE_REQUIRED: the Free plan cannot claim.
- 402 plan_limit_reached, refusal INSUFFICIENT_CREDITS: the workspace cannot pay the first
  month and the pre-warmed fee. Add credits, then call again.
- 402 plan_limit_reached (new-payer limit): the account holds as many Kenso domains or
  mailboxes as a new payer may. Do not retry; wait for more paid history or contact support.
- 400 validation_failed (capacity): the claim would pass the workspace's daily send capacity
  or the white-label cap its parent workspace set. Do not retry; free capacity or ask the
  parent workspace.
- 403 forbidden: a paid plan is required (for example, the plan was canceled).
- 409 invalid_state with detail stock_empty: no warmed stock is free. Read inbox-stock-get first.
- 503 service_unavailable: the claim did not finish. Retry with the same idempotency_key:
  it returns the claimed domain and its inboxes if one was bought, and buys nothing twice.
- 500 with detail claim_incomplete: the claim stopped after the buy may have gone out. Do not
  retry: a retry buys a second domain. List the workspace's domains, then contact support.
idempotency_key (1 to 200 characters) is required. After a timeout or any 5xx, retry with the
same key: the claimed domain and its inboxes come back with 201 and nothing is bought twice.
The same key with another request is 409 idempotency_key_reused. 409 claim_in_progress: this
key's claim, or another claim of the workspace, is still running, or staff are checking a
recent claim whose outcome is unknown; retry with the same key after nextAllowedAt. 500 with detail claim_incomplete under the same key: that claim stopped
after its buy may have gone out; do not retry under any key: list the workspace's domains,
then contact support.
The claim is off on Kenso until staff turn it on, and answers 404 while off.
404 while agent_send is off for the workspace.

inboxes-create-connect-session

Write. POST https://api.ken.so/v1/inboxes/connect-sessions

Body (json): provider string, purpose string, returnTo string

Start a Gmail or Microsoft mailbox connect. Returns 201. provider is google or microsoft. purpose is primary (the member's own work mailbox) or campaign (a Kenso Mail sending inbox). Requires Delivery edit, or approve_own_sends for a client seat's own primary inbox.

POST /api/v1/inboxes/connect-sessions. Public. Sends Ken-Version 1.1.
Needs Delivery edit (the Admin and Editor templates have it), or
approve_own_sends (the Client template) for the caller's own primary
inbox. Nothing is stored until the provider calls back.
Returns provider, purpose, appName, clientId, authorizationUrl, adminUrl,
adminConsentUrl (Microsoft only) and expiresAt.
- authorizationUrl is for a human to open in a browser and sign in to the
  mailbox. Open it before expiresAt.
- The connect finishes in the Kenso dashboard, not at the provider: after
  consent the browser lands on the dashboard, and the member who created
  the session (the API key's owner) must be signed in there, in this
  workspace. Anyone else sees "connect link expired or was started by
  someone else" and nothing is connected, so a key that names no member
  cannot finish a connect.
- purpose primary connects the member's own work mailbox through the
  "Kenso Workspace" app. It needs the accounts feature (not_found
  without it). The mailbox is recorded as owned by the member who created
  the session, so that member must open authorizationUrl themselves and
  sign in to their own mailbox. Do not hand the URL to anyone else. The
  mailbox is never used by campaigns or warmup. Check ownerMemberId,
  isPrimary and connectionApp on inboxes(operation="list") afterwards.
- purpose campaign is the classic Kenso Mail sending-inbox connect.
- A client seat may connect only its own primary inbox: purpose campaign
  is 403 own_inbox_only. When its login email is not on the workspace's
  email domain (or the workspace has none) it is 409 invalid_state with
  email_domain_mismatch, because that mailbox would never be its primary
  inbox. Pass the message on as written. It asks Kenso to set the
  workspace's email domain only when the workspace has none; an existing
  domain is never changed for one member.
- adminUrl and adminConsentUrl let a Google Workspace or Entra admin trust
  the app first when the workspace blocks unapproved apps.
- The API also takes returnTo, the dashboard page the browser lands on
  after the connect. It is for the Kenso dashboard; this tool does not send
  it, so the connect returns to the app's default page.

inboxes-delete

Write. DELETE https://api.ken.so/v1/inboxes/{inboxId}

Path: inboxId

Delete a Kenso inbox. Requires a workspace admin. Cancels its mailbox at the provider and stops its monthly charge.

DELETE /api/v1/inboxes/{inboxId}. Admin. Sends Ken-Version 1.1. Returns 204.
Needs the Billing feature and the agent_send flag (404 while it is off).
A workspace admin, their API key or agent can delete an inbox.
A member's own mailbox is refused (403) unless a person deletes it in the dashboard.
Cancels the mailbox at the provider first. When that cancel fails it is 503: nothing was deleted,
so retry. When no live inbox is left on a Kenso-purchased domain, it turns the domain's auto-renew off.
Adding an inbox to that domain again turns auto-renew back on while the workspace pays.

delivery-defaults-get

Read. GET https://api.ken.so/v1/delivery-defaults

Read the workspace's delivery defaults: redirect, website mode, senders, photo, reply forwarding, signature. Internal. Requires Delivery view. Every new domain setup and mailbox starts from these.

GET /api/v1/delivery-defaults. Sends Ken-Version 1.1. Requires Delivery view. Not behind a flag.

Returns {"data": {redirectUrl, websiteMode, senders, profilePhotoUrl, replyForwardingEmail, signatureHtml}},
each {"value": ..., "source": "stored" | "derived" | "none"}. stored: the workspace saved it. derived: nothing
saved, but Kenso knows one (redirectUrl from the workspace website with https://, a Kenso site is
https://getken.ai; senders from the workspace owner's first and last name). none: value is null.
websiteMode is "redirect" (the domain's root redirects to redirectUrl) or "page" (Kenso builds a page).
senders is a list of {firstName, lastName, nickname}. Change them with
domain_setup(operation="delivery-defaults-update", ...).

delivery-settings-get

Read. GET https://api.ken.so/v1/delivery-settings

Read the workspace's delivery settings: whether a failing Kenso placement test pauses the domain. Public. Requires Delivery view. 404 while placement_native is off for the workspace.

GET /api/v1/delivery-settings. Sends Ken-Version 1.1. Requires Delivery view.
Dark behind the placement_native flag: while it is off the route answers 404 not_found.

Returns {"data": {"placementAutoPause": bool}}. placementAutoPause on means a completed Kenso domain,
weekly, retest or campaign placement test that finds the domain's mail in spam pauses sending from that
domain (send block reason domain_placement_spam). An inbox-scope test and a copy verdict never pause.
On by default; false once the workspace turns it off. Change it with
domain_setup(operation="delivery-settings-update", placement_auto_pause=...).

inbox-stock-get

Read. GET https://api.ken.so/v1/inbox-stock

How many warmed Kenso domains a claim can take now. Internal. Needs the agent_send flag. Returns claimableDomains and a count per mailbox type.

GET /api/v1/inbox-stock. Internal. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Delivery view.
Returns { claimableDomains, claimableByMailboxType: { gmail, outlook } }.
A domain counts under every mailbox type it accepts, so the types can add up to more than claimableDomains.
404 while agent_send is off for the workspace.

setup-reply-to

Write. POST https://api.ken.so/v1/workspaces/{workspaceId}/reply-to/setup

Path: workspaceId

Body (json): domainId integer

SPENDS CREDITS: buys the workspace's replies@ inbox and makes it the Reply-To default. One Kenso inbox, 200 credits a month (first month now). Confirm the cost with the user before calling. Off (not_found) without the reply_to_default flag. Needs a workspace admin.

POST /api/v1/workspaces/{workspaceId}/reply-to/setup with Ken-Version 1.1.
Internal exposure. The backend requires the workspace settings and Billing permissions.
Buys replies@ on an outbound domain, then sets it as the workspace Reply-To, so every
campaign reply lands in one mailbox Kenso reads. The inbox only receives: it never joins
a campaign or warmup.
domain_id picks the domain; omitted, Kenso picks the active Kenso-managed outbound domain
with the most active inboxes, and when the mailbox provider refuses it (detail code
provider_refused, as on a full domain) the next, up to three. None is validation_failed
with detail code
no_outbound_domain (buy a domain first); another workspace's domain is not_found; a Kenso
domain is never used (given as domain_id: validation_failed, detail code brand_domain).
When replies@ is taken, reply@ then hello@ is bought.
200: data has inboxId, email, domainId, status "set", replyTo and alreadySet. Safe to
call again: a replies@ default Kenso already reads returns alreadySet true, and the
workspace's replies@ inbox is reused, never bought twice (with a different domain_id it
is conflict, detail code replies_inbox_exists). Any other default stays the Reply-To
until replies@ is read, then replies@ replaces it.
202 with status "pending": bought but not connected yet. conflict with detail code
inbox_not_ready: connected but Kenso does not read it yet. In both, call again in a few
minutes: it reuses the inbox and buys nothing more.
Too few credits is 402 plan_limit_reached with refusal INSUFFICIENT_CREDITS, or
FREE_CREDITS_NOT_ELIGIBLE when only free or bonus credits would cover it. Provider
errors pass through as domains(operation="create-inbox", ...) returns them.

delivery-defaults-update

Write. PATCH https://api.ken.so/v1/delivery-defaults

Body (json): profilePhotoUrl string, redirectUrl string, replyForwardingEmail string, senders array, signatureHtml string, websiteMode string

Change the workspace's delivery defaults. Only the fields you pass change; clear lists fields to empty. Internal. Requires Delivery edit. Confirm the values with the user first. Photo upload is app-only.

PATCH /api/v1/delivery-defaults. Sends Ken-Version 1.1. Requires Delivery edit. Not behind a flag.
Changes nothing already set up: new domains and mailboxes start from these values.

redirect_url: an absolute http or https URL on a public host, at most 2,048 characters, where a new domain's
root redirects; it gets the same link checks as a domain order's forwarding URL, and a Kenso URL is stored as
https://getken.ai. website_mode: "redirect" or "page". senders: 1 to 10 people, each {"first_name",
"last_name", "nickname"} (first and last name 1-40 characters, nickname optional; firstName/lastName also
accepted); it replaces the list. reply_forwarding_email: an external address of at most 254 characters that
new mailboxes forward replies to, never a Kenso address or one on a domain Kenso sends from. signature_html:
HTML or text, reduced to bold, italic, links and lines, at most 10,000 characters after that; it may not link
to a Kenso domain. clear: field names to empty, so each falls back to its derived value or none: redirect_url,
website_mode, senders, profile_photo_url, reply_forwarding_email, signature_html. The photo itself is uploaded
in the app
(POST /v1/delivery-defaults/photo), not here.

Returns the same shape as delivery-defaults-get, after the change. A refused value is 400
validation_failed with error.details[].field naming it (senders[0].firstName, replyForwardingEmail, ...);
nothing is saved then.

delivery-settings-update

Write. PATCH https://api.ken.so/v1/delivery-settings

Body (json): placementAutoPause boolean

Turn the placement auto-pause on or off: pause a domain when a Kenso placement test finds its mail in spam. Public. Requires Delivery edit. Ask the user first. 404 while placement_native is off.

PATCH /api/v1/delivery-settings. Sends Ken-Version 1.1. Requires Delivery edit.
Dark behind the placement_native flag: while it is off the route answers 404 not_found.

placement_auto_pause (required, true or false): on, a completed Kenso domain, weekly, retest or campaign
placement test that finds the domain's mail in spam pauses sending from that domain (send block reason
domain_placement_spam). An inbox-scope test and a copy verdict never pause. Off, a failing test only
records what it would have paused, and lifts the pauses it placed. On by default. It changes campaign
sending, so get the user's yes before turning it on or off.

Returns {"data": {"placementAutoPause": bool}}, the settings after the change.