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

# Inboxes: Turn an inbox's warmup on or off

> **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 [Inboxes](/docs/api/inboxes.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Turn an inbox's warmup on or off

`PATCH /v1/inboxes/{inboxId}/warmup` - operationId `inboxes.update-warmup`

| Permission | Rate limit |
| --- | --- |
| Delivery edit | 4,800 requests a minute per API key |

Send `enabled: false` to pause the inbox's warmup or `enabled: true` to turn it on. Warmup is off by
default: new inboxes ramp up their sends instead. Turning it on resumes paused warmup, or, for a Google inbox
Kenso provided that has no warmup yet, answers with `status` `pending` while Kenso enrolls it, within
about 10 minutes. The response leaves out `readiness`: read it with
`GET /v1/inboxes/{inboxId}/warmup`.

For an inbox in the Kenso warmup pool, or a Google or Microsoft inbox of a workspace that joined it,
`enabled: true` switches the inbox on for the pool and `enabled: false` switches it off.

Errors:

- `400 validation_failed` on `enabled`: `enabled` is missing or not a boolean, or Kenso could
not change this inbox's warmup. The message is the reason code, such as `not_found` (no inbox with this
id in the workspace), `not_active` (pausing warmup that is not running), `not_paused`,
`unknown_status` or `missing_uid` (turning on warmup for an inbox Kenso cannot enroll, such as the
workspace's own mailbox or an Outlook inbox) or `provider_error`.
- `409 invalid_state`: the inbox's workspace is not in the warmup pool.
- `503 service_unavailable`: the warmup pool could not take the change; retry later.

Requires Delivery edit.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/inboxes/PATCH/v1/inboxes/%7BinboxId%7D/warmup)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `inboxId` | path | integer (int64) | yes | The inbox's 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`. |

### Request body

`application/json`, optional: `object`.

### Response 200

`data` is a `InboxWarmup`.

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | The warmup state: `not_started`, `pending` (warmup is being switched on), `in_progress`, `paused`, `completed`, `maintenance`, `failed` or `degraded`. An Azure inbox with no warmup plan is `failed`, because Kenso cannot start warmup on Azure. |
| `enabled` | boolean | True when warmup is switched on: the inbox is warming up or its warmup is starting. |
| `startedAt` | string (date-time) | When warmup started, in UTC. When Kenso has no start time, the first day warmup sends were reported. Omitted when neither is known. |
| `completedAt` | string (date-time) | When warmup completed, in UTC. Omitted until it does. |
| `readiness` | InboxWarmupReadiness | Whether the inbox is warm enough for cold sends. Only on `GET /v1/inboxes/{inboxId}/warmup`, not on the update response, and omitted when Kenso could not read it. |
| `pool` | InboxWarmupPool | The inbox's place in the Kenso warmup pool. Present only when the inbox is a pool member. Unless its pool `status` is `off`, the `status` and `enabled` above come from the pool. |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/inboxes/812/warmup" \
  -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 '{}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "status": "string",
    "enabled": true,
    "startedAt": "2026-09-23T15:02:11Z",
    "completedAt": "2026-09-23T15:02:11Z",
    "readiness": {
      "outcome": "string",
      "isReady": true,
      "isHeld": true,
      "isEnforced": true,
      "firstWarmupSendDate": "string",
      "lastWarmupSendDate": "string",
      "daysInWarmup": 1,
      "minimumWarmupDays": 1,
      "hasMinWeekOverride": true,
      "hasOutreachBypass": true
    },
    "pool": {
      "status": "waiting",
      "reasonCode": "seed_spam",
      "role": "full",
      "isEnabled": true
    }
  }
}
```

## Types

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

### InboxWarmupReadiness

The verdict of Kenso's warmup check, which keeps cold sends off an inbox until it is warm.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `outcome` | string | no | The verdict: `ready`, `bypassed` (an outreach bypass from Kenso covers the inbox), `unconfirmed` (no recent warmup sends reported), `too_young` (younger than `minimumWarmupDays`), `provider_stale` (the warmup service reported nothing recently, so the check holds nothing) or `unavailable` (no fresh warmup data, or the read failed, so the check holds nothing). |
| `isReady` | boolean | no | True when warmup is confirmed: the outcome is `ready` or `bypassed`. |
| `isHeld` | boolean | no | True when the check keeps cold sends off this inbox, as long as `isEnforced` is true. |
| `isEnforced` | boolean | no | True when the check holds inboxes now. When false, a held inbox still sends. |
| `firstWarmupSendDate` | string | no | The first day warmup sends were reported, as YYYY-MM-DD in UTC. Omitted when none were. |
| `lastWarmupSendDate` | string | no | The latest day warmup sends were reported with warmup on, as YYYY-MM-DD in UTC. Omitted when none were. |
| `daysInWarmup` | integer (int32) | no | Whole days since the first reported warmup send. Omitted when none was reported. |
| `minimumWarmupDays` | integer (int32) | no | The minimum warmup age, in days, the check requires before cold sends. |
| `hasMinWeekOverride` | boolean | no | True when Kenso waived the minimum warmup age for this inbox or its domain. |
| `hasOutreachBypass` | boolean | no | True when Kenso granted an outreach bypass for this inbox or its domain, which skips the warmup check. |

### InboxWarmupPool

An inbox's place in the Kenso warmup pool.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | The pool status: `waiting`, `probation`, `active`, `watch`, `throttled`, `quarantined`, `ejected`, `tapering`, `paused`, `not_eligible` or `off`. |
| `reasonCode` | string | no | Why the inbox has this status, as a code such as `seed_spam`. Omitted when there is none. |
| `role` | string | no | `full`, `reply_only` or `send_only`. Omitted until Kenso checked what the mailbox can do. |
| `isEnabled` | boolean | no | True when the inbox is switched on for the pool. |
