Kenso

Read and answer replies

This path answers the replies that wait on you, the inbox's To Reply tab. An email answer never goes out the moment you call: it waits 60 seconds, so you can still cancel it. When the campaign stops on reply (the default), the contact's reply already stopped its sequence.

Ken-Version: 2026-11-02
Markdown

Before you start

  • REST: export KENSO_API_KEY=<your key> and export KENSO_WORKSPACE_ID=<your workspace id> (see Authentication and Workspaces). The examples read ids with jq.
  • kenso: npm i -g kenso, printf '%s' "$KENSO_API_KEY" | kenso auth login --with-key, then kenso workspace use <your workspace id>. A command prints the response's data without the envelope, and a list prints one JSON row per line (CLI guide).
  • MCP: connect https://mcp.ken.so/mcp (setup). Each tool takes the workspace id as client_id and returns the same body as the REST call.
  • Each step keeps the ids the next steps need in shell variables ($CAMPAIGN_ID). The MCP examples show the same ids as numbers.

The path

List To Reply threads with GET /v1/threads, read one with GET /v1/threads/{threadId}/messages, answer with POST /v1/threads/{threadId}/messages, then archive it with PATCH /v1/threads/{threadId}. Each thread carries the inbox to answer from and the reply's interest.

  • GET /v1/events is the campaign event log (lead_replied, lead_interested). Its events carry a contact id but no thread id, so you cannot answer from them.
  • POST /v1/event-subscriptions and GET /v1/event-occurrences feed AI agents connected over MCP: a subscription belongs to one member and lasts at most an hour, and the occurrences log is off unless turned on for the workspace.
  • Webhooks push each reply to your server as it arrives (Receive webhooks). You still read and answer with the calls here.

1. Find the replies waiting on you

GET /v1/threads To Reply holds threads whose newest reply is worth answering (interest is interested, objection, wrong_contact or referral) and threads whose reminder is due. sort=oldest_waiting puts the longest wait first. The MCP's tab: "to_reply" sends the same status, folder and isArchived filters. This takes one thread; drop limit and page with cursor to work through them all.

REST
RESPONSE=$(curl -sS -X GET "https://api.ken.so/v1/threads?status=to_reply&folder=inbox&isArchived=false&channel=email&sort=oldest_waiting&limit=1" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID")
THREAD_ID=$(echo "$RESPONSE" | jq -r '.data[0].id')
INBOX_ID=$(echo "$RESPONSE" | jq -r '.data[0].inboxId')
kenso
RESPONSE=$(kenso threads list --status to_reply --folder inbox --no-is-archived --channel email --sort oldest_waiting --limit 1)
THREAD_ID=$(echo "$RESPONSE" | jq -r '.id')
INBOX_ID=$(echo "$RESPONSE" | jq -r '.inboxId')
MCP: threads
threads({
  "operation": "list",
  "tab": "to_reply",
  "channel": "email",
  "sort": "oldest_waiting",
  "limit": 1,
  "client_id": 4107
})

Keeps data[0].id as $THREAD_ID and data[0].inboxId as $INBOX_ID.

2. Read the conversation

GET /v1/threads/{threadId}/messages Messages come oldest first, so the last one is the contact's reply. extractedText is their own words, without the quoted history or signature. If hasDraft was true, Ken already drafted an answer: GET /v1/threads/{threadId}/draft returns its body.

REST
MESSAGE_ID=$(curl -sS -X GET "https://api.ken.so/v1/threads/$THREAD_ID/messages" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" | jq -r '.data[-1].id')
kenso
MESSAGE_ID=$(kenso threads list-messages --thread-id "$THREAD_ID" | jq -r '.[-1].id')
MCP: threads
threads({
  "operation": "list-messages",
  "thread_id": "thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20",
  "client_id": 4107
})

Keeps data[-1].id as $MESSAGE_ID.

3. Answer

POST /v1/threads/{threadId}/messages Send from the thread's own inbox (senderEmailId is its inboxId). The answer goes to the contact as Re: in the same thread. It is queued for 60 seconds (the MCP waits 300): data.scheduledMessageId cancels it with POST /v1/scheduled-messages/{scheduledMessageId}/cancel. To make a retry safe, add -H "Idempotency-Key: reply-$MESSAGE_ID" to the curl, or pass idempotency_key to the MCP.

REST
curl -sS -X POST "https://api.ken.so/v1/threads/$THREAD_ID/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>Happy to. Does Thursday at 2pm work for a 20-minute call?</p>",
  "senderEmailId": '"$INBOX_ID"'
}'
kenso
kenso threads create-message --thread-id "$THREAD_ID" --sender-email-id "$INBOX_ID" --body "<p>Happy to. Does Thursday at 2pm work for a 20-minute call?</p>"
MCP: threads
threads({
  "operation": "create-message",
  "thread_id": "thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20",
  "body": "<p>Happy to. Does Thursday at 2pm work for a 20-minute call?</p>",
  "sender_email_id": 4127,
  "idempotency_key": "reply-msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
  "client_id": 4107
})
Status
What happened
201
The answer is queued and sends once the 60 seconds pass.
202
Nothing is queued yet: the answer waits for an approval, such as a client's or the owner of a personal mailbox.
403
Your key lacks the reply permission, or the inbox is another member's personal mailbox. Answer from the campaign's inbox.
409 invalid_state
The contact is unsubscribed, blocklisted or marked do not contact. Send again with confirmSuppressed: true only once a person has confirmed.
409 idempotency_key_reused
The key was used for a different answer. Use a new key for a new answer.

4. File it away

PATCH /v1/threads/{threadId} Archive the thread so your next poll skips it. To Reply drops a thread by itself only once your answer has sent, after the 60 seconds, and a poll in between would answer twice. The contact's next reply puts the thread back on To Reply.

REST
curl -sS -X PATCH "https://api.ken.so/v1/threads/$THREAD_ID" \
  -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 '{
  "isArchived": true
}'
kenso
kenso threads update --thread-id "$THREAD_ID" --data '{"isArchived": true}'
MCP: threads
threads({
  "operation": "update",
  "thread_id": "thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20",
  "changes": {
    "is_archived": true
  },
  "client_id": 4107
})

Good to know

  • Leave out isArchived=false and the list holds archived threads too. q searches every thread and drops status, folder and isArchived.
  • An unknown status is ignored, so a typo lists the whole inbox.
  • The same PATCH corrects a classification: {"interest": "interested"}, or not_interested, objection, wrong_contact, referral and more.
  • Answering needs edit access to the inbox and the reply permission.

More recipes and guides