> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [https://api.ken.so/v1/docs/openapi.json](https://api.ken.so/v1/docs/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-15.

# Read and answer replies

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

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>` and `export KENSO_WORKSPACE_ID=<your workspace id>` (see [Authentication](/docs/authentication) and [Workspaces](/docs/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](/cli)).
- MCP: connect `https://mcp.ken.so/mcp` ([setup](/mcp)). 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](/docs/recipes/receive-webhooks)). You still read and answer with the calls here.

## 1. Find the replies waiting on you

[`GET /v1/threads`](/docs/api/threads.md)

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**

```bash
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**

```bash
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`)

```text
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`](/docs/api/threads.md)

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**

```bash
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**

```bash
MESSAGE_ID=$(kenso threads list-messages --thread-id "$THREAD_ID" | jq -r '.[-1].id')
```

**MCP** (`threads`)

```text
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`](/docs/api/threads.md)

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**

```bash
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**

```bash
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`)

```text
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}`](/docs/api/threads.md)

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**

```bash
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**

```bash
kenso threads update --thread-id "$THREAD_ID" --data '{"isArchived": true}'
```

**MCP** (`threads`)

```text
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

- [Add leads from your app](/docs/recipes/add-leads.md)
- [Create and launch a campaign](/docs/recipes/launch-a-campaign.md)
- [Receive webhooks](/docs/recipes/receive-webhooks.md)
- [API reference](/docs.md)
