> 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: Get an inbox's warmup

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

## Get an inbox's warmup

`GET /v1/inboxes/{inboxId}/warmup` - operationId `inboxes.get-warmup`

| Permission | Rate limit |
| --- | --- |
| Delivery view | 12,000 requests a minute per API key |

Returns the inbox's warmup state and Kenso's readiness verdict: `readiness` shows how far any warmup has
run. It is evidence only, not a condition for sending.

Warmup is off by default: a new inbox reads `not_started` and ramps up its sends instead. `status` is
`pending` while warmup the workspace bought waits to start, or after someone turned warmup on and Kenso
has not enrolled the inbox yet, and `paused` while it is paused. An Azure inbox with no warmup subscription
reads `failed`, because Kenso cannot enroll Azure inboxes in warmup. Kenso omits `readiness` when it
could not read it. `pool` shows the inbox's place in the Kenso warmup pool when it is a member.

Errors:

- `404 not_found`: no inbox with this id in the workspace.

Requires Delivery view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/inboxes/GET/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`. |

### 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 GET "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"
```

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