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

# Threads: Start an email thread

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

One endpoint of [Threads](/docs/api/threads.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Start an email thread

`POST /v1/threads` - operationId `threads.create`

| Permission | Rate limit |
| --- | --- |
| Inbox edit and the `reply` permission | 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) |

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.

Needs the `agent_send` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/threads/POST/v1/threads)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |
| `Idempotency-Key` | header | string | yes | 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) | yes | 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 | yes | Required. The one person the email goes to. |
| `subject` | string | yes | Required. The email's subject. |
| `body` | string | yes | Required. The email body as HTML. |
| `overrideContactLimits` | boolean | no | true sends this email past a contact limit that refuses it (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. |

### Response 201

`data` is a `ThreadMessage`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The message's `msg_` id. |
| `threadId` | string | The `thr_` id of the thread. |
| `channel` | string | The channel: `email`, `linkedin`, `instagram`, `facebook`, `whatsapp` or `imessage`. |
| `kind` | string | What the item is: `message` for an email or chat message. A LinkedIn thread read with `includeEvents=true` also lists `connection_note` (the note sent with the invitation, outbound) and `connection_accepted` (the accept, inbound, with an empty body). An Instagram chat also has `story_reply` and `story_mention` (a message about a story), and `notice`: an event Instagram writes into the chat (for example that the person cannot receive the message), with no sender. Always set. |
| `direction` | string | Who sent the message: `inbound` (the contact) or `outbound` (the workspace). |
| `subject` | string | The message's subject. Null when it has none. |
| `body` | string | The message text. |
| `extractedText` | string | Inbound email only: the sender's own words, without quoted history, signature, mobile footer and sign-off. Omitted for outbound email, for LinkedIn, and for a message with no readable body. `body` keeps the full text. |
| `language` | string | Inbound messages only: the message's language as an ISO 639-1 code, such as `en`. Omitted when unknown and on outbound messages. |
| `occurredAt` | string (date-time) | When the message was sent or received, in UTC. |
| `scheduledMessageId` | integer (int64) | On the response of `POST /v1/threads/{threadId}/messages`, email only: the queued reply's scheduled message id. Until its undo window ends, `POST /v1/scheduled-messages/{scheduledMessageId}/cancel` with this id stops it. Omitted otherwise. |
| `warnings` | array of ThreadMessageWarning | Set on `POST /v1/threads/{threadId}/messages` when the reply went out past a safeguard you confirmed, and on `POST /v1/threads` when the new thread went out from an inbox that has not finished warmup. Omitted otherwise. |
| `senderName` | string | The same value as `fromName`. |
| `fromName` | string | The sender's name. |
| `fromEmailAddress` | string | Email only: the sender's address. |
| `htmlBody` | string | Email only: the message as HTML. |
| `tags` | array of ThreadTag | The tags on the message. |
| `to` | array of ThreadRecipient | Email only: the To recipients. |
| `cc` | array of ThreadRecipient | Email only: the Cc recipients. |
| `bcc` | array of ThreadRecipient | Email only: the Bcc recipients. |
| `openCount` | integer (int32) | Outbound email only: opens of the tracking pixel, without known proxies and crawlers. 0 when not opened or not tracked. |
| `rawOpenCount` | integer (int32) | Outbound email only: every hit on the tracking pixel, proxies and prefetches included. Always at least `openCount`. |
| `firstOpenedAt` | string (date-time) | Outbound email only: the first recorded open, in UTC. |
| `lastOpenedAt` | string (date-time) | Outbound email only: the latest recorded open, in UTC. |
| `referral` | ThreadReferral | Inbound email only: the person a recruiting reply referred you to, when its interest is `referral`. Null on LinkedIn messages and every other reply. |
| `browserRun` | ThreadBrowserRun | The workflow browser run whose web form submission this inbound message answers, or null. The Kenso app labels such a message as a browser run and never counts it as a reply. |
| `attachments` | array of MessageAttachment | Email only, on `GET /v1/threads/{threadId}/messages`: the message's files, inline images included. Download one with `GET /v1/attachments/{attachmentId}/content`. Omitted when the message has none. |
| `voiceNote` | VoiceNoteRef | LinkedIn only: the message's voice note. A note Kenso sent carries its `voiceNoteId`, the script and, while Kenso keeps the audio, `audioUrl`. A contact's note carries `voiceNoteId` 0, status `received` and `durationMs`. A note the account owner sent from LinkedIn itself is the same with status `sent`. Omitted otherwise. |
| `voiceTranscript` | string | WhatsApp only: the transcript of a voice note the contact sent, when one was made. Omitted otherwise. |
| `imessage` | ThreadMessageImessage | iMessage only: delivery, failure, tapbacks and media. Omitted on other channels. |
| `sentBy` | string | Email only: `agent` when Ken sent this message, either the reply agent (a reply a client approved first included) or a workflow's reply step, so the thread shows it as sent by Ken. Omitted on a message a person sent. |
| `agentJobId` | integer (int64) | The reply-agent job whose draft went out as this message, rated as `reply_job:{agentJobId}` on the `reply_sent` surface. Omitted when `sentBy` is, or when the job is not known. |
| `quoteDroppedReason` | string | Outbound email only: set when a reply or 1:1 follow-up went out without the earlier message Kenso quotes below it, because that message would have put a Kenso link in cold email. `brand_domain_in_quote`: the earlier message itself loads from a Kenso host or carries a Kenso tracking link. `brand_domain_when_joined`: each passes on its own, but the reply and the quote joined load from a Kenso host. The reply itself went out as written. Omitted when the quote went out, and on messages sent before Kenso recorded it. |

### Request

```bash
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": "priya.shah@northwind.example.com"
  },
  "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>"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
    "threadId": "thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20",
    "channel": "email",
    "kind": "message",
    "direction": "inbound",
    "subject": "Re: Onboarding new engineers at Northwind Labs",
    "body": "Thanks Alex, this is timely. We are hiring 12 engineers this quarter. Could we talk Thursday afternoon?\n\nAmanda\n\nOn Tue, Oct 13, 2026 at 9:04 AM Alex Rivera <alex@mail.example.com> wrote:\n> Hi Amanda, following up on this.",
    "extractedText": "Thanks Alex, this is timely. We are hiring 12 engineers this quarter. Could we talk Thursday afternoon?",
    "language": "en",
    "occurredAt": "2026-10-13T16:22:05Z",
    "senderName": "Amanda Chen",
    "fromName": "Amanda Chen",
    "fromEmailAddress": "amanda.chen@northwind.example.com",
    "htmlBody": "<p>Thanks Alex, this is timely. We are hiring 12 engineers this quarter.</p><p>Could we talk Thursday afternoon?</p><p>Amanda</p>",
    "tags": [
      {
        "id": 341,
        "name": "Hot lead",
        "color": "#FFD6A5"
      }
    ],
    "to": [
      {
        "name": "Alex Rivera",
        "address": "alex@mail.example.com"
      }
    ]
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### CreateThreadRecipient

The person a new thread's email goes to.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | string | yes | Required. One plain email address, such as `jane@acme.com`. |
| `name` | string | no | The person's name. Optional. |

### ThreadMessageWarning

A warning on a message that went out.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | no | What the warning is about: `suppressed_contact_overridden` (on a reply) or `warmup_not_ready` (on a new thread). |
| `reason` | string | no | With `suppressed_contact_overridden`, the suppression reason: `do_not_contact`, `blocklisted` or `unsubscribed`. With `warmup_not_ready`, the warmup state: `too_young` or `unconfirmed`. |
| `fix` | string | no | With `warmup_not_ready`: what to do. The email was sent, so pick an inbox that finished warmup for the next one. |
| `readyAt` | string (date-time) | no | With `warmup_not_ready` and `too_young`: the day the inbox is ready, in UTC. |

### ThreadTag

A tag on a thread or message.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The tag's id. |
| `name` | string | no | The tag's name. |
| `color` | string | no | The tag's display color. |
| `systemKey` | string | no | Set on a built-in Kenso tag: a fixed key to find it by, which stays the same when its name changes. Null on the workspace's own tags. |

### ThreadRecipient

An email recipient.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The display name. Null when the email gives none. |
| `address` | string | no | The email address. |

### ThreadReferral

The person a recruiting reply referred you to, when its interest is `referral`. Every part comes from the reply itself, and a part the reply does not give is null.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The person's name. |
| `email` | string | no | The person's email address. |
| `linkedinUrl` | string | no | The person's LinkedIn profile URL. |
| `phone` | string | no | The person's phone number as the reply writes it. Kenso cannot add a person with only a phone number as a contact, so add them by hand. |

### ThreadBrowserRun

The workflow browser run whose web form submission a thread or message answers.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `runId` | string | no | The browser run's id, as a string. |
| `automated` | boolean | no | True when the headers and the sender show that a machine sent the email, such as a form confirmation or a notification. |

### MessageAttachment

A file on an email message, inline images included.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The `att_` id that `GET /v1/attachments/{attachmentId}/content` downloads. Omitted when Kenso cannot serve the file, as for an older message whose original email Kenso did not store. |
| `fileName` | string | no | The file name the email gives. Null when it gives none. |
| `contentType` | string | no | The MIME type the email gives, such as `image/png`. |
| `sizeBytes` | integer (int64) | no | The file size in bytes. Null when unknown. |
| `isInline` | boolean | no | True for a part the email shows in its body, such as an inline image. |
| `contentId` | string | no | The MIME Content-ID an HTML body's `cid:` image refers to, without the `cid:` scheme. |

### VoiceNoteRef

A LinkedIn voice note on a message, touch or account activity. `audioUrl` is an API route that redirects to a short-lived link to the audio, and is set only while Kenso keeps the audio.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `voiceNoteId` | integer (int64) | no | The voice note's id. 0 for a voice note a contact sent. |
| `status` | string | no | `pending`, `generating`, `ready`, `sent`, `failed` or `expired`. On a thread message, a contact's note reads `received`. |
| `durationMs` | integer (int32) | no | The audio's length in milliseconds. Null until known. |
| `language` | string | no | The language of the script. Null when unknown. |
| `provider` | string | no | The voice service that made the audio. Null when unknown. |
| `voiceId` | string | no | The voice used for the audio. Null when unknown. |
| `scriptText` | string | no | The words spoken. Null until generated, and left out of list reads. |
| `failureReason` | string | no | Why the voice note failed. Null unless status is `failed`. |
| `audioAvailable` | boolean | no | True while Kenso keeps the audio. |
| `audioUrl` | string | no | The API route that serves the audio. Null when the audio is gone. |

### ThreadMessageImessage

One iMessage text's delivery, failure, tapbacks and media.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deliveredChannel` | string | no | How the text was delivered: `imessage` or `sms`. Omitted until delivered. |
| `deliveredAt` | string (date-time) | no | When the text was delivered. Omitted until delivered. |
| `failedAt` | string (date-time) | no | When delivery failed. Omitted unless it failed. |
| `errorCode` | string | no | A code for why delivery failed. Omitted unless it failed. |
| `reactions` | array of ThreadImessageReaction | no | The tapbacks on the text, at most one per direction (`inbound`: the person's, `outbound`: yours). |
| `mediaCount` | integer (int32) | no | How many images the text carried. |
| `voiceNoteId` | integer (int64) | no | The voice note the text carried; `GET /v1/voice-notes/{voiceNoteId}/imessage-audio` plays it. Omitted when none. |
| `attachments` | array of ThreadImessageAttachment | no | Files the person sent with an inbound text. Each file's `url` is a Kenso route that downloads it. |

### ThreadImessageReaction

A tapback on an iMessage text.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `direction` | string | no | `inbound` (the person's) or `outbound` (yours). |
| `value` | string | no | love, like, dislike, laugh, emphasize, question, or one emoji. |
| `at` | string (date-time) | no | When the tapback was set. |

### ThreadImessageAttachment

A file on an inbound iMessage text.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contentType` | string | no | The file's MIME type, when known. |
| `fileName` | string | no | The file's name, when known. |
| `url` | string | no | Where the file downloads: `GET /v1/threads/{threadId}/messages/{messageId}/attachments/{index}`, where `index` is the file's 0-based position in `attachments`. Requires Inbox view. Omitted when Kenso has no link for the file. |
