Threads
Inbox threads across email and LinkedIn: count and list them, read messages, reply, forward, update in bulk and keep drafts.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
threadId | path | string | required | The thread's thr_ id. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List threads
/v1/threadsthreads.list- Permission
- Inbox view
- Rate limit
- 12,000 requests a minute per API key
Lists the workspace's inbox threads, one row per thread, newest first. Each row shows the thread's newest message in the tab you ask for. limit is 50 by default and at most 100.
Pick the tab with status and folder. To Reply (status=to_reply) lists campaign threads whose newest reply is interested, objection, wrong_contact or referral, plus threads whose reminder came due. A thread leaves To Reply once your reply is its newest message and comes back with the contact's next reply. source narrows a tab to account threads or campaign threads, as accountsCount and campaignsCount on GET /v1/threads/counts count them.
Kenso applies contactId, inboxId, interest and hasReminder before paging, so hasMore and pagination.totalCount count only matching threads. On folder=all a row is the newest message in either direction, and a message you sent has no label and no reminder. To filter threads by their newest reply, list with folder=inbox.
pagination.totalCount counts threads, the same number as allCount on GET /v1/threads/counts. With q the total stops at 1,000: past that it reads 1,000, pagination.isTotalCapped is true, and you can keep paging while hasMore is true.
sort=oldest_waiting lists the thread that has waited longest first, across pages. groupBy=person lists one row per person instead of one per thread, and personKey lists one person's threads. Both add the person fields to each row.
channel=facebook lists Facebook threads, only chats with a person of this workspace (never a group), and takes limit, cursor and isRead only; any other filter is 400 validation_failed on that field. When Facebook outreach is off for the workspace it is 400 like any unknown channel. channel=all lists email and LinkedIn threads, plus matched Instagram and WhatsApp chats while the workspace has those channels on, and never Facebook threads.
Errors:
400 validation_failed:limitis outside 1 to 100,cursoris invalid, orchannel,interest,source,sort,groupByorpersonKeyis not a known value.
Requires Inbox view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channel | query | string | optional | The channel: email, linkedin, instagram, whatsapp or all. Omitted, it is all. Instagram and WhatsApp chats are listed only while the workspace has that channel on. |
campaignId | query | integer (int64) | optional | Only this campaign's threads. |
inboxId | query | integer (int64) | optional | Only threads whose inboxId is this id: a LinkedIn thread's LinkedIn account, or the workspace inbox an email row's message was sent to or from. Email inbox ids and LinkedIn account ids can repeat across channels, so on channel=all the id matches either. Pass channel to stay on one. |
contactId | query | integer (int64) | optional | Only threads with this contactId, as each row carries it: the stored contact, or for a LinkedIn conversation stored without one, the contact its person matches. |
interest | query | string | optional | Only threads whose row carries this label: interested, not_interested, negative, automated, unclassified, unsubscribe, objection, wrong_contact, out_of_office or referral. not_interested also matches negative. Under folder=all a row is the newest message in either direction, and a message you sent has no label, so a thread you already answered matches only unclassified. To filter by each thread's newest reply, list with folder=inbox. |
status | query | string | optional | The inbox tab: to_reply, other, automated_reply, not_interested or human_reply. Kenso applies it before paging. Any other value is ignored. |
folder | query | string | optional | The folder: inbox (replies you received), sent (messages you sent) or all (both). Omitted, it is inbox. |
source | query | string | optional | Narrows the tab to accounts (threads of an account touch) or campaigns (campaign threads), the same split as accountsCount and campaignsCount on GET /v1/threads/counts. Omitted lists every thread of the tab. Any other value is 400 validation_failed. |
sort | query | string | optional | The order. oldest_waiting lists the thread that has waited longest first, across pages: by each row's waitingSince, else its newest message. Omitted keeps the inbox order, newest first. Any other value is 400 validation_failed. |
groupBy | query | string | optional | Set to person to list one row per person, the person's newest thread in the tab. Each row adds personKey, personId, personName, channels, waitingCount and threadIds, and pagination.totalCount counts people. With q the total stops at 1,000 people. On folder=sent or folder=all, in the default order and without q, Kenso counts only the people among the newest messages it read for the page. When pagination.isTotalCapped is true, show the total as a lower bound and page while hasMore is true. With sort=oldest_waiting a person sorts by their longest wait in the tab, and the row stays their newest thread. Omitted lists one row per thread. Any other value is 400 validation_failed. |
personKey | query | string | optional | A row's personKey (per_, con_ or thr_): lists every thread of that person, archived or not, newest first, each with the person fields of groupBy=person. It covers every folder unless you pass folder or status, and other filters still apply. A malformed key is 400 validation_failed. |
isRead | query | boolean | optional | True lists read threads, false unread ones. Omitted lists both. |
isArchived | query | boolean | optional | True lists archived threads, false the rest. Omitted lists both. |
isSaved | query | boolean | optional | True lists saved threads, false the rest. Omitted lists both. |
hasReminder | query | boolean | optional | True lists threads whose row carries a reminder, false those whose row carries none. Under folder=all a row is the newest message in either direction, and a message you sent has no reminder. To filter by each thread's newest reply, list with folder=inbox. |
tagIds | query | array of integer (int64) | optional | Only threads with any of these tag ids. Repeat the parameter for each id. |
q | query | string | optional | Search text. It matches the subject and body, the sender's domain, a recipient's email address, and the company name or domain. A term under 3 characters matches whole words of the subject and body only. |
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
limit | query | integer (int32) | optional | Threads per page, from 1 to 100. Omitted, it is 50. |
curl -X GET "https://api.ken.so/v1/threads?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of PersonThread. Each item has these fields. The response also carries pagination.
Show the 40 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Start an email thread
/v1/threadsthreads.create- Permission
- Inbox edit and the
replypermission - Rate limit
- 10 requests a minute per API key; 30 requests a minute and 500 a day per workspace (Free plan: 3 a minute and 50 a day)
agent_send feature on your workspace. Until it is on, calls answer 404.Sends a new email to one person from one of the workspace's shared cold inboxes, which starts a thread. Use it when an agent or an integration opens a conversation outside a campaign. A member's own mailbox cannot send it.
senderInboxId, to.address, subject and body are required, and the body is HTML. The Idempotency-Key header is required, from 1 to 200 characters. A retry with the same key and the same request returns the first message with 201 and sends nothing.
Kenso checks each send against the workspace's sending rules first: the inbox's daily limit, pauses and blocks, the contact's suppression, the workspace's contact limits, the content rules and the agent send quota. A refusal is an error whose details[0].code names the reason, with a fix that says what to do. When a later retry can work, the detail also carries nextAllowedAt and the response a Retry-After header.
An inbox that has not finished warmup still sends. The 201 then carries a warnings entry with code warmup_not_ready, a reason of too_young or unconfirmed, a fix, and readyAt for too_young. A replay carries no warnings. Kenso records the send only after the email provider accepts it.
Errors:
400 validation_failed: a required field or theIdempotency-Keyheader is missing, the key is longer than 200 characters, the recipient is not one valid address, the inbox cannot send for an agent or API key, or the content breaks a cold email rule.402 plan_limit_reached: the workspace has no sends or credits left, or a Free plan rule refuses the send.402 free_plan_sending_needs_plan: the workspace is on the Free plan, which sends nothing for a workspace created after the Free no-send rule started.error.refusalhascodeFREE_PLAN_SENDING_NEEDS_PLANandremedyUpgrade: pick a paid plan, then send again.403 forbidden: agent sending or 1:1 sending is not turned on for this workspace.404 not_found: the inbox is not in this workspace.409 in_progress: a send under this key is still running. Retry after theRetry-Afterheader, 30 seconds.409 outcome_unknown: Kenso cannot tell whether the provider took the email, and never resends it. Read the inbox's threads with the person before you send again under a new key.409 invalid_state: the inbox is paused, blocked or not connected, the person must not be emailed, the workspace holds replies or campaign copy for client approval, or the provider refused the email.422 idempotency_key_reused: the key was used for another request. This operation answered409for it before 2026-11-17.422 guardrail_violation: the send breaks one of the workspace's contact limits. Withagent_contact_limit_overrideon for the workspace, an agent'soverrideContactLimits: truesends it anyway (not an API key's).429 rate_limited: the inbox has no sends left today, sent a new email less than 5 minutes ago, or the workspace used up its agent send quota.503 service_unavailable: Kenso could not add the unsubscribe link or reach the provider. Retry later.
Requires Inbox edit and the reply permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | required | Required. A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. Kenso records the key with what the request did, so a repeat of the same request with the same key does not do it twice: the description says what a repeat returns. The same key with a different request answers 422 idempotency_key_reused. This operation answered 409 for it before 2026-11-17: branch on the code, not the status. Keys are per workspace and at most 200 characters long. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
senderInboxId | integer (int64) | required | Required. The id of one of the workspace's shared cold inboxes, from GET /v1/inboxes. A member's own mailbox is refused. |
to | CreateThreadRecipient | required | Required. The one person the email goes to. |
subject | string | required | Required. The email's subject. |
body | string | required | Required. The email body as HTML. |
overrideContactLimits | boolean | optional | true sends this email past a contact limit that refuses it (weeks between touches, the send window, an account with an open deal), for an agent in a workspace with agent_contact_limit_override on; otherwise, and for an API key, the limit's 422 guardrail_violation stands. Default false. |
curl -X POST "https://api.ken.so/v1/threads" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H 'Idempotency-Key: string' \
-H "Content-Type: application/json" \
-d '{
"senderInboxId": 5530,
"to": {
"name": "Priya Shah",
"address": "[email protected]"
},
"subject": "Amanda Chen suggested I reach out",
"body": "<p>Hi Priya,</p><p>Amanda mentioned you run onboarding for new engineers. Could I send you a 2-minute video on how we cut setup time?</p><p>Alex</p>"
}'Response 201
data is a ThreadMessage.
Show the 32 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a thread
/v1/threads/{threadId}threads.get- Permission
- Inbox view
- Rate limit
- 12,000 requests a minute per API key
Returns one thread. Read its messages with GET /v1/threads/{threadId}/messages.
An email thread also carries scheduledMessages: the replies and forwards queued on it that have not sent yet, a reply that waits for a member's approval included. POST /v1/scheduled-messages/{scheduledMessageId}/cancel withdraws one. accountId and accountName name the account whose touch the thread is, else the account where the thread's contact is a stakeholder. An email thread of an account touch also carries replyTouchId, the open reply touch that answers it.
A Facebook thread carries historyStartsAt while the account's history is locked.
Errors:
404 not_found: the id is malformed, or no thread in this workspace has it.
Requires Inbox view.
curl -X GET "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Thread.
Show the 34 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a thread
/v1/threads/{threadId}threads.update- Permission
- Inbox edit
- Rate limit
- 4,800 requests a minute per API key
Changes a thread's state and keeps every field you leave out. The body is a JSON object with at least one of these fields:
isRead,isArchived,isSaved: true or false. Archiving an email thread archives every reply in it.interest: the label, one ofinterested,not_interested,negative,automated,unclassified,unsubscribe,objection,wrong_contact,referralorout_of_office.not_interestedreads back asnegative. A LinkedIn thread does not takeautomated.reminderAt: when to remind you, as an ISO 8601 instant. Null clears the reminder.personId: links the thread's contact to this person in Accounts and replaces any earlier link. A merged person links as the person it merged into.
On an email thread, an interest that says a person wrote back (any value but automated, out_of_office and unclassified) clears the reply's auto-reply marks. Kenso then treats it as a human reply and stops the contact's sequence.
personId needs the unified_inbox feature on the workspace and Accounts edit. Kenso checks the link before it writes any field and writes the link last, so a refused field leaves no link.
The response is the updated thread. It carries hasDraft and draftAuthor, and leaves out accountId, replyTouchId and scheduledMessages.
A Facebook thread takes isRead only.
Errors:
400 validation_failed: the body is not an object, has no field, names an unknown field, or holds a value of the wrong type or an unknown value.403 permission_denied: the body setspersonIdand the caller lacks Accounts edit.404 not_found: the thread is not in this workspace, or the body setspersonIdand the person is not in the workspace, was deleted, or theunified_inboxfeature is off.422 unprocessable: the body setspersonIdand the thread has no contact.
Requires Inbox edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the Idempotent-Replayed: true header, and Kenso does not run the action twice. The same key with a different request answers 422 idempotency_key_reused. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get 503 service_unavailable with Retry-After. Retry it with the same key. Kenso does not store a 5xx response, so a retry after one runs the action again. |
Request body
application/json, required.
| Field | Type | Required | Description |
|---|---|---|---|
isRead | boolean | optional | True marks the thread read, false unread. Null is refused. |
isArchived | boolean | optional | True archives the thread, false moves it back to the inbox. Archiving an email thread archives every reply in it. Null is refused. |
isSaved | boolean | optional | True saves the thread, false takes it out of the saved threads. Null is refused. |
interest | string | optional | The label: interested, not_interested, negative, automated, unclassified, unsubscribe, objection, wrong_contact, referral or out_of_office. not_interested reads back as negative, and a LinkedIn thread does not take automated. On an email thread, any value but automated, out_of_office and unclassified marks the reply as written by a person and stops the contact's sequence. Null is refused. |
reminderAt | string (date-time) | optional | When to remind you, as an ISO 8601 instant. Null clears the reminder. |
personId | integer (int64) | optional | Links the thread's contact to this person in Accounts, replacing any earlier link. A merged person links as the person it merged into. Needs the unified_inbox feature on the workspace and Accounts edit. Null is refused. |
curl -X PATCH "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"isRead": true,
"isArchived": false,
"isSaved": true,
"interest": "interested",
"reminderAt": "2026-10-15T18:30:00Z",
"personId": 77310
}'Response 200
data is a Thread.
Show the 34 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Count threads by tab
/v1/threads/countsthreads.counts- Permission
- Inbox view
- Rate limit
- 12,000 requests a minute per API key
Returns thread counts for the inbox tabs, email and LinkedIn together. Use it for tab badges and to know when to reload the thread list.
Name the tab with status, folder, isArchived and isSaved, the same way GET /v1/threads takes them. allCount is the number of threads that list returns for the tab. accountsCount and campaignsCount split the tab into threads linked to an account and threads from a campaign, and campaigns lists every campaign with a thread in the inbox. toReplyCount, unreadCount, latestMessageAt and inboxChangedAt ignore the tab. An email thread counts once however many messages it has, and a LinkedIn conversation is one thread.
To keep a view current, poll this call and reload the list when inboxChangedAt changes. It moves when a reply arrives, a late one included, and when a reply changes tab, for example when Kenso classifies it.
With groupBy=person the counts count people instead of threads, each the number of rows GET /v1/threads?groupBy=person lists for the tab. A person counts under the campaign or account of their thread in the tab. On a tab that lists your own sends (folder=sent or folder=all), allCount, accountsCount, campaignsCount and campaigns[].threadCount keep counting threads, because that grouped list's total can be capped. toReplyCount and unreadCount count people on every tab.
facebookUnreadCount counts Facebook threads with an unread inbound message, and is omitted when Facebook outreach is off for the workspace.
Errors:
400 validation_failed:status,folderorgroupByis not a known value.
Requires Inbox view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
status | query | string | optional | The inbox tab to count: to_reply, other, automated_reply, not_interested or human_reply. Omit it to count threads of every status. |
folder | query | string | optional | Which messages to count: inbox (messages received), sent (messages sent) or all (both). Default inbox. |
isArchived | query | boolean | optional | Filters by archive state: true counts only archived threads and false only threads not archived. Kenso counts both when it is omitted or when status=human_reply. |
isSaved | query | boolean | optional | Filters by saved state: true counts only saved threads and false only threads not saved. Kenso counts both when it is omitted or when status=human_reply. |
groupBy | query | string | optional | Set to person to count distinct people instead of threads, one per row of GET /v1/threads?groupBy=person. Omit it to count threads, and any other value answers 400 validation_failed. |
curl -X GET "https://api.ken.so/v1/threads/counts" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a ThreadCounts.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Mark all threads read
/v1/threads/mark-all-readthreads.mark-all-read- Permission
- Inbox edit
- Rate limit
- 480 requests a minute per API key
Marks every unread thread in the inbox as read and returns how many changed. It covers every unread inbound email message and every unread LinkedIn conversation in one pass, and every unread WhatsApp chat when WhatsApp is on for the workspace, and every unread allowed Facebook chat when Facebook outreach is on. The call takes no body.
A repeat call is safe and returns updatedCount: 0.
Requires Inbox edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the Idempotent-Replayed: true header, and Kenso does not run the action twice. The same key with a different request answers 422 idempotency_key_reused. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get 503 service_unavailable with Retry-After. Retry it with the same key. Kenso does not store a 5xx response, so a retry after one runs the action again. |
curl -X POST "https://api.ken.so/v1/threads/mark-all-read" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a MarkAllThreadsRead.
Show the 1 response field and an example
The fields and an example are also on this endpoint's Markdown page.
Update many threads
/v1/threads/bulk-updatethreads.bulk-update- Permission
- Inbox edit
- Rate limit
- 480 requests a minute per API key
Applies the same change to up to 1,000 threads. The body is a JSON object with ids, a list of thr_ ids, and the fields to change, under the same rules as PATCH /v1/threads/{threadId}. personId is not allowed here: link people one thread at a time.
Kenso updates each thread on its own, so one failure does not stop the others. The response lists the ids that changed in succeeded and the rest in failed, each with an error code of not_found or validation_failed. A field with a bad value fails every id with validation_failed.
Errors:
400 validation_failed:idsis missing, empty, longer than 1,000 or holds a value that is not a string, the body has no field to change, or it setspersonId.
Requires Inbox edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the Idempotent-Replayed: true header, and Kenso does not run the action twice. The same key with a different request answers 422 idempotency_key_reused. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get 503 service_unavailable with Retry-After. Retry it with the same key. Kenso does not store a 5xx response, so a retry after one runs the action again. |
Request body
application/json, required.
| Field | Type | Required | Description |
|---|---|---|---|
isRead | boolean | optional | True marks the thread read, false unread. Null is refused. |
isArchived | boolean | optional | True archives the thread, false moves it back to the inbox. Archiving an email thread archives every reply in it. Null is refused. |
isSaved | boolean | optional | True saves the thread, false takes it out of the saved threads. Null is refused. |
interest | string | optional | The label: interested, not_interested, negative, automated, unclassified, unsubscribe, objection, wrong_contact, referral or out_of_office. not_interested reads back as negative, and a LinkedIn thread does not take automated. On an email thread, any value but automated, out_of_office and unclassified marks the reply as written by a person and stops the contact's sequence. Null is refused. |
reminderAt | string (date-time) | optional | When to remind you, as an ISO 8601 instant. Null clears the reminder. |
ids | array of string | required | Required. From 1 to 1,000 thr_ thread ids. |
curl -X POST "https://api.ken.so/v1/threads/bulk-update" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20",
"thr_ZW1haWw6NDAyMzE3LjFAZXhhbXBsZS5jb20"
],
"isRead": true,
"isArchived": true,
"isSaved": false,
"interest": "out_of_office"
}'Response 200
data is a ThreadBulkResult.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List a thread's messages
/v1/threads/{threadId}/messagesthreads.list-messages- Permission
- Inbox view
- Rate limit
- 12,000 requests a minute per API key
Returns every message in a thread, oldest first, in one page. Each item carries kind: message for an email or chat message.
With includeEvents=true a LinkedIn thread also lists the connection note sent with the invitation (connection_note, outbound) and the moment the person accepted (connection_accepted, inbound, with an empty body), in time order. An event comes before a message sent at the same instant. An email thread ignores includeEvents. When Kenso cannot read the events, it returns the messages alone.
Errors:
404 not_found: the id is malformed, or no thread in this workspace has it.
Requires Inbox view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
includeEvents | query | boolean | optional | True to add a LinkedIn thread's connection events to its messages. |
curl -X GET "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20/messages" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of ThreadMessage. Each item has these fields. The response also carries pagination.
Show the 32 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Send a reply in a thread
/v1/threads/{threadId}/messagesthreads.create-message- Permission
- Inbox edit and the
replypermission - Rate limit
- 10 requests a minute per API key
Sends a reply on an email thread or a LinkedIn conversation. body is required. Kenso records each reply with its caller: a person, an API key, or an agent (any caller that sends the header X-Ken-Actor: agent). Kenso records the send only after the email provider or LinkedIn accepts it.
On an email thread senderEmailId, the inbox that sends, is required. The reply goes to the thread's sender unless you name to, or set replyAll: true to reach the sender, To and Cc without the sending inbox. cc and bcc add recipients. Each recipient is one bare email address. attachmentIds takes att_ ids uploaded against the thread's newest message. contentType is html (the default) or text. A reply goes out on the thread's subject, so a send ignores subject.
Kenso queues an email reply for an undo window of delaySeconds, 60 (the default) or 300 seconds. The 201 response carries the queued reply's scheduledMessageId, and POST /v1/scheduled-messages/{scheduledMessageId}/cancel stops it until the window ends. A pause or block that starts during the window refuses the reply at send time, and its scheduled message ends failed. With archiveAfterSend: true Kenso archives the thread once the reply sends.
An email reply to a contact who is do-not-contact, blocklisted or unsubscribed returns 409 invalid_state with a confirmSuppressed detail whose code is the reason. Kenso sends it only when you repeat the request with confirmSuppressed: true, and the reply then carries a suppressed_contact_overridden warning.
Some email replies wait for approval and return 202 instead of sending:
- When the workspace requires external approval for replies, the response has
status: held_for_client_approvaland theclientApprovalItemIdthat holds the reply. - A reply an agent or API key sends from its own member's mailbox returns the scheduled message with
status: awaiting_approvalandapproverMemberId. It waits in that member'sGET /v1/approvalsuntil they approve it in person. From another member's own mailbox, or with theaccountsfeature off, it is403 forbidden. - A reply a teammate writes in person from the own inbox of a member with the Client role, while the
accounts_sendfeature is on, waits the same way in that member'sGET /v1/approvals.
A waiting reply with archiveAfterSend archives the thread only when the approved reply sends.
An agent's or API key's reply from an inbox a member paused or Kenso blocked from sending returns 409 invalid_state with detail code inbox_paused or inbox_send_blocked and a fix. A block also carries nextAllowedAt, when it ends, and a Retry-After header. A pause has no known end.
An email reply takes an optional Idempotency-Key of at most 200 characters, unique in the workspace. The key is bound to the thread, the inbox and the body, and to to, cc, bcc, replyAll, contentType and attachmentIds when you send them. A retry returns the reply the key queued, or the 202 it was held with, and queues nothing. A refused reply frees its key.
On a LinkedIn thread Kenso sends plain text at once from the LinkedIn account that holds the conversation, and ignores delaySeconds. A LinkedIn reply that names an email-only field (to, cc, bcc, replyAll, attachmentIds or contentType) gets 400 validation_failed on that field and sends nothing. Kenso always refuses a LinkedIn reply to a suppressed contact. A LinkedIn Idempotency-Key is bound to its thread and text. Without a key, the same text sent again in the thread more than 5 minutes later sends again.
A LinkedIn reply an agent or API key sends through an account another member connected waits for that member. The 202 response has status: awaiting_approval, channel: linkedin, the approvalId (type reply.linkedin) and approverMemberId. It sends once that member approves it in person in GET /v1/approvals. A retry with the same key, or the same text without one, returns the same waiting reply. With the accounts feature off for that member, or on an account no member connected, it is 403 forbidden. A person's own reply in the Kenso app, and the account owner's own agent or API key, send at once.
On an Instagram thread Kenso sends at once from the chat's account: text of at most 1,000 characters and up to 3 images uploaded with purpose=instagram (their att_ ids in attachmentIds; then body may be blank). It refuses email-only fields, senderEmailId, imageIds and voiceNoteId with 400, a suppressed person, and an agent's or API key's reply through an account another member connected (403 forbidden). A paused, resting, limited or disconnected account answers 409 invalid_state, with nextAllowedAt and Retry-After when known. Its 503 may mean the message went out: retry with the same body, images and Idempotency-Key (or again none), never under a new key.
A Facebook reply sends body (optional when it has images or a voice note, at most 2,000 characters), then each of imageIds as its own message, then voiceNoteId, through the Facebook account that holds the chat. It is recorded only after Facebook confirms each part. A part that fails stops the rest: 409 invalid_state says how many were sent. When Kenso cannot tell whether a part was sent, the reply is 503 service_unavailable and is never sent again under the same Idempotency-Key: read the thread first. An agent or API key replies only through a Facebook account its own member connected (else 403). Email-only fields are 400 on a Facebook thread.
A WhatsApp reply sends at once from the chat's account: text of at most 4,096 characters, up to 6 mediaIds (then body may be blank), or a voice note of body with voiceProvider and voiceId. It follows the LinkedIn rules above for email-only fields, suppression, keys and an agent's reply through another member's account (approval type reply.whatsapp). WhatsApp's send limits answer 409 invalid_state with nextAllowedAt and Retry-After.
Errors:
400 validation_failed:bodyis missing,delaySecondsis not 60 or 300,senderEmailIdis missing on an email thread, a recipient is not an email address,contentTypeis nothtmlortext,attachmentIdsnames a file of another message, a LinkedIn reply names an email-only field, theIdempotency-Keyis longer than 200 characters, or the provider rejected the message.403 forbidden: the caller may not send from this inbox or LinkedIn account.404 not_found: the id is malformed, or no thread in this workspace has it.409 invalid_state: the contact is suppressed, the sending inbox is disconnected, paused or blocked, or the LinkedIn account reached its daily limit.409 in_progress: an email reply under this key is still being queued. Retry afternextAllowedAt, also sent asRetry-After.409 outcome_unknown: Kenso cannot tell whether the email reply under this key was queued, and never queues it again. Read the thread before you reply under a new key.409 reply_not_sent: the email reply under this key failed or was cancelled and never went out. Send it again under a new key if you still want it.422 idempotency_key_reused: the key was used for another request or another thread. This operation answered409for it before 2026-11-17.503 service_unavailable: the provider could not take the message, or Kenso could not save the reply for approval. Retry later.
Requires Inbox edit and the reply permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. Kenso records the key with what the request did, so a repeat of the same request with the same key does not do it twice: the description says what a repeat returns. The same key with a different request answers 422 idempotency_key_reused. This operation answered 409 for it before 2026-11-17: branch on the code, not the status. Keys are per workspace and at most 200 characters long. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
body | string | required | Required. The reply text: HTML on an email thread unless contentType is text, plain text on a LinkedIn thread. |
subject | string | optional | Drafts only. A reply goes out on the thread's own subject, so a send ignores this field. Set a draft's subject with PUT /v1/threads/{threadId}/draft. |
senderEmailId | integer (int32) | optional | Email only, and required there: the id of the inbox that sends the reply. |
delaySeconds | integer (int32) | optional | Email only: the undo window before the reply sends, 60 or 300 seconds. Omitted, it is 60. Cancel the queued reply with POST /v1/scheduled-messages/{scheduledMessageId}/cancel and the response's scheduledMessageId. A LinkedIn reply sends at once and ignores it. |
confirmSuppressed | boolean | optional | Email only: send even though the contact is do-not-contact, blocklisted or unsubscribed. Set it only after a person confirmed a 409 invalid_state that names a suppressed contact. |
archiveAfterSend | boolean | optional | Email only: archive the thread once the reply sends. A reply that waits for approval archives the thread when the approved reply sends, never while it waits, and a reply that never sends leaves the thread as it was. |
to | array of ThreadAddressRequest | optional | Email only: who the reply goes to, each one bare email address. Omitted, the reply goes to the thread's sender, or to everyone on the thread with replyAll. A LinkedIn thread refuses it. |
cc | array of ThreadAddressRequest | optional | Email only: Cc recipients, each one bare email address. A LinkedIn thread refuses it. |
bcc | array of ThreadAddressRequest | optional | Email only: Bcc recipients, each one bare email address. A LinkedIn thread refuses it. |
replyAll | boolean | optional | Email only: without to, reply to the thread's sender, To and Cc, minus the sending inbox. A LinkedIn thread refuses it. |
attachmentIds | array of string | optional | Email: att_ ids of files uploaded with POST /v1/attachments against the thread's newest message. Instagram: up to 3 att_ ids of images uploaded with purpose=instagram. A LinkedIn thread refuses it. |
contentType | string | optional | Email only: html (the default) or text. A LinkedIn thread refuses it. |
imageIds | array of string | optional | Facebook only: images uploaded with POST /v1/threads/{threadId}/images, sent after the text, one message each. At most 4. Any other thread refuses it with 400 validation_failed; an Instagram reply sends its images in attachmentIds. |
voiceNoteId | integer (int64) | optional | Facebook only: a ready voice note made with POST /v1/threads/{threadId}/voice-notes, sent last. Any other thread refuses it with 400 validation_failed. |
mediaIds | array of integer (int64) | optional | WhatsApp threads only: up to 6 distinct message_media image ids to send with the text. With images, body may be blank. |
voiceProvider | string | optional | WhatsApp threads only: deepgram or elevenlabs. With voiceId, the reply goes out as a voice note that speaks body (at most 900 characters) instead of text. |
voiceId | string | optional | WhatsApp threads only: the voice of the voice note, at most 200 characters. Requires voiceProvider. |
curl -X POST "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20/messages" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"body": "<p>Hi Amanda,</p><p>Thursday works. Does 2pm Central suit you? I will send an invite.</p><p>Alex</p>",
"senderEmailId": 5530,
"delaySeconds": 60,
"confirmSuppressed": false,
"archiveAfterSend": false,
"replyAll": false,
"contentType": "html"
}'Response 201
Also answers 202. data is a ThreadMessage.
Show the 32 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a thread's draft
/v1/threads/{threadId}/draftthreads.get-draft- Permission
- Inbox view
- Rate limit
- 12,000 requests a minute per API key
Returns the reply draft saved on a thread. authorSource says who last wrote it: user for a person in the Kenso app, agent for an agent or API key. When an agent wrote the reply in the contact's language, the draft also carries mirror, the same reply in the reader's language.
A Facebook thread has no draft: 404.
Errors:
404 not_found: the id is malformed, no thread in this workspace has it, or the thread has no draft.
Requires Inbox view.
curl -X GET "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20/draft" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a ThreadDraft.
Show the 7 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Replace a thread's draft
/v1/threads/{threadId}/draftthreads.replace-draft- Permission
- Inbox edit
- Rate limit
- 4,800 requests a minute per API key
Saves the reply draft on a thread in place of the one there. Send body and, on an email thread, an optional subject. An empty or missing body deletes the draft and returns 204 with no body.
Only a person signed in to the Kenso app writes as the draft's author, user. An agent (any caller that sends the header X-Ken-Actor: agent) or an API key writes as agent, and never overwrites or deletes a person's draft: the response is then the person's draft, unchanged.
On an email thread, a person who saves a reply Ken wrote into their composer sends authorSource agent, and the model that wrote it in the header X-Ken-Generator. The draft is theirs, as their own save is (authorSource stays user, so no agent write replaces it), and it records the text as Ken's, so their send or discard of it is measured against that text.
On an email thread, saving or clearing a draft also stops any reply or follow-up that Ken holds for the thread, so Ken does not send on top of it.
A Facebook thread has no draft: 404.
Errors:
404 not_found: the id is malformed, or no thread in this workspace has it.
Requires Inbox edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
subject | string | optional | Email only: the draft's subject. A LinkedIn thread ignores it. |
body | string | optional | The draft's text. Empty or omitted deletes the draft. |
authorSource | string | optional | Email only, optional: agent when a person saves a reply Ken wrote into their composer. The draft stays the person's (the response's authorSource is user) and records the text as Ken's, with the model the X-Ken-Generator header names. Ignored for any caller that is not a person signed in to the Kenso app, and for any other value. |
curl -X PUT "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20/draft" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"subject": "Re: Onboarding new engineers at Northwind Labs",
"body": "<p>Hi Amanda,</p><p>Thursday works. Does 2pm Central suit you? I will send an invite.</p><p>Alex</p>"
}'Response 200
data is a ThreadDraft.
Show the 7 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a thread's draft
/v1/threads/{threadId}/draftthreads.delete-draft- Permission
- Inbox edit
- Rate limit
- 4,800 requests a minute per API key
Deletes the reply draft saved on a thread. Returns 204 with no body, also when the thread has no draft. Unlike an empty PUT /v1/threads/{threadId}/draft, this deletes a person's draft whoever calls.
A Facebook thread has no draft: 404.
Errors:
404 not_found: the id is malformed, or no thread in this workspace has it.
Requires Inbox edit.
curl -X DELETE "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20/draft" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentUpload an image for a Facebook reply
/v1/threads/{threadId}/imagesthreads.create-image- Permission
- Inbox edit and the
replypermission - Rate limit
- 30 requests a minute per API key
Facebook threads only (any other thread is 404). Multipart field file: a jpg, png or webp image up to 8 MB, checked by its content. A thread holds at most 4 images until the next reply sends them; an image not sent within 24 hours is dropped. Pass the returned id in imageIds on POST /v1/threads/{threadId}/messages. Requires Inbox edit and the reply permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
threadId | path | string | required | The Facebook thread's thr_ id. |
Request body
multipart/form-data, optional.
| Field | Type | Required | Description |
|---|---|---|---|
file | string (binary) | optional | The image, as a multipart file part. |
curl -X POST "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20/images" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-F "file=@./file"Response 201
data is a ThreadImage.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Forward an email thread
/v1/threads/{threadId}/forwardthreads.forward- Permission
- Inbox edit and the
replyandexportpermissions - Rate limit
- 10 requests a minute per API key
Forwards an email thread's newest message to new recipients. Email threads only. body is required, and to is required unless replyAll is true. Each recipient is one bare email address.
senderEmailId, the inbox that sends, is required unless replyAll is true. Kenso queues the forward for an undo window of delaySeconds, 60 (the default) or 300 seconds, and returns 200 with the scheduled message. POST /v1/scheduled-messages/{scheduledMessageId}/cancel stops it until the window ends. attachmentIds takes att_ ids uploaded against the thread's newest message. With archiveAfterSend: true Kenso archives the thread once the forward sends.
A forward that goes back into the thread is refused when the contact is suppressed or when the workspace holds replies for external approval. A forward goes back into the thread when it uses replyAll without to, or names the contact or another participant as a recipient. No setting overrides this refusal: send a reply instead.
A forward an agent or API key sends from its own member's mailbox does not send yet. It returns 202 with the scheduled message in status: awaiting_approval and approverMemberId, and waits in that member's GET /v1/approvals until they approve it in person. From another member's own mailbox, or with the accounts feature off, it is 403 forbidden.
The built-in Client role has no export permission, so its members can reply but not forward.
Errors:
400 validation_failed:bodyor a required field is missing, a recipient is not an email address,delaySecondsis not 60 or 300,contentTypeis nothtmlortext,attachmentIdsnames a file of another message, the thread is a LinkedIn thread, or the provider rejected the forward.403 forbidden: the caller may not send from this inbox.404 not_found: the id is malformed, or no thread in this workspace has it.409 invalid_state: the sending inbox is disconnected, or the forward goes back into the thread while the contact is suppressed or replies need external approval. The detail code is the suppression reason orclient_approval_required.503 service_unavailable: Kenso could not queue the forward. Retry later.
Requires Inbox edit and the reply and export permissions.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the Idempotent-Replayed: true header, and Kenso does not run the action twice. The same key with a different request answers 422 idempotency_key_reused. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get 503 service_unavailable with Retry-After. Retry it with the same key. Kenso does not store a 4xx or 5xx response, so a retry after one runs the action again. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
body | string | required | Required. Your note above the forwarded message: HTML unless contentType is text. |
senderEmailId | integer (int32) | optional | The id of the inbox that sends the forward. Required unless replyAll is true, when Kenso picks the inbox from the thread. |
contentType | string | optional | The body's format: html (the default) or text. |
replyAll | boolean | optional | Without to, true sends the forward to the thread's sender, To and Cc, minus the sending inbox. A forward that goes back into the thread is refused when the contact is suppressed or replies need external approval. |
injectPreviousEmailBody | boolean | optional | Quote the forwarded message under your note. Omitted or true quotes it, false leaves it out. |
replyTemplateId | integer (int32) | optional | The id of the reply template the note came from. Kenso stores it with the forward, and it does not change what is sent. |
useDedicatedIps | boolean | optional | Kenso stores it with the forward, and it does not change how the forward is sent. |
to | array of ThreadAddressRequest | optional | Who the forward goes to, each one bare email address. Required unless replyAll is true. |
cc | array of ThreadAddressRequest | optional | Cc recipients, each one bare email address. |
bcc | array of ThreadAddressRequest | optional | Bcc recipients, each one bare email address. |
delaySeconds | integer (int32) | optional | The undo window before the forward sends, 60 or 300 seconds. Omitted, it is 60. |
archiveAfterSend | boolean | optional | Archive the thread once the forward sends. |
attachmentIds | array of string | optional | The att_ ids of files uploaded with POST /v1/attachments against the thread's newest message. |
curl -X POST "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20/forward" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"body": "<p>Jordan, Amanda wants a call on Thursday afternoon. Can you take it?</p>",
"senderEmailId": 5530,
"contentType": "html",
"replyAll": false,
"injectPreviousEmailBody": true,
"useDedicatedIps": false,
"to": [
{
"name": "Jordan Patel",
"address": "[email protected]"
}
],
"delaySeconds": 60,
"archiveAfterSend": false
}'Response 200
Also answers 202. data is a ScheduledMessage.
Show the 14 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Inbox:Reply templatesScheduled messagesAttachmentsInboxesInbox importsLinkedIn accountsWhatsApp accountsWhatsApp settingsAll resources