Skip to Content
Inbox

Threads

Inbox threads across email and LinkedIn: count and list them, read messages, reply, forward, update in bulk and keep drafts.

Inbox14 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
threadIdpathstringrequiredThe thread's thr_ id.

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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

GET/v1/threadsthreads.list
Permission
Inbox view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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: limit is outside 1 to 100, cursor is invalid, or channel, interest, source, sort, groupBy or personKey is not a known value.

Requires Inbox view.

Parameters

NameInTypeRequiredDescription
channelquerystringoptionalThe 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.
campaignIdqueryinteger (int64)optionalOnly this campaign's threads.
inboxIdqueryinteger (int64)optionalOnly 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.
contactIdqueryinteger (int64)optionalOnly 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.
interestquerystringoptionalOnly 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.
statusquerystringoptionalThe inbox tab: to_reply, other, automated_reply, not_interested or human_reply. Kenso applies it before paging. Any other value is ignored.
folderquerystringoptionalThe folder: inbox (replies you received), sent (messages you sent) or all (both). Omitted, it is inbox.
sourcequerystringoptionalNarrows 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.
sortquerystringoptionalThe 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.
groupByquerystringoptionalSet 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.
personKeyquerystringoptionalA 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.
isReadquerybooleanoptionalTrue lists read threads, false unread ones. Omitted lists both.
isArchivedquerybooleanoptionalTrue lists archived threads, false the rest. Omitted lists both.
isSavedquerybooleanoptionalTrue lists saved threads, false the rest. Omitted lists both.
hasReminderquerybooleanoptionalTrue 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.
tagIdsqueryarray of integer (int64)optionalOnly threads with any of these tag ids. Repeat the parameter for each id.
qquerystringoptionalSearch 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.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
limitqueryinteger (int32)optionalThreads per page, from 1 to 100. Omitted, it is 50.
Request
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

POST/v1/threadsthreads.create
Permission
Inbox edit and the reply permission
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)
Needs the agent_send feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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 the Idempotency-Key header 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.refusal has code FREE_PLAN_SENDING_NEEDS_PLAN and remedy Upgrade: 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 the Retry-After header, 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 answered 409 for it before 2026-11-17.
  • 422 guardrail_violation: the send breaks one of the workspace's contact limits. With agent_contact_limit_override on for the workspace, an agent's overrideContactLimits: true sends 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

NameInTypeRequiredDescription
Idempotency-KeyheaderstringrequiredRequired. 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.

FieldTypeRequiredDescription
senderInboxIdinteger (int64)requiredRequired. The id of one of the workspace's shared cold inboxes, from GET /v1/inboxes. A member's own mailbox is refused.
toCreateThreadRecipientrequiredRequired. The one person the email goes to.
subjectstringrequiredRequired. The email's subject.
bodystringrequiredRequired. The email body as HTML.
overrideContactLimitsbooleanoptionaltrue 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.
Request
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

GET/v1/threads/{threadId}threads.get
Permission
Inbox view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

PATCH/v1/threads/{threadId}threads.update
Permission
Inbox edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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 of interested, not_interested, negative, automated, unclassified, unsubscribe, objection, wrong_contact, referral or out_of_office. not_interested reads back as negative. A LinkedIn thread does not take automated.
  • 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 sets personId and the caller lacks Accounts edit.
  • 404 not_found: the thread is not in this workspace, or the body sets personId and the person is not in the workspace, was deleted, or the unified_inbox feature is off.
  • 422 unprocessable: the body sets personId and the thread has no contact.

Requires Inbox edit.

Parameters

NameInTypeRequiredDescription
Idempotency-KeyheaderstringoptionalA 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.

FieldTypeRequiredDescription
isReadbooleanoptionalTrue marks the thread read, false unread. Null is refused.
isArchivedbooleanoptionalTrue archives the thread, false moves it back to the inbox. Archiving an email thread archives every reply in it. Null is refused.
isSavedbooleanoptionalTrue saves the thread, false takes it out of the saved threads. Null is refused.
intereststringoptionalThe 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.
reminderAtstring (date-time)optionalWhen to remind you, as an ISO 8601 instant. Null clears the reminder.
personIdinteger (int64)optionalLinks 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.
Request
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

GET/v1/threads/countsthreads.counts
Permission
Inbox view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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, folder or groupBy is not a known value.

Requires Inbox view.

Parameters

NameInTypeRequiredDescription
statusquerystringoptionalThe inbox tab to count: to_reply, other, automated_reply, not_interested or human_reply. Omit it to count threads of every status.
folderquerystringoptionalWhich messages to count: inbox (messages received), sent (messages sent) or all (both). Default inbox.
isArchivedquerybooleanoptionalFilters 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.
isSavedquerybooleanoptionalFilters 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.
groupByquerystringoptionalSet 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.
Request
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

POST/v1/threads/mark-all-readthreads.mark-all-read
Permission
Inbox edit
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
Idempotency-KeyheaderstringoptionalA 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
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

POST/v1/threads/bulk-updatethreads.bulk-update
Permission
Inbox edit
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

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: ids is missing, empty, longer than 1,000 or holds a value that is not a string, the body has no field to change, or it sets personId.

Requires Inbox edit.

Parameters

NameInTypeRequiredDescription
Idempotency-KeyheaderstringoptionalA 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.

FieldTypeRequiredDescription
isReadbooleanoptionalTrue marks the thread read, false unread. Null is refused.
isArchivedbooleanoptionalTrue archives the thread, false moves it back to the inbox. Archiving an email thread archives every reply in it. Null is refused.
isSavedbooleanoptionalTrue saves the thread, false takes it out of the saved threads. Null is refused.
intereststringoptionalThe 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.
reminderAtstring (date-time)optionalWhen to remind you, as an ISO 8601 instant. Null clears the reminder.
idsarray of stringrequiredRequired. From 1 to 1,000 thr_ thread ids.
Request
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

GET/v1/threads/{threadId}/messagesthreads.list-messages
Permission
Inbox view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
includeEventsquerybooleanoptionalTrue to add a LinkedIn thread's connection events to its messages.
Request
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

POST/v1/threads/{threadId}/messagesthreads.create-message
Permission
Inbox edit and the reply permission
Rate limit
10 requests a minute per API key

Try it on developer.ken.so

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_approval and the clientApprovalItemId that holds the reply.
  • A reply an agent or API key sends from its own member's mailbox returns the scheduled message with status: awaiting_approval and approverMemberId. It 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.
  • A reply a teammate writes in person from the own inbox of a member with the Client role, while the accounts_send feature is on, waits the same way in that member's GET /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: body is missing, delaySeconds is not 60 or 300, senderEmailId is missing on an email thread, a recipient is not an email address, contentType is not html or text, attachmentIds names a file of another message, a LinkedIn reply names an email-only field, the Idempotency-Key is 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 after nextAllowedAt, also sent as Retry-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 answered 409 for 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

NameInTypeRequiredDescription
Idempotency-KeyheaderstringoptionalA 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.

FieldTypeRequiredDescription
bodystringrequiredRequired. The reply text: HTML on an email thread unless contentType is text, plain text on a LinkedIn thread.
subjectstringoptionalDrafts 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.
senderEmailIdinteger (int32)optionalEmail only, and required there: the id of the inbox that sends the reply.
delaySecondsinteger (int32)optionalEmail 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.
confirmSuppressedbooleanoptionalEmail 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.
archiveAfterSendbooleanoptionalEmail 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.
toarray of ThreadAddressRequestoptionalEmail 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.
ccarray of ThreadAddressRequestoptionalEmail only: Cc recipients, each one bare email address. A LinkedIn thread refuses it.
bccarray of ThreadAddressRequestoptionalEmail only: Bcc recipients, each one bare email address. A LinkedIn thread refuses it.
replyAllbooleanoptionalEmail only: without to, reply to the thread's sender, To and Cc, minus the sending inbox. A LinkedIn thread refuses it.
attachmentIdsarray of stringoptionalEmail: 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.
contentTypestringoptionalEmail only: html (the default) or text. A LinkedIn thread refuses it.
imageIdsarray of stringoptionalFacebook 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.
voiceNoteIdinteger (int64)optionalFacebook only: a ready voice note made with POST /v1/threads/{threadId}/voice-notes, sent last. Any other thread refuses it with 400 validation_failed.
mediaIdsarray of integer (int64)optionalWhatsApp threads only: up to 6 distinct message_media image ids to send with the text. With images, body may be blank.
voiceProviderstringoptionalWhatsApp 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.
voiceIdstringoptionalWhatsApp threads only: the voice of the voice note, at most 200 characters. Requires voiceProvider.
Request
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

GET/v1/threads/{threadId}/draftthreads.get-draft
Permission
Inbox view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

PUT/v1/threads/{threadId}/draftthreads.replace-draft
Permission
Inbox edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

FieldTypeRequiredDescription
subjectstringoptionalEmail only: the draft's subject. A LinkedIn thread ignores it.
bodystringoptionalThe draft's text. Empty or omitted deletes the draft.
authorSourcestringoptionalEmail 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.
Request
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

DELETE/v1/threads/{threadId}/draftthreads.delete-draft
Permission
Inbox edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Upload an image for a Facebook reply

POST/v1/threads/{threadId}/imagesthreads.create-image
Permission
Inbox edit and the reply permission
Rate limit
30 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
threadIdpathstringrequiredThe Facebook thread's thr_ id.

Request body

multipart/form-data, optional.

FieldTypeRequiredDescription
filestring (binary)optionalThe image, as a multipart file part.
Request
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

POST/v1/threads/{threadId}/forwardthreads.forward
Permission
Inbox edit and the reply and export permissions
Rate limit
10 requests a minute per API key

Try it on developer.ken.so

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: body or a required field is missing, a recipient is not an email address, delaySeconds is not 60 or 300, contentType is not html or text, attachmentIds names 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 or client_approval_required.
  • 503 service_unavailable: Kenso could not queue the forward. Retry later.

Requires Inbox edit and the reply and export permissions.

Parameters

NameInTypeRequiredDescription
Idempotency-KeyheaderstringoptionalA 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.

FieldTypeRequiredDescription
bodystringrequiredRequired. Your note above the forwarded message: HTML unless contentType is text.
senderEmailIdinteger (int32)optionalThe id of the inbox that sends the forward. Required unless replyAll is true, when Kenso picks the inbox from the thread.
contentTypestringoptionalThe body's format: html (the default) or text.
replyAllbooleanoptionalWithout 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.
injectPreviousEmailBodybooleanoptionalQuote the forwarded message under your note. Omitted or true quotes it, false leaves it out.
replyTemplateIdinteger (int32)optionalThe id of the reply template the note came from. Kenso stores it with the forward, and it does not change what is sent.
useDedicatedIpsbooleanoptionalKenso stores it with the forward, and it does not change how the forward is sent.
toarray of ThreadAddressRequestoptionalWho the forward goes to, each one bare email address. Required unless replyAll is true.
ccarray of ThreadAddressRequestoptionalCc recipients, each one bare email address.
bccarray of ThreadAddressRequestoptionalBcc recipients, each one bare email address.
delaySecondsinteger (int32)optionalThe undo window before the forward sends, 60 or 300 seconds. Omitted, it is 60.
archiveAfterSendbooleanoptionalArchive the thread once the forward sends.
attachmentIdsarray of stringoptionalThe att_ ids of files uploaded with POST /v1/attachments against the thread's newest message.
Request
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.


On this page