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

# Scheduled messages

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

Cancel a scheduled message before it starts sending.

Inbox. 1 endpoint under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/scheduled-messages/openapi.json](/docs/api/scheduled-messages/openapi.json).

- `POST /v1/scheduled-messages/{scheduledMessageId}/cancel` - Cancel a scheduled message (`scheduled-messages.cancel`): [/docs/api/scheduled-messages/cancel.md](/docs/api/scheduled-messages/cancel.md)

## Cancel a scheduled message

`POST /v1/scheduled-messages/{scheduledMessageId}/cancel` - operationId `scheduled-messages.cancel`

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

Stops a queued email reply or forward before it sends. Get the id from `scheduledMessageId` on the reply you
sent, from the forward's response, or from `scheduledMessages` on `GET /v1/threads/{threadId}`.

Only a message in `scheduled` or `awaiting_approval` status can be cancelled. Kenso saves its text back
as the thread's draft and returns it in `draft`. Files attached to the message return to pending, so you can
send them again or delete them. When the cancel succeeds but saving the draft fails, the response still returns the
message with `draft.saved` set to false, so save the draft yourself with
`PUT /v1/threads/{threadId}/draft`.

Errors:

- `404 not_found`: no scheduled message in this workspace has this id.
- `409 invalid_state`: the message is already sending, sent, cancelled or failed.

Requires Inbox edit and the `reply` permission.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `scheduledMessageId` | path | string | yes | The scheduled message's numeric 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`. |

### Response 200

`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/scheduled-messages/812/cancel" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

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

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

All resources: [/docs.md](/docs.md).
