> 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: Forward 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).

## Forward an email thread

`POST /v1/threads/{threadId}/forward` - operationId `threads.forward`

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

Forwards an email thread's newest message to new recipients. Email threads only. `body` is required, and
`to` is required unless `replyAll` is true. Each recipient is one bare email address.

`senderEmailId`, the inbox that sends, is required unless `replyAll` is true. Kenso queues the forward
for an undo window of `delaySeconds`, 60 (the default) or 300 seconds, and returns `200` with the
scheduled message. `POST /v1/scheduled-messages/{scheduledMessageId}/cancel` stops it until the window ends.
`attachmentIds` takes `att_` ids uploaded against the thread's newest message. With
`archiveAfterSend: true` Kenso archives the thread once the forward sends.

A forward that goes back into the thread is refused when the contact is suppressed or when the workspace holds
replies for external approval. A forward goes back into the thread when it uses `replyAll` without
`to`, or names the contact or another participant as a recipient. No setting overrides this refusal: send a
reply instead.

A forward an agent or API key sends from its own member's mailbox does not send yet. It returns `202` with
the scheduled message in `status: awaiting_approval` and `approverMemberId`, and 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`.

The built-in Client role has no `export` permission, so its members can reply but not forward.

Errors:

- `400 validation_failed`: `body` or a required field is missing, a recipient is not an email address,
`delaySeconds` is not 60 or 300, `contentType` is not `html` or `text`,
`attachmentIds` names a file of another message, the thread is a LinkedIn thread, or the provider rejected
the forward.
- `403 forbidden`: the caller may not send from this inbox.
- `404 not_found`: the id is malformed, or no thread in this workspace has it.
- `409 invalid_state`: the sending inbox is disconnected, or the forward goes back into the thread while the
contact is suppressed or replies need external approval. The detail code is the suppression reason or
`client_approval_required`.
- `503 service_unavailable`: Kenso could not queue the forward. Retry later.

Requires Inbox edit and the `reply` and `export` permissions.

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

### 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. For 24 hours, a repeat of the same request with the same key gets the first response again, with the `Idempotent-Replayed: true` header, and Kenso does not run the action twice. The same key with a different request answers `422 idempotency_key_reused`. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get `503 service_unavailable` with `Retry-After`. Retry it with the same key. Kenso does not store a `4xx` or `5xx` response, so a retry after one runs the action again. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | string | yes | Required. Your note above the forwarded message: HTML unless `contentType` is `text`. |
| `senderEmailId` | integer (int32) | no | The id of the inbox that sends the forward. Required unless `replyAll` is true, when Kenso picks the inbox from the thread. |
| `contentType` | string | no | The body's format: `html` (the default) or `text`. |
| `replyAll` | boolean | no | Without `to`, true sends the forward to the thread's sender, To and Cc, minus the sending inbox. A forward that goes back into the thread is refused when the contact is suppressed or replies need external approval. |
| `injectPreviousEmailBody` | boolean | no | Quote the forwarded message under your note. Omitted or true quotes it, false leaves it out. |
| `replyTemplateId` | integer (int32) | no | The id of the reply template the note came from. Kenso stores it with the forward, and it does not change what is sent. |
| `useDedicatedIps` | boolean | no | Kenso stores it with the forward, and it does not change how the forward is sent. |
| `to` | array of ThreadAddressRequest | no | Who the forward goes to, each one bare email address. Required unless `replyAll` is true. |
| `cc` | array of ThreadAddressRequest | no | Cc recipients, each one bare email address. |
| `bcc` | array of ThreadAddressRequest | no | Bcc recipients, each one bare email address. |
| `delaySeconds` | integer (int32) | no | The undo window before the forward sends, 60 or 300 seconds. Omitted, it is 60. |
| `archiveAfterSend` | boolean | no | Archive the thread once the forward sends. |
| `attachmentIds` | array of string | no | The `att_` ids of files uploaded with `POST /v1/attachments` against the thread's newest message. |

### Response 200

Also answers `202`. `data` is a `ScheduledMessage`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The scheduled message's id. `POST /v1/scheduled-messages/{scheduledMessageId}/cancel` takes it. |
| `messageId` | string | The `msg_` id of the message it replies to or forwards. |
| `kind` | string | The kind of message: `reply` or `forward`. |
| `status` | string | The message's status: `scheduled`, `sending`, `sent`, `cancelled`, `failed` or `awaiting_approval`. |
| `approverMemberId` | integer (int64) | With status `awaiting_approval`: the member who must approve the message before it sends, the owner of the sending mailbox. `GET /v1/members` gives their name. |
| `delaySeconds` | integer (int32) | The undo window in seconds, 60 or 300. |
| `sendAt` | string (date-time) | When Kenso sends the message, in UTC. |
| `createdAt` | string (date-time) | When Kenso queued the message, in UTC. |
| `body` | string | The message's body. |
| `senderEmailId` | integer (int32) | The id of the inbox that sends the message. |
| `to` | array of ThreadRecipient | The To recipients. Null when none were named. |
| `cc` | array of ThreadRecipient | The Cc recipients. Null when none were named. |
| `bcc` | array of ThreadRecipient | The Bcc recipients. Null when none were named. |
| `draft` | ScheduledMessageDraft | On a cancel: the message, saved back as the thread's draft. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20/forward" \
  -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>Jordan, Amanda wants a call on Thursday afternoon. Can you take it?</p>",
  "senderEmailId": 5530,
  "contentType": "html",
  "replyAll": false,
  "injectPreviousEmailBody": true,
  "useDedicatedIps": false,
  "to": [
    {
      "name": "Jordan Patel",
      "address": "jordan.patel@northwind-outbound.example.com"
    }
  ],
  "delaySeconds": 60,
  "archiveAfterSend": false
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 66012,
    "messageId": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
    "kind": "forward",
    "status": "scheduled",
    "delaySeconds": 60,
    "sendAt": "2026-10-13T16:31:12Z",
    "createdAt": "2026-10-13T16:30:12Z",
    "body": "<p>Jordan, Amanda wants a call on Thursday afternoon. Can you take it?</p>",
    "senderEmailId": 5530,
    "to": [
      {
        "name": "Jordan Patel",
        "address": "jordan.patel@northwind-outbound.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`. |

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

### ScheduledMessageDraft

A cancelled message, saved back as the thread's draft.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `messageId` | string | no | The `msg_` id of the message the draft replies to or forwards. |
| `kind` | string | no | The kind of message: `reply` or `forward`. |
| `body` | string | no | The draft's body. |
| `senderEmailId` | integer (int32) | no | The id of the inbox the draft sends from. |
| `to` | array of ThreadRecipient | no | The draft's To recipients. Null when none. |
| `cc` | array of ThreadRecipient | no | The draft's Cc recipients. Null when none. |
| `bcc` | array of ThreadRecipient | no | The draft's Bcc recipients. Null when none. |
| `saved` | boolean | no | False when the cancel went through but Kenso could not save this draft as the thread's draft. The draft is still here, so save it yourself. |
