> 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: Send a reply in a 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).

## Send a reply in a thread

`POST /v1/threads/{threadId}/messages` - operationId `threads.create-message`

| Permission | Rate limit |
| --- | --- |
| Inbox edit and the `reply` permission | 10 requests a minute per API key |

Sends a reply on an email thread, a LinkedIn conversation or an Instagram, Facebook, WhatsApp or iMessage chat.
`body` is required, except where a channel below lets it be blank: images on Instagram, Facebook or WhatsApp,
a Facebook voice note, or a lone `voiceNoteId` on iMessage. 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` (an iMessage thread
refuses it).

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

On an iMessage thread (while the `imessage` flag is on) a member's reply takes `body` (at most 4,096
characters), with up to 10 `mediaIds` if you want images, or a lone `voiceNoteId`, and sends at once:
`201` once the send is confirmed. Images never go without a text: `mediaIds` with a blank `body` is
`400 validation_failed` on `body`. Setting `subject`, `to`, `cc`, `bcc`,
`replyAll`, `attachmentIds`, `contentType`, `voiceProvider`, `voiceId` or
`imageIds` there is `400 validation_failed` on that field, and nothing is sent. A longer `body`
(detail `imessage_text_too_long`; nothing is sent), a text before the person replied that holds a link, an
email address, a phone number or a money amount (detail `first_message_content`), or an unusable image or
voice note, is `400 validation_failed`. A `body` that still holds a
template key nobody filled in is `422 unfilled_template_key`, with the key in the detail's `key` and the
marker as written in `marker`. In a member's own text only a brace key counts (`{first_name}`,
`{{company}}`, spintax), so square brackets are ordinary text; in an agent's or API key's text
a square-bracket key such as `[company]` counts too. A line that cannot send now holds the text:
`409 invalid_state` with the reason as detail code, `nextAllowedAt` and `Retry-After`, so send it
again after that time. A refusal is `409 invalid_state` with the reason as detail code, no `nextAllowedAt`
and no `Retry-After`, and its `fix` says what must change: media before the person replied
(`imessage_media_requires_reply`) or on an SMS thread (`imessage_sms_thread`), `recipient_must_reply`,
`phone_opt_out` (a STOP, or the person's opt-out of texts), `do_not_call` (a provider the workspace's own key asked flagged the person do not call, and the person
has not written in this thread or the text is an agent's or API key's: a member may answer a person who wrote),
`suppressed:<reason>` (blocklist,
do-not-contact, unsubscribed; never overridable), `provider_rejected:IMESSAGE_SEND_REFUSED`,
`imessage_line_owner_left` and `imessage_line_gone` (the thread's line was released, failed or never
activated, or the thread is gone, so nothing
goes on this thread again, and a new line cannot carry it). An agent or API key may text only a person who
engaged first (`409`, detail `imessage_not_engaged`), and never one whose no stands, even after they texted
this thread: `409` with detail `person_refused` while nothing since their no takes it back (a reply classed
as no refusal, an accepted connection or a booked meeting; a text with no class never does), and `503` with
detail `imessage_reply_unclassified` while a message of theirs after it still waits for its class (try again in
a few minutes). Neither saves a touch or sends anything; a member may still send the text. Its text always waits for approval, through the line
owner's own credential too: it is saved as an iMessage touch pinned to this thread, so it goes only from this thread's
line to this thread's number, and answered `202` with `status` `awaiting_approval`, `channel`
`imessage`, the `touch_` `approvalId`, `approverMemberId` and `approverName` (that member's
first name). Only a person approves it: an agent or API key gets `403`, detail
`approval_requires_human`. When this thread's line can no longer send, the agent's text is
`409 invalid_state` with detail `imessage_line_gone` (the line was released, failed or never activated, or
its thread is gone), `imessage_line_down` or
`imessage_line_owner_left`; a paused line still takes it, and it waits there. An agent's voice note, or a person
on no live account, is `403 forbidden` with detail `imessage_agent_voice_note` (on `voiceNoteId`) or
`imessage_person_on_no_account` (on `threadId`), unless an earlier check refuses the voice note first
(`409` `imessage_media_requires_reply` or `imessage_sms_thread`, `400`
`imessage_voice_note_alone` or `imessage_voice_note_unavailable`). `409 outcome_unknown`
means Kenso could not tell whether the text went out: never send it again under a new key. When it carries
`nextAllowedAt` and `Retry-After`, send the same request with the same `Idempotency-Key` after that
time: Kenso reads the thread and answers `201` when the text is there, or `503` with detail
`imessage_reply_not_sent` when it never went (the key is free again: send it under the same key or a new
one). When Kenso cannot read the thread yet, it answers `409 outcome_unknown` again with a later
`nextAllowedAt`. When the thread or its line is gone, it answers `404` or `409 invalid_state` with
detail `imessage_line_gone`, frees the key, and nothing more goes. While iMessage sending is paused, that
retry answers `503` with detail `imessage_first_try_unknown` instead: it sent nothing, but the first try
may have gone, so read the thread or retry later under the same key. Any other `503` means nothing
went. An iMessage `Idempotency-Key` never sends twice:
a retry with it answers the same `201` or `202`. `mediaIds` and `voiceNoteId` on any other
thread are `400 validation_failed`.

Errors:

- `400 validation_failed`: `body` is missing where the channel needs one (an iMessage reply needs one
unless it is a lone `voiceNoteId`), `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 or iMessage reply
names a field its channel does not take, 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, or an agent or API key sent a
voice note on an iMessage thread (detail `imessage_agent_voice_note`) or texted a person on no live account
(detail `imessage_person_on_no_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, the
LinkedIn account reached its daily limit, an iMessage line cannot send now (with `nextAllowedAt`) or refused the
text (no retry time, see above), or the thread's line was released, failed or never activated
(`imessage_line_gone`), or an agent's text has
a thread line that is down or whose owner can't send from it (`imessage_line_down`, `imessage_line_owner_left`),
or an agent's text goes to a person whose no stands (`person_refused`).
- `409 in_progress`: an email reply under this key is still being queued. Retry after
`nextAllowedAt`, also sent as `Retry-After`. On an iMessage thread, a reply under this key is still being
sent by another request, which owns the send: nothing more goes, so read the thread in a moment.
- `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. On an iMessage thread it may carry
`nextAllowedAt` and `Retry-After`: retry the same request with the same key after that time.
- `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 unfilled_template_key`: an iMessage text still holds a template key, named in the detail's `key` and
quoted as written in `marker`. Fill it in or take it out.
- `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. On an iMessage thread, detail `imessage_unavailable` means iMessage cannot send right
now (Kenso could not check the line's new-conversation lock, or iMessage is unavailable for now): nothing was sent,
try again later. Detail `imessage_reply_unclassified` on an agent's text: a message of theirs after their no
waits for its class; nothing was saved, try again in a few minutes. Detail `imessage_reply_not_sent` answers a
retry under the key of an unsure text that Kenso found never went out: the key is free again, so send it again
under the same key or a new one. Detail `imessage_first_try_unknown` answers a retry under the key of an
unsure text while iMessage sending is paused: this retry sent nothing, but the first try may have gone out. While
iMessage sending is paused, a key whose first try is still running answers this `503` too (not
`409 in_progress`), and a key used for another reply answers the plain `503` (not
`422 idempotency_key_reused`).

Requires Inbox edit and the `reply` permission.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `threadId` | path | string | yes | The thread's `thr_` id. |
| `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 | no | 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 |
| --- | --- | --- | --- |
| `body` | string | no | The reply text: HTML on an email thread unless `contentType` is `text`, plain text on any other thread. Required, except with images on an Instagram, Facebook or WhatsApp thread, a Facebook voice note, or a lone iMessage `voiceNoteId`. |
| `subject` | string | no | Drafts only. A reply goes out on the thread's own subject, so a send ignores this field, except on an iMessage thread, which refuses it with `400 validation_failed`. Set a draft's subject with `PUT /v1/threads/{threadId}/draft`. |
| `senderEmailId` | integer (int32) | no | Email only, and required there: the id of the inbox that sends the reply. |
| `delaySeconds` | integer (int32) | no | Email 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. |
| `confirmSuppressed` | boolean | no | Email 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. |
| `archiveAfterSend` | boolean | no | Email 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. |
| `to` | array of ThreadAddressRequest | no | Email 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. |
| `cc` | array of ThreadAddressRequest | no | Email only: Cc recipients, each one bare email address. A LinkedIn thread refuses it. |
| `bcc` | array of ThreadAddressRequest | no | Email only: Bcc recipients, each one bare email address. A LinkedIn thread refuses it. |
| `replyAll` | boolean | no | Email only: without `to`, reply to the thread's sender, To and Cc, minus the sending inbox. A LinkedIn thread refuses it. |
| `attachmentIds` | array of string | no | Email: `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. |
| `contentType` | string | no | Email only: `html` (the default) or `text`. A LinkedIn thread refuses it. |
| `imageIds` | array of string | no | Facebook 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`. |
| `voiceNoteId` | integer (int64) | no | Facebook and iMessage threads only. On Facebook, a ready voice note Kenso made for the thread, sent last. On iMessage, a ready voice note made for this person with `POST /v1/voice-notes`. It goes alone, with no body or images. A member's reply only: from an agent or an API key it is `403 forbidden` (`imessage_agent_voice_note`); they put the note on the person's iMessage touch instead, which a member approves. Any other thread refuses it with `400 validation_failed`. |
| `mediaIds` | array of integer (int64) | no | WhatsApp and iMessage threads only. On WhatsApp, up to 6 distinct `message_media` image ids to send with the text; with images, `body` may be blank. On iMessage, the `mediaId`s of images uploaded with `POST /v1/imessage-media`, at most 10, sent with a `body` (never alone: a blank `body` is `400 validation_failed` on `body`), only after the person replied and never on an SMS thread. |
| `voiceProvider` | string | no | WhatsApp 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. |
| `voiceId` | string | no | WhatsApp threads only: the voice of the voice note, at most 200 characters. Requires `voiceProvider`. |

### Response 201

Also answers `202`. `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/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"
}'
```

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

### ThreadAddressRequest

An email recipient.

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

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