Replies replies
threads-create starts a new email from a workspace inbox. reply-templates-* are saved reusable reply texts: reply-templates-delete removes a template, never a reply or a thread. Also signature, autonomous replies. The replies people sent (messages and threads) are the threads tool.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through replies_read and changes through replies_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: sync-changes, reply-templates-create, threads-create, translations-create, threads-create-image, threads-create-voice-note, reply-templates-delete, approvals-get, autonomous-reply-settings-get, reply-templates-get, get-signature, sync-hello, reply-templates-list, autonomous-reply-settings-update, reply-templates-update, update-signature
sync-changes
Read. Early access: needs sync_engine on for the workspace. GET https://api.ken.so/v1/sync/changes
Query: limit integer, since string
List what changed in the workspace after a cursor, for the kinds this seat may sync. Read only. Needs a signed-in person (OAuth), not an API key.
GET /api/v1/sync/changes. Sends Ken-Version 1.1; client_id is sent as X-Ken-Workspace-Id. since is the cursor from replies(operation="sync-hello") or the previous page's pagination.nextCursor, which is always set. limit is 1 to 500 (default 200). Each item in data has seq, entity (one of sync-hello's entities), key (the id that kind's own route returns: thr_, msg_, ntf_, mtg_, an approval id, or a number as a string), op (upsert or delete) and, for an upsert, the current row in the field named for its kind in camelCase, so entity account_view is in accountView, never in row[entity] (thread, message, notification, tag, accountView, inbox, domain, member, campaign, sequenceStep, approval, meeting, repNote, contact; threads and messages without htmlBody). A thread upsert is followed by the thread's other live messages under the same seq, so a page can hold more items than limit. A delete means the row is gone, not visible to you, or changed after it left its working set; a row that only ages out sends nothing. Apply them in order. Changes from transactions still in flight are held back until they commit, so a cursor never skips one. pagination.hasMore true means pull again at once with pagination.nextCursor. 410 cursor_too_old for a cursor issued more than 13 days ago: call sync-hello again. 400 for a missing or foreign cursor.
reply-templates-create
Write. POST https://api.ken.so/v1/reply-templates
Body (json): authorSource string, body string, description string, name string
Create a reply template. Returns 201. The template is recorded as agent-written. Requires Inbox edit and the `workspace_settings` permission (owners, admins and editors by default).
POST /api/v1/reply-templates. Public.
Sends Ken-Version 1.1 and X-Ken-Actor: agent.
name is at most 255 characters. description is at most 2000.
The body keeps raw {tokens}.
threads-create
Write. Early access: needs agent_send on for the workspace. POST https://api.ken.so/v1/threads
Body (json): body string, senderInboxId integer, subject string, to object
Start a new email thread to one person from a shared cold inbox. Listed where the workspace's agent_send flag is on, for every seat that can reply. Inbox, quota and outage refusals are 409, 429 or 503, each with a fix and nextAllowedAt when a retry can work. idempotency_key is required: reuse it only to retry the same request.
POST /api/v1/threads. Public once the workspace's agent_send flag is on: then every seat that can reply sees it, and staff see it everywhere (the route answers 404 until the flag is on). Sends Ken-Version 1.1 and X-Ken-Actor agent, so the send is recorded as the agent's and goes through the agent limits even on a person's token: a member and staff get the same refusals. Returns 201 with the first message (id msg_, threadId thr_). The caller needs the same permission as replying in a thread (Reply on the Inbox), Client seats included; a seat that cannot reply gets 403. Send to one recipient: `to` is one plain address and `to_name` is its display name. sender_inbox_id is a shared cold inbox of the workspace: list them with inboxes(operation="list", role="sending", status="active") and pick one with no ownerMemberId on a cold sending domain (not the company's primary domain). A member's own mailbox is refused (not_owned); on not_owned, try another such inbox. idempotency_key (1 to 200 characters) is required. Reuse it on a retry of the same request: the original message comes back with 201 and nothing is sent twice. The same key with another request is 409 idempotency_key_reused, so use a new key for each new email. The send counts against the inbox's day. It goes through the campaign guardrails: contact limits, the send window, suppression, send credits, the domain's DKIM and the free-plan cold-send gate. A 201 may carry warnings: warmup_not_ready, with reason too_young or unconfirmed, a fix, and readyAt for too_young. The email was sent; pick a warmer inbox for the next one if you can. Each new thread uses one of the plan's included sends, then extra_sends credits once those run out (like a campaign send); replies are free. A refusal is the canonical error. details[0].code is the reason, fix says what to do and nextAllowedAt (also Retry-After) says when to retry: - 400 validation_failed: not_owned, not_primary (pick a shared cold inbox), brand_domain (remove the Kenso domain from the body), content_blocked (fix the body or subject), recipient_invalid and unsubscribe_no_contact (send to one valid address). - 409 invalid_state: not_connected, inbox_paused, inbox_send_blocked, sending_paused (an operator paused sending on the inbox, its domain or the workspace, or capacity limits are enforced and an automatic pause covers it: pick another inbox, or wait for a person to lift the pause; nextAllowedAt is when it expires), suppressed (never retry), client_approval_required (the workspace holds replies or campaign copy for client approval, so an agent cannot start threads there: do not retry, and give the person the draft to send). - 409 invalid_state: provider_dkim_failed (DKIM fails on the inbox's domain: pick an inbox on another domain, or retry after nextAllowedAt). - 429 rate_limited: inbox_day_cap, inbox_outreach_gap (pick another inbox or retry after nextAllowedAt); agent_send_quota (workspace-wide: retry after nextAllowedAt, another inbox does not help). - 422 guardrail_violation: contact_limit (the rule field names the Contact limits rule that stopped it). - 402 plan_limit_reached: free_plan_ken_inbox, free_plan_daily_cap, free_plan_no_own_inbox (a plan limit). - 402 free_plan_sending_needs_plan: free_plan_needs_plan (a Free workspace created after the Free no-send rule started sends nothing). error.refusal has code FREE_PLAN_SENDING_NEEDS_PLAN and remedy Upgrade: the user picks a paid plan; no nextAllowedAt. - 402 plan_limit_reached: credits_exhausted (no included sends or credits left), infra_unpaid (the inbox's or its domain's monthly renewal is unpaid). A workspace admin adds credits; no nextAllowedAt. - 409 invalid_state: provider_rejected (the provider did not accept the email, nothing was sent; check the recipient, subject and body or pick another inbox, then retry under a new key). - 503 service_unavailable: unsubscribe_unavailable, pre_submit_error (nothing was sent; retry with the same key, after nextAllowedAt when it is set), agent_guardrails_unavailable (nothing was sent; reply in an existing thread). - 409 in_progress: a send with this key is still running. Retry with the same key after nextAllowedAt. - 409 outcome_unknown: the provider never confirmed the email, so it may have gone out. Do not resend. Read the inbox's threads with this person first, and send under a new key only if nothing went out.
translations-create
Write. Early access: needs multilingual_outreach on for the workspace. POST https://api.ken.so/v1/translations
Body (json): messageId string, targetLanguage string, text string
Translate plain text into an ISO 639-1 language, keeping its line breaks. With message_id (the msg_ id whose own text you send), the result is cached on that email message, so the next call with the same text and language answers from the cache. 20 a minute, 500 a day per workspace. A translation costs credits for its AI work; a cached one is free.
POST /api/v1/translations. Sends Ken-Version 1.1; client_id is sent as X-Ken-Workspace-Id.
Listed where the workspace's multilingual_outreach flag is on, for every seat with inbox view and
Ask (Client seats lack Ask); staff see it everywhere. The route answers 404 until the flag is on.
text (required, at most 8,000 characters) is plain text: a message's main body without quotes or
signature, or a draft. Line breaks, names, links, numbers and {placeholders} are kept.
target_language is a two-letter ISO 639-1 code such as en, fr or es; anything else is 400.
message_id is optional: send it only with that message's own text, never with a draft or other
text (leave it out for those). An email message of the workspace caches the result on itself
under that language, keyed to the text: a later call with the same text answers from the cache
with no model call, and other text is translated again and replaces the entry. An email of
another workspace is 404; a LinkedIn msg_ id is accepted and not cached; any other value is 400.
Returns the API data object: text (the translation) and sourceLanguage (the ISO 639-1 code of the
input, or und when the model named none). A failed model call is 503 "Couldn't translate". Each
call, a cached one included, takes one unit of the workspace's aiTranslations quota (20 a minute,
500 a day): past it, 429 quota_exceeded with Retry-After.
Credits (DEV-7368): each translation the model writes is charged for its AI work (credit action
translation, a typical price on the rate card); an answer from the cache costs nothing.
With no credits left the call is 402 plan_limit_reached, and past the member's own monthly credit
limit it is 402 member_credit_limit_reached; neither calls the model.
Examples:
- replies(operation="translations-create", text="Bonjour,\n\nMerci pour votre message.", target_language="en", message_id="msg_...", client_id=7)
- replies(operation="translations-create", text="Thanks, Tuesday works.", target_language="es", client_id=7)
threads-create-image
Write. POST https://api.ken.so/v1/threads/{threadId}/images
Path: threadId
Upload an image for a Facebook reply. Facebook threads only. A jpg, png or webp image up to 8 MiB; at most 4 wait per thread.
POST /api/v1/threads/{threadId}/images. Public. Sends Ken-Version 1.1.
Multipart field file. Requires Inbox edit and the `reply` permission. Any other thread is 404.
Pass the returned data.id in image_ids on threads(operation="create-message"). An image not
sent within 24 hours is dropped. file_content_base64 is the file's bytes in base64 and
file_name its name; the hosted MCP refuses file_path.
threads-create-voice-note
Write. POST https://api.ken.so/v1/threads/{threadId}/voice-notes
Path: threadId
Body (json): voice object
Make an AI voice note for a Facebook reply. Facebook threads only. Charged like a sent voice note. Returns voiceNoteId to pass on create-message.
POST /api/v1/threads/{threadId}/voice-notes. Internal. Sends Ken-Version 1.1.
Requires Inbox edit, the `reply` permission and the `ask` permission (AI work), so a Client seat
cannot make one. Any other thread is 404.
voice is a JSON object, as a LinkedIn voice_note step takes it: provider and voiceId,
and the optional speed, wordsMode, instructions, script, model and matchLeadLanguage.
The voice note speaks to the thread's person. Response data: voiceNoteId, status,
script, audioUrl (valid for one hour) and durationMs. Send it with
threads(operation="create-message") and voice_note_id; nothing is sent until then.
reply-templates-delete
Write. DELETE https://api.ken.so/v1/reply-templates/{replyTemplateId}
Path: replyTemplateId
Query: authorSource string
Delete a reply template. Returns 204. An agent cannot delete a human-written template: that is forbidden.
DELETE /api/v1/reply-templates/{replyTemplateId}. Public.
Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires Inbox edit and the `workspace_settings` permission (owners, admins and editors by default).
approvals-get
Read. Early access: needs accounts or linkedin_ai_notes or agent_templates or linkedin_engagement on for the workspace. GET https://api.ken.so/v1/approvals/{approvalId}
Path: approvalId
Read one approval item by id, in any status: its draft, facts and actions. Read only.
GET /api/v1/approvals/{approvalId}. Staff. Sends Ken-Version 1.1 and X-Ken-Workspace-Id (DEV-5331).
Needs one of the accounts, linkedin_ai_notes, agent_templates or linkedin_engagement flags on, like
client_approvals(operation="approvals-list"), which lists the items this reads.
- approval_id: the item's id from approvals-list or the Approvals page: reply_4 (an Inbox reply draft
waiting on approval), lnote_5 (a LinkedIn connection note), touch_9001, calendar_write_12, linreq_7,
leng_8, request_501.
Returns the item as approvals-list shows it: id, type, title, status, dueAt, updatedAt, its blocks (a
reply's draft and the message it answers, a note's text and LinkedIn limit) and its actions. An unknown
id, one from another workspace, or one the caller may not approve is 404 not_found, and so is an item
whose source is closed to the caller (its flag is off or its page denies the caller). This only reads:
a change to the draft is the person's decision in Approvals, or client_approvals(operation="approvals-decide")
when they ask you to take it.
autonomous-reply-settings-get
Read. GET https://api.ken.so/v1/autonomous-reply-settings
Return autonomous reply settings for the current workspace. Open to any workspace member. mode is draft, autonomous or approve_risky.
GET /api/v1/autonomous-reply-settings. Public. Sends Ken-Version 1.1. client_id is sent as X-Ken-Workspace-Id. Fields: defaultEnabled, linkedInEnabled, mode, extraInstructions, createdAt, updatedAt.
reply-templates-get
Read. GET https://api.ken.so/v1/reply-templates/{replyTemplateId}
Path: replyTemplateId
Return one reply template in the current workspace. A missing or cross-workspace id is not_found.
GET /api/v1/reply-templates/{replyTemplateId}. Public.
Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires Inbox view.
get-signature
Read. GET https://api.ken.so/v1/me/signature
Return the caller's personal email signature in a workspace. The HTML Knowledge > Signature saves and where the Inbox composer adds it.
GET /api/v1/me/signature with Ken-Version 1.1. Internal exposure. Needs Knowledge view and a member's credential (an API key with no member gets 403). client_id is sent as X-Ken-Workspace-Id. Never writes: a member who never saved reads the defaults. data: html (sanitized HTML, "" when none), addToInboxReplies (default true: the Inbox reply composer adds it to replies the member writes), addToKenDrafts (default true: it adds it under replies Ken drafts for them) and updatedAt (omitted until the first save). Campaign emails use the inbox signature instead.
sync-hello
Read. Early access: needs sync_engine on for the workspace. GET https://api.ken.so/v1/sync/hello
Start tailing a workspace: the cursor to pull changes from, and what this seat may sync. Read only. Needs a signed-in person (OAuth), not an API key.
GET /api/v1/sync/hello. Sends Ken-Version 1.1; client_id is sent as X-Ken-Workspace-Id. Returns seq (the last change id the cursor covers), cursor, floorSeq (the oldest change still kept), schemaVersion, permissionsHash, epoch, window (threadDays 30, notificationSeenDays 30), entities (the kinds this seat may sync; each needs what its own list route needs, so a seat without the Inbox page gets no thread or message) and serverTime. Pass cursor as since to replies(operation="sync-changes"). 404 not_found while the workspace's sync_engine flag is off; 403 unsupported_credential for a raw API key.
reply-templates-list
Read. GET https://api.ken.so/v1/reply-templates
Query: cursor string, limit integer
List reply templates in the current workspace. Ordered by id. Requires Inbox view.
GET /api/v1/reply-templates. Public. Sends Ken-Version 1.1 and X-Ken-Actor: agent. client_id is sent as X-Ken-Workspace-Id. limit is 1 to 200.
autonomous-reply-settings-update
Write. PATCH https://api.ken.so/v1/autonomous-reply-settings
Update autonomous reply settings. Absent fields stay unchanged. Null extra_instructions clears them. Requires the `workspace_settings` permission.
PATCH /api/v1/autonomous-reply-settings. Public. Sends Ken-Version 1.1. mode is draft or autonomous, or approve_risky where the workspace has the reply_agent_approve_risky flag on; elsewhere the API answers approve_risky with the same 400 validation_failed on mode as an unknown mode. approve_risky auto-sends the replies no check flagged and holds the risky ones, meeting requests and negotiation turns for a person. Leave mode out to keep the stored one. extra_instructions is at most 4000 characters. Autonomous and approve_risky send AI replies without a person, so an OAuth connector needs the send consent scope. Sends X-Ken-Actor: agent.
reply-templates-update
Write. PATCH https://api.ken.so/v1/reply-templates/{replyTemplateId}
Path: replyTemplateId
Update a reply template. Absent fields stay unchanged. changes holds name, description, or body. Null description clears it. An agent cannot edit a human-written template: that is forbidden.
PATCH /api/v1/reply-templates/{replyTemplateId}. Public.
Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires Inbox edit and the `workspace_settings` permission (owners, admins and editors by default). Only the fields sent are written.
update-signature
Write. PATCH https://api.ken.so/v1/me/signature
Body (json): addToInboxReplies boolean, addToKenDrafts boolean, html string
Change the caller's own personal email signature in a workspace. Omit a field to leave it unchanged. html "" removes the signature.
PATCH /api/v1/me/signature with Ken-Version 1.1. Internal exposure. Changes only the caller's own row, so any member with Knowledge view can save theirs. client_id is sent as X-Ken-Workspace-Id. Send at least one field. Fields (all optional): - html: the signature as HTML, or plain text whose line breaks are kept. It is sanitized on save and the response returns what is stored: formatting, headings, lists, tables, images (http or https), links (http, https, mailto, tel) and inline styles stay; scripts, style sheets, frames, forms, event handlers, other attributes and CSS that could load or run anything go. At most 20,000 characters after that. "" removes it. - add_to_inbox_replies: add it to replies the member writes in the Inbox. - add_to_ken_drafts: add it under replies Ken drafts for the member in the Inbox. A refused field returns 400 validation_failed with every refusal in error.details (html too_long or too_complex, a boolean required), and nothing is saved. Returns the saved signature, the same shape as replies(operation="get-signature").