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.
Before you start
- REST:
export KENSO_API_KEY=<your key>andexport KENSO_WORKSPACE_ID=<your workspace id>(see Authentication and Workspaces). The examples read ids withjq. kenso:npm i -g kenso,printf '%s' "$KENSO_API_KEY" | kenso auth login --with-key, thenkenso workspace use <your workspace id>. A command prints the response'sdatawithout 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 asclient_idand 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/eventsis 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-subscriptionsandGET /v1/event-occurrencesfeed 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.
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')
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')
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.
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')
MESSAGE_ID=$(kenso threads list-messages --thread-id "$THREAD_ID" | jq -r '.[-1].id')
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.
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 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>"
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
})invalid_stateconfirmSuppressed: true only once a person has confirmed.idempotency_key_reused4. 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.
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 threads update --thread-id "$THREAD_ID" --data '{"isArchived": true}'threads({
"operation": "update",
"thread_id": "thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20",
"changes": {
"is_archived": true
},
"client_id": 4107
})Good to know
- Leave out
isArchived=falseand the list holds archived threads too.qsearches every thread and dropsstatus,folderandisArchived. - An unknown
statusis ignored, so a typo lists the whole inbox. - The same
PATCHcorrects a classification:{"interest": "interested"}, ornot_interested,objection,wrong_contact,referraland more. - Answering needs edit access to the inbox and the reply permission.