Kenso MCP tools

Threads threads

A new email (not a reply) is not on this tool: replies(operation="threads-create", sender_inbox_id, to, subject, body, idempotency_key). Here: inbox threads (replies to campaigns). A reply in a thread: create-message with thread_id and body, no read needed first. Read, unread, archive, save and reminders: update or bulk-update with changes. create here only uploads an attachment.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through threads_read and changes through threads_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, cancel, counts, create, create-message, delete, delete-draft, forward, get, get-content, get-draft, list, list-messages, mark-all-read, promote, replace-draft, suggest, update, variables, email_reply_assist

bulk-update

Write. POST https://api.ken.so/v1/threads/bulk-update

Apply one field update to up to 1,000 threads. Returns per-id succeeded and failed outcomes.

POST /api/v1/threads/bulk-update. Public. Sends Ken-Version 1.1.
Requires Inbox edit. A malformed id fails that row as not_found.
Same fields as threads(operation="update"): interest not_interested stores
ReplyClassification Negative=11, like negative, and a human interest clears
an email reply's three auto-reply markers (automated, out_of_office and
unclassified do not).

cancel

Write. POST https://api.ken.so/v1/scheduled-messages/{scheduledMessageId}/cancel

Path: scheduledMessageId

Cancel a scheduled message that has not started sending. Requires Inbox edit and the `reply` permission. A missing id is not_found.

POST /api/v1/scheduled-messages/{scheduledMessageId}/cancel. Public.
Sends Ken-Version 1.1. A row that is already sending, sent, cancelled, or failed
is 409 invalid_state. A reply in awaiting_approval (waiting on a client seat) can
be cancelled too. Cancel still returns the scheduled message when restoring
the composer draft fails; draft.saved is then false and the caller saves the
draft itself (PUT /api/v1/threads/{threadId}/draft).

counts

Read. GET https://api.ken.so/v1/threads/counts

Query: folder string, groupBy string, isArchived boolean, isSaved boolean, status string

Count inbox threads for a tab, plus the unread and to-reply badges. tab is to_reply, other, automated, not_interested, saved, done, sent or all. group_by=person counts people instead of threads.

GET /api/v1/threads/counts. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Inbox view.
tab maps to the status, folder, isArchived and isSaved query items the app's
tabs send: to_reply, other, automated (status automated_reply) and
not_interested are inbox, not archived; saved is isSaved; done is isArchived;
sent is folder sent; all is folder all, every thread whoever wrote last. Omit
tab for the same: no filter.
Counts cover email and LinkedIn and ignore search, tags, read state, channel
and campaign. Response data:
allCount - threads in the tab.
accountsCount - threads in the tab linked to an account.
campaignsCount - threads in the tab that belong to a campaign.
campaigns - per campaign {campaignId, campaignName, threadCount}.
toReplyCount - the To Reply badge.
unreadCount - the unread badge.
latestMessageAt - time of the newest inbound message in the inbox.
inboxChangedAt - moves when a reply arrives (a late-synced one too), the
classifier files a reply, or a LinkedIn conversation updates. Poll it and
refetch when it changes.
group_by: person counts people (the group_by=person rows),
campaigns[].threadCount included. Folder sent and all keep thread counts
for allCount, accountsCount, campaignsCount and campaigns; toReplyCount
and unreadCount still count people.
facebookUnreadCount: Facebook threads with an unread inbound message,
omitted when Facebook outreach is off.

create

Write. POST https://api.ken.so/v1/attachments

Upload a pending attachment for an email message. message_id is an email msg_ id. Caps are 5 files, 8 MiB each, 10 MiB pending.

POST /api/v1/attachments. Public. Sends Ken-Version 1.1.
Multipart field file plus form field messageId. Requires Inbox edit.
A message id that is not an email msg_ id is validation_failed.

file_content_base64 is the file's bytes in base64 and file_name its name
(pdf, image, office, txt, or csv). The hosted MCP refuses file_path,
because it cannot read your machine; off the hosted MCP, file_path opens
only a file inside the MCP export directory.

create-message

Write. POST https://api.ken.so/v1/threads/{threadId}/messages

Path: threadId

Body (json): archiveAfterSend boolean, attachmentIds array, bcc array, body string, cc array, confirmSuppressed boolean, contentType string, delaySeconds integer, imageIds array, mediaIds array, replyAll boolean, senderEmailId integer, subject string, to array, voiceId string, voiceNoteId integer, voiceProvider string

Send a message on a thread. Email requires sender_email_id. An email reply waits 300 seconds before it sends, and threads(operation="cancel") stops it in that window.

POST /api/v1/threads/{threadId}/messages. Public. Sends Ken-Version 1.1.
Requires Inbox edit and the `reply` permission. Returns 201. LinkedIn sends plain text at once.
Instagram sends plain text of at most 1,000 characters at once from the chat's
account, refuses the email-only fields below, Facebook's image_ids and
voice_note_id, and WhatsApp's media_ids, voice_provider and voice_id with 400, and answers 409
invalid_state when the account is paused, resting, at its limit or disconnected
(retry after details[0].nextAllowedAt when set). 503 means Instagram did not
confirm the send and it may have gone out: to retry, send the same body and images
with the same idempotency_key (or again none), never a new key: Kenso then answers the
reply it already stored or reuses the provider key. An agent's reply through
an account another member connected is 403.
Undo window: an email reply is queued, then sent. delay_seconds is 60 or 300; omit it
for 300, the agent window (the app's own composer uses 60). The 201's
data.scheduledMessageId is the queued reply: pass it as scheduled_message_id to
threads(operation="cancel") to stop the reply before the window ends. LinkedIn ignores
delay_seconds and has no scheduledMessageId. A retry under the same idempotency_key
returns the first reply, whatever its delay.
subject is for drafts only: a reply goes out on the thread's subject, so this operation
does not send it. Set a draft's subject with threads(operation="replace-draft").
Email only, as threads(operation="forward") takes them: to, cc and bcc are lists of
{"address": ..., "name": ...} (name optional), each one bare email address. Without to
the reply goes to the thread's sender; reply_all true sends it to the sender, To and Cc
instead, less the sending inbox. attachment_ids are att_ ids uploaded against this thread.
content_type is html or text; omit it for html. A LinkedIn thread refuses every one of
these with 400 validation_failed on that field and sends nothing.
idempotency_key is sent as Idempotency-Key. On email (at most 200 characters) a retry
with the same key returns the reply it scheduled (or the 202 with the client approval
item it was held as) and queues nothing; the key with
another thread, inbox, body, to, cc, bcc, reply_all, content_type or attachment_ids is
409 idempotency_key_reused, one still being queued is
409 in_progress (retry after details[0].nextAllowedAt), 409 outcome_unknown means
do not resend: read the thread first, and 409 reply_not_sent means the scheduled reply
ended failed or cancelled and never went out (send again with a new key).
Sends X-Ken-Actor: agent, so the reply is recorded as the agent's (source mcp). An email
reply from a paused or send-blocked inbox is 409 invalid_state with details[0].code
inbox_paused or inbox_send_blocked: reply from another inbox, or retry after
details[0].nextAllowedAt (the block's end; a pause has no known end and carries none, so
retry once a member resumes the inbox). A pause that lands while the reply waits out its
undo delay ends that scheduled message in status failed; a block is retried for a few
minutes and ends it failed if it outlasts them.
A person replying in the dashboard from a client seat's own inbox gets 202 with a
scheduled message in status awaiting_approval and approverMemberId: it sends only
after that client approves it (approval type reply.email). An agent or API key
replying from its own member's mailbox is not refused: the reply (and a forward from
that mailbox) waits as a pending approval until that member approves it in person in
Kenso. From another member's own mailbox it is 403. A LinkedIn reply through a seat
another member connected is not sent either: it returns 202 with status
awaiting_approval, channel linkedin, approvalId (approval type reply.linkedin) and
approverMemberId (the seat owner), and sends only once that member approves it in
person in Kenso; tell the person it waits for them. A retry with the same idempotency_key
returns the same waiting reply. If that member cannot approve it, it is 403. Through
the caller's own seat it sends as before. Email archive_after_send archives the
thread once the reply sends (a waiting reply: once the approved reply sends, never while
it waits).
confirm_suppressed overrides a suppression: the contact opted out or is blocked, so the
reply mails someone who asked not to hear from you. An agent sets it only when a person
asked for that reply. Without it a suppressed contact is 409 invalid_state with
details[0].field confirmSuppressed and the reason in details[0].code; with it the 201
carries warnings (code suppressed_contact_overridden, reason) and the override is audited.
Facebook: body (optional with images or a voice note, at most 2,000 characters), then
image_ids (from replies(operation="threads-create-image")), then voice_note_id (from
replies(operation="threads-create-voice-note")), each its own message. A part that fails
stops the rest (409 invalid_state says how many were sent); 503 means Kenso cannot tell
whether it was sent: read the thread, never resend under the same idempotency_key. An
agent replies only through a Facebook account its own member connected (403 otherwise).
delay_seconds does not apply.
WhatsApp threads only (DEV-7890): a reply sends at once through the chat's account, as
plain text of at most 4096 characters. media_ids are up to 6 message media ids (images);
body may be empty when media_ids is set. voice_provider and voice_id turn body into a
voice note script (at most 900 characters). An agent reply through another member's
account returns 202 awaiting_approval with approvalId (type reply.whatsapp), as LinkedIn.
WhatsApp's limits answer 409 invalid_state with details[0].nextAllowedAt.

delete

Write. DELETE https://api.ken.so/v1/attachments/{attachmentId}

Path: attachmentId

Delete a pending attachment that has not been sent. Returns 204. A malformed id is not_found.

DELETE /api/v1/attachments/{attachmentId}. Public. Sends Ken-Version 1.1.
Requires Inbox edit.

delete-draft

Write. DELETE https://api.ken.so/v1/threads/{threadId}/draft

Path: threadId

Delete the draft for a thread, whoever wrote it. Returns 204. A malformed thread id is not_found.

DELETE /api/v1/threads/{threadId}/draft. Public.
Sends Ken-Version 1.1 and X-Ken-Actor: agent. Requires Inbox edit.
This discards a person's draft too. Call it only when the user asks to
discard the draft, never to clear the way for a draft of your own.

forward

Write. POST https://api.ken.so/v1/threads/{threadId}/forward

Path: threadId

Body (json): archiveAfterSend boolean, attachmentIds array, bcc array, body string, cc array, contentType string, delaySeconds integer, injectPreviousEmailBody boolean, replyAll boolean, replyTemplateId integer, senderEmailId integer, to array, useDedicatedIps boolean

Forward an email thread to new recipients. Returns the queued message. Requires Inbox edit and the `reply` and `export` permissions. to is required unless reply_all is true.

POST /api/v1/threads/{threadId}/forward. Public. Sends Ken-Version 1.1.
Email only. The forward is queued and the provider confirms delivery later.
sender_email_id is required unless reply_all is true. delay_seconds is 60 or 300.
Omit delay_seconds for 60. content_type is html or text. Omit it for html.
attachment_ids are att_ ids for this thread. A disconnected inbox is 409 invalid_state.
Each recipient is one bare email address. A forward that reaches the thread (reply_all
without to, or the contact or another participant as a recipient) is 409 invalid_state
when the contact is suppressed or the workspace holds replies for external approval; send
it as a reply with threads(operation="create-message") instead.
A queued forward returns 200. An agent or API key forwarding from its own member's
mailbox is not refused: it returns 202 with the message in status awaiting_approval and
approverMemberId, and waits as a pending approval until that member approves it in person
in Kenso. From another member's own mailbox it is 403.

get

Read. GET https://api.ken.so/v1/threads/{threadId}

Path: threadId

Return one thread in the current workspace. A malformed id or a thread outside the workspace is not_found.

GET /api/v1/threads/{threadId}. Public. Sends Ken-Version 1.1.
thread_id is a thr_ id. Requires Inbox view.
Email threads include senderName, fromName, fromEmailAddress, htmlBody, tags,
and to, cc, and bcc. LinkedIn threads include senderName and fromName (the
contact's name) and tags (the conversation's), and omit the others, as do
Instagram threads (a chat with a person of the workspace whose handle is
accepted; any other chat, and every one while Instagram is off, is not_found).
Recruiting replies classified `referral` carry `referral` (`name`, `email`,
`linkedinUrl`, `phone`, each copied from the reply or null) on the thread and on
the inbound message. A person with only a phone has no email or LinkedIn URL to
add them by: ask the user for one.
accountId and accountName are the account whose touch the thread is, else the
account on which the thread's contact is a stakeholder. Absent when none.
replyTouchId, on an email thread of an account touch, is that account's open
reply touch (planned, drafted, awaiting_approval or approved) answering the
thread; approve it with touches approve to send the reply. hasDraft is true when
a reply draft is saved on the thread, and draftAuthor says who wrote it: user
(a person) or agent.
language is the ISO 639-1 code (fr, es, ...) of the newest inbound message,
absent (null) when unknown or the thread has no inbound message.
scheduledMessages lists the thread's replies that have not sent yet: status
scheduled, sending, or awaiting_approval (a teammate's reply from a client
seat's own inbox, with approverMemberId, waiting until that client approves it).

get-content

Read. GET https://api.ken.so/v1/attachments/{attachmentId}/content

Path: attachmentId

Query: inline boolean

Download an attachment: its name, type, size and bytes as base64. inline=true is only honored for an inline image. A malformed id is not_found.

GET /api/v1/attachments/{attachmentId}/content. Public. Sends Ken-Version 1.1.
attachment_id is an att_ id. Requires Inbox view.
Returns data with fileName, contentType, size (bytes) and contentBase64, the
file's bytes in base64. A UTF-8 text file (text/* or JSON) also returns
text, its content as text, unless that text is JSON: decode contentBase64
for a JSON file. A file over 2 MiB (2,097,152 bytes) is refused with a
validation error: open it from the thread in the Kenso inbox instead.

get-draft

Read. GET https://api.ken.so/v1/threads/{threadId}/draft

Path: threadId

Return the saved draft for a thread. A missing draft is not_found.

GET /api/v1/threads/{threadId}/draft. Public.
Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires Inbox view. A malformed thread_id is not_found.
authorSource says who last wrote the draft: user (a person in the app) or
agent. An agent's save never overwrites a person's draft.
mirror is {text, language} when Ken's reply agent wrote the draft in the
lead's language: the same reply as plain text in the reader's language
(language is ISO 639-1, en today). Absent otherwise; a person's save
that changes the body clears it. It is for reading only and is never
sent.
An email draft that came from Ken's reply agent carries agentJobId, the
reply-agent job it came from. Absent on a draft a person wrote.

list

Read. GET https://api.ken.so/v1/threads

Query: campaignId integer, channel string, contactId integer, cursor string, folder string, groupBy string, hasReminder boolean, inboxId integer, interest string, isArchived boolean, isRead boolean, isSaved boolean, limit integer, personKey string, q string, sort string, source string, status string, tagIds array

List threads in the current workspace. tab picks an inbox tab. channel is email, linkedin, instagram, facebook or whatsapp. source is accounts or campaigns. sort is oldest_waiting. limit is 1 to 100. group_by=person groups rows by person; person_key lists one person.

GET /api/v1/threads. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Inbox view.
Email rows include senderName, fromName, fromEmailAddress, htmlBody, tags,
and to, cc, and bcc. LinkedIn rows include senderName and fromName (the
contact's name) and tags (the conversation's), and omit the others. Ids are
thr_ of the email thread key.
Instagram rows (channel instagram, only while the workspace has Instagram on)
are direct-message chats with a person of the workspace whose Instagram handle
is accepted (verified, or set by a member); chats with anyone else are never
listed or counted. They carry
senderName and fromName (the person's name) and tags, like LinkedIn rows.
Every row has direction: inbound when the contact sent the newest message the
row stands for, outbound when we did. On an outbound email row fromName is
ours, so the contact is the first of to. A LinkedIn row's fromName is the
contact either way. The one-thread read leaves direction out: each of its
messages carries its own.
language is the ISO 639-1 code (fr, es, ...) of the newest inbound message
the row stands for: absent (null) when unknown and on an email row whose
newest message is ours. A LinkedIn row reads its newest inbound message.
Ordered for the inbox, newest first. sort=oldest_waiting lists the thread that
has waited longest first, across pages: by waitingSince, else by the newest
message, so tab=to_reply works the replies that waited longest first. A row
whose newest message is the contact's carries waitingSince, when that message
arrived, on any tab; it is a wait on a reply only on to_reply. A thread we
answered that a due reminder keeps on to_reply carries the reminder's due time
as waitingSince, not the time of the reply we answered. Omit channel to
include email, LinkedIn, Instagram and WhatsApp (each chat channel only while
the workspace has it on), never Facebook.
channel facebook lists Facebook threads: only chats with a person of the
workspace, never a group; it takes limit, cursor and is_read only. With
Facebook outreach off for the workspace it is 400.
pagination.total counts threads. With q it counts at most 1,000: past
1,000 it is 1,000 and pagination.isTotalCapped is true, so say "1,000+"
and keep paging while hasMore is true. Without q, or with 1,000 matches or
fewer, total is exact and isTotalCapped is left out.
tab: to_reply, other, automated, not_interested, saved, done, sent, all. It is
sent as the status, folder, isArchived and isSaved the app's tab uses, so the
list matches the tab count from threads counts. all is folder all: every
thread, whoever sent its newest message, archived and saved ones included (the
app's All tab shows only threads whose newest message is the contact's). Omit
tab for the same: no tab filter.
interest or has_reminder (true or false) with tab all or no tab sends folder
inbox instead. Under folder all an email thread's row is its newest message in
either direction, and our messages never carry an interest or a reminder, so
the filter would miss every thread we answered; folder inbox reads each
thread's newest reply. LinkedIn ignores folder. Every other tab keeps its own
folder.
An explicit is_archived or is_saved overrides the tab's value.
q searches every tab: it drops the tab's status, folder, is_archived and is_saved
(and an explicit is_archived or is_saved), so a match in sent, done or saved
threads comes back too. is_read, campaign_id, tag_ids, channel, source,
contact_id, inbox_id, interest and has_reminder still apply with q, to each
thread's newest message that matches q, ours included. A q under 3
characters matches whole subject and body words only; use 3+ characters (or
the domain) to match a sender, recipient or company.
source: the lane on top of the tab. accounts lists only 1:1 account threads
(threads of an account touch), campaigns only campaign threads, so the list
matches accountsCount and campaignsCount from threads counts. Omit it for both.
A row of an account thread carries accountId and accountName, and an email one
replyTouchId: that account's open reply touch answering the thread, which sends
the reply when approved. Every row carries hasDraft, true when a reply draft is
saved on it, and then draftAuthor: user (a person) or agent.
interest: interested, not_interested, negative, automated, unclassified,
unsubscribe, objection, wrong_contact, out_of_office, referral.
not_interested matches replies stored as NotInterested=1 or Negative=11.
inbox_id and a row's inboxId: a LinkedIn thread's account; an email row's
workspace inbox, the one its message was sent to (a reply's to) or from (ours).
With no channel (email and LinkedIn), inbox_id matches an email inbox or a
LinkedIn account with that id, so pass channel to stay on one.
group_by: person lists one row per person (its newest thread in the tab);
pagination.total counts people. Rows add personKey (per_<id>, else
con_<contactId>, else the row's thr_ id), personId and personName (null
unless per_), channels {email, linkedin}, waitingCount (their threads
To Reply lists) and threadIds (newest first, at most 200), over their
threads on any tab. On folder sent or all in the default order without
q, total may be capped, counting only the people among the newest
messages read; when pagination.isTotalCapped is true, show the total as
"N+" and page while hasMore is true. With q the total caps at 1000
people, as a plain search's does.
sort=oldest_waiting orders people by their longest wait.
person_key: a row's personKey. Lists that person's threads in every folder,
newest first, with the same fields. Filters still narrow it, and interest or
has_reminder with no tab reads their replies (folder inbox), as above.

list-messages

Read. GET https://api.ken.so/v1/threads/{threadId}/messages

Path: threadId

Query: includeEvents boolean

List messages in a thread, oldest first. Message ids are msg_. A malformed thread id is not_found. Each item has a kind: message; LinkedIn with include_events=true adds connection_note and connection_accepted; Instagram adds story_reply, story_mention and notice.

GET /api/v1/threads/{threadId}/messages. Public. Sends Ken-Version 1.1.
An Instagram notice is Instagram's own note in the chat, such as a refused
message: it has no senderName and is nobody's words.
Every item carries kind. include_events=true (sent as includeEvents, only
when true) adds two LinkedIn events in time order, an event before a message
sent at the same instant: connection_note is the note Kenso sent with the
connection request (outbound, body is the note) and connection_accepted is the
moment the person accepted (inbound, empty body). An email thread ignores it.
Requires Inbox view. Email messages include senderName, fromName,
fromEmailAddress, htmlBody, tags, and to, cc, and bcc. LinkedIn omits those.
Inbound email messages also carry extractedText: the sender's own words
without quoted history, signature, mobile footer or sign-off (body keeps the
full text). Read it first when answering a reply. It is absent on outbound
and LinkedIn messages and when the reply has no readable body.
Inbound messages carry language, the ISO 639-1 code (fr, es, ...) of that
message: the classifier's, else detected from its own words. It is absent
(null) when unknown and on outbound messages.
Outbound email messages also carry openCount (proxies and crawlers
excluded), rawOpenCount, firstOpenedAt and lastOpenedAt.
An email message with files carries attachments: fileName, contentType,
sizeBytes, isInline, contentId (what an inline image's cid: points at) and
id, an att_ id: download it with threads(operation="get-content",
attachment_id=...), which returns the bytes as base64 (contentBase64) and,
for a text file, its text, up to 2 MiB. id is absent when Kenso cannot serve
the file (older messages). The field is absent when the message has no files.
A LinkedIn voice note carries voiceNote: voiceNoteId, status, durationMs,
language, provider, voiceId, scriptText (the words spoken), failureReason,
audioAvailable and audioUrl (while the audio is kept). A lead's own voice
note has voiceNoteId 0, status received and only durationMs; one the seat
owner sent from LinkedIn itself is the same with status sent. The field is
absent on every other message.
An email Ken sent (the reply agent, a reply a client approved first
included, or a workflow's reply step) carries sentBy: agent and, when the
reply-agent job is known, agentJobId (the job whose draft went out). Both
are absent on a message a person sent.
An outbound email reply or 1:1 follow-up that went out without the earlier
message Kenso quotes below it carries quoteDroppedReason:
brand_domain_in_quote (the earlier message loads from a Kenso host or
carries a Kenso tracking link, which never go in cold email) or
brand_domain_when_joined (only the reply and the quote joined do). The reply
itself went out as written. The field is absent when the quote went out and
on older messages.

mark-all-read

Write. POST https://api.ken.so/v1/threads/mark-all-read

Mark every unread thread in the workspace read. There is no undo. This is the Inbox "Mark all as read" menu item. Returns updatedCount.

POST /api/v1/threads/mark-all-read. Public. Sends Ken-Version 1.1. No body.
A write. Marks every unread email and LinkedIn thread in the workspace read,
across all tabs, with no filters and no undo. Idempotent: a repeat call finds
nothing unread. Response data: {"updatedCount": n}.
To mark only some threads, use threads bulk-update with is_read.

promote

Write. Early access: needs accounts, promote_to_accounts on for the workspace. POST https://api.ken.so/v1/threads/{threadId}/promote

Path: threadId

Body (json): stage string

Promote a campaign thread's contact to Accounts: their company becomes a target account. Reuses the account that already owns the company domain. Never stamps do-not-contact.

POST /api/v1/threads/{threadId}/promote. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Requires inbox edit. stage is researching, warming (default) or engaged.

The company comes from the contact's company domain, else their email domain. A new
account starts at stage with source promoted and Ken researches it. An existing
account only moves forward (researching, warming, engaged, meeting_booked, in_deal); one at
new moves to stage, and one in customers, later, network or archive keeps its stage. The contact joins as an engaged
stakeholder (priority 1) when they have an email or a LinkedIn URL. Every campaign
sequence at the account's domains stops. One account.promoted activity event per account.

Returns data.stage, data.accounts (accountId, name, domain, created, stage,
previousStage when an existing account moved, research, people with result added,
already_member, no_identity, previously_removed or failed, sequenceStop done or failed
(failed: promote again to retry the stop) and sequencesStopped) and data.skipped
(contactId, code, message). A thread without a
campaign contact is 409 invalid_state. A contact that cannot be promoted (no company
domain, a free email domain) is 400 validation_failed with the skip code as the detail code.

replace-draft

Write. PUT https://api.ken.so/v1/threads/{threadId}/draft

Path: threadId

Body (json): authorSource string, body string, subject string

Replace the draft for a thread. An empty body deletes it. Requires Inbox edit. A person's draft is never replaced: the result then has kept_person_draft true. Otherwise an empty body returns 204.

PUT /api/v1/threads/{threadId}/draft. Public.
Sends Ken-Version 1.1 and X-Ken-Actor: agent, so the draft is recorded as
agent-written and never overwrites or deletes a person's draft (DEV-3111).
When a person's draft is on the thread, nothing is saved: the result is the
person's draft with kept_person_draft true and a message. Tell the user the
draft was not saved. A malformed thread_id is not_found.

suggest

Write. POST https://api.ken.so/v1/threads/{threadId}/draft/suggest

Path: threadId

Body (json): action string, draft string, selection string, senderEmail string, toneOrInstruction string

Suggest a draft body for a thread. Nothing is saved or sent. Internal. A blank action is rewrite.

POST /api/v1/threads/{threadId}/draft/suggest. Internal. Sends Ken-Version 1.1.
Actions are rewrite, simplify, shorten, lengthen, tone, custom, continue, and draft_from_chip
(draft-from-chip is the same action). tone and custom use tone_or_instruction.
LinkedIn threads get plain text of at most 8,000 characters and ignore sender_email.
A missing thread is not_found. This tool returns threadId, body and suggestionId
(sug_ and 20 url-safe characters, the suggestion's id).
Accept: text/event-stream returns a suggestion frame with suggestionId first, then
token frames. Each token carries text and delta for the same chunk, then done or
error. Other clients still get body.

update

Write. PATCH https://api.ken.so/v1/threads/{threadId}

Path: threadId

Update thread fields. Absent fields stay unchanged. Null reminder_at clears a reminder. Setting one also saves the thread, on email and LinkedIn alike. Requires Inbox edit.

PATCH /api/v1/threads/{threadId}. Public. Sends Ken-Version 1.1.
Fields: is_read, is_archived, is_saved, interest, reminder_at.
A malformed thread_id is not_found. LinkedIn rejects interest automated.
person_id links the thread's contact to that person,
replacing any link; a merged person links as its survivor. It needs the
unified_inbox feature for the workspace (off is not_found) and Accounts edit
(without it, permission_denied 403). No contact is unprocessable (422) and a
missing or deleted person not_found, as is a person outside the caller's own
accounts when its seat sees only those; each answers before any field is
written, and the link is written after the other fields. bulk-update
refuses it.
interest not_interested and negative store the same ReplyClassification,
Negative=11, as the app's Not interested label does, so the thread then reads
interest negative. The legacy inbox mark-as-not-interested route still stores
NotInterested=1, and a reply stored that way reads not_interested. The list
filter interest=not_interested matches both values, and both sit on the
not_interested tab.
On an email reply, a human interest (any value but automated, out_of_office
and unclassified) clears all three auto-reply markers, isAutoReply,
isOutOfOffice and aiIsOoo, in the same write as the label. Reply-stop skips
a reply with any of them, so with them gone the planner and the send fence
stop the contact's sequence on their next read. That later clear runs
neither the LinkedIn all-channel stop nor the company-wide stop (which stops
colleagues at the same company): those run only when the reply arrives.
automated sets the auto-reply flag; out_of_office leaves the markers;
unclassified clears the label and leaves the markers as they are.

variables

Read. GET https://api.ken.so/v1/threads/{threadId}/variables

Path: threadId

Query: senderEmail string

Resolve reply variables for an email thread. Internal. sender_email selects the From mailbox for sender variables.

GET /api/v1/threads/{threadId}/variables. Internal. Sends Ken-Version 1.1.
Requires Inbox view. LinkedIn threads are rejected. A missing thread is not_found.
Each variable has name, syntax, description, category, value, and hasValue.

email_reply_assist

Write.

Generate a draft-only AI reply suggestion for a Master Inbox message.

Generate a draft-only AI reply suggestion for a Master Inbox message.

Maps to POST /api/v1/inbox/ai/assist and buffers the backend SSE token
stream into a single text result for MCP callers. This tool never sends,
forwards, archives, or mutates the reply. It only returns suggested text.

Required:
- message_id: the reply to answer: the msg_ id of an inbound email message from
  threads(operation="list-messages", thread_id=...). A raw inbox message id
  still works. A LinkedIn message's msg_ id is a 404.
- action: rewrite | simplify | shorten | lengthen | tone | custom |
  continue | draft-from-chip (draft_from_chip is the same action).
- draft or selection for rewrite-like actions. Use selection when the user
  highlighted part of a draft; otherwise pass draft as the full composer
  content.
- tone_or_instruction for action="tone" or action="custom".

Optional:
- client_id: forwarded as clientId query parameter when supplied.
- sender_email: selected sending inbox email for sender-signature context.
- model_override: backend model override for debugging.

Uses credits for the AI work of the suggestion (reply_assist on the rate
card), capped per run. Refused with INSUFFICIENT_CREDITS when the
workspace has less than 1 credit available.

Returns:
{ success: true, data: { messageId, action, text, tokenCount } }