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

# Campaigns: Replace a campaign's inboxes

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

## Replace a campaign's inboxes

`PUT /v1/campaigns/{campaignId}/inboxes` - operationId `campaigns.replace-inboxes`

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

Sets the inboxes the campaign sends from and returns them. The new set replaces the old one.

Send `inboxIds` for a saved list, or `assignAllActive` to save every inbox that can send through
Kenso, optionally only those of one `provider`. Send `allInboxes` `true` to use all inboxes
instead: every inbox a launch would assign joins now, and inboxes connected later join too. Paused inboxes the
campaign does not already have are left out. `allInboxes` ignores the other fields and needs the sender
routing feature.

Errors:

- `400 validation_failed`: `inboxIds` is missing, names an inbox that is not in this workspace or
cannot send, no inbox matched `assignAllActive` or `allInboxes`, or `provider` is unknown.
Detail code `feature_disabled` means the workspace does not have the sender routing feature.
- `404 not_found`: the campaign does not exist in this workspace.

Requires Campaigns edit.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | Id of the campaign. |
| `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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inboxIds` | array of integer (int64) | no | Ids of the workspace inboxes the campaign should use. Required unless `assignAllActive` or `allInboxes` is true. |
| `assignAllActive` | boolean | no | True assigns every inbox in the workspace that can send through Kenso, as a saved list. `inboxIds` is then ignored. |
| `provider` | string | no | With `assignAllActive`, assigns only inboxes of this kind: `google`, `microsoft`, `azure` or `custom_smtp`. |
| `allInboxes` | boolean | no | True makes the campaign use all inboxes: every inbox a launch would assign joins now, and inboxes connected later join too. `inboxIds`, `assignAllActive` and `provider` are then ignored. Needs the sender routing feature. Omitted or false keeps a saved list of the inboxes you send. |

### Response 200

`data` is a list of `Inbox`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The inbox id. |
| `email` | string | The inbox's email address. |
| `firstName` | string | The sender's first name. Omitted when not set. |
| `lastName` | string | The sender's last name. Omitted when not set. |
| `displayName` | string | The sender name recipients see. Omitted when not set. |
| `signature` | string | The HTML signature Kenso adds to email from this inbox. Omitted when not set. |
| `status` | string | The inbox's state: `active`, `warmup`, `disconnected`, `paused`, `banned`, `connection_error`, `deleted`, `inactive` (its domain is about to expire), `replaced` (a rename gave the mailbox a new address, and this inbox keeps only its history) or `pending_provisioning` (Kenso is still setting up the mailbox). Only an `active` inbox sends campaign email. A pause shows in `pausedAt`, not here. |
| `role` | string | What the inbox is for: `sending` (a campaign inbox), `replies` (the workspace's shared replies inbox, the address campaign replies go to) or `retired` (a campaign inbox Kenso switched to receive only). A `replies` or `retired` inbox never joins a campaign or warmup, and Kenso keeps reading its mail. |
| `captureUntil` | string (date-time) | When a `retired` inbox's reply capture window ends, in UTC. Nothing changes automatically then: Kenso keeps reading the inbox until it is deleted. Omitted unless the inbox is retired. |
| `renewalEndsWindowEarly` | boolean | For a `retired` inbox: true when its domain's registration expires before `captureUntil` and auto-renew is off. The domain can then lapse, and a new owner would get the replies. False when auto-renew is on, the registration runs past `captureUntil`, or `captureUntil` has passed. Omitted when the inbox is not retired, or when Kenso does not know its domain or the registration's expiry. |
| `provider` | string | The mailbox platform: `google`, `microsoft`, `azure` or `custom_smtp`. |
| `domainId` | integer (int64) | The id of the inbox's domain in Kenso. Omitted when the domain is not one Kenso manages. |
| `dailySendLimit` | integer (int32) | The most emails the inbox sends per day. Omitted when not set. |
| `forwarding` | string | Where the inbox's incoming mail is forwarded: `ken_hosted` (to a Kenso address) or `client` (to `forwardingDestination`, an address of yours). Omitted when the inbox does not forward. |
| `forwardingDestination` | string | The email address that receives the inbox's forwarded mail. Omitted when there is none. |
| `profileImageUrl` | string | The URL of the inbox's sender photo: the photo Kenso set, else the photo the mailbox provider reports. Omitted when there is none. |
| `profilePhotoSupport` | string | Whether Kenso can set this inbox's sender photo: `google` (a Google mailbox Kenso set up for you), `microsoft` (a Microsoft or Azure mailbox Kenso set up for you), `google_account` or `microsoft_account` (a member's own mailbox, whose photo only its owner can change) or `none`. Setting a photo also needs the workspace's `inbox_photos` feature. |
| `profilePhotoStatus` | string | Whether the photo Kenso set reached the mailbox: `pending` (queued for a Microsoft or Azure mailbox and not applied yet), `applied` or `failed` (no photo shows, and `profilePhotoError` says why). Omitted when Kenso set no photo, or set it before Kenso tracked this. |
| `profilePhotoStatusAt` | string (date-time) | When `profilePhotoStatus` last changed, in UTC. For `pending`, when the photo was queued. |
| `profilePhotoError` | string | Why the photo failed. Present only when `profilePhotoStatus` is `failed`. |
| `tagIds` | array of integer (int64) | Ids of the workspace's tags on this inbox. Empty when it has none. |
| `createdAt` | string (date-time) | When the inbox was added to Kenso, in UTC. |
| `updatedAt` | string (date-time) | When Kenso last synced the inbox's details, in UTC. |
| `pausedAt` | string (date-time) | When a member paused outreach from this inbox, in UTC. Omitted when it is not paused. A paused inbox holds campaign steps, triggers and approved one-to-one Accounts email, while warmup and reply sync keep running. Separate from `status`. |
| `isKenSendable` | boolean | Whether Kenso can send campaign email from this inbox now. Present only on lists of the inboxes a campaign uses or can use. |
| `sendState` | string | Whether the inbox can send now, and if not, the first reason why: `ready` (it sends), `gone` (deleted, replaced, turned off or banned, so it never sends again), `receive_only` (a `replies` or `retired` inbox), `needs_reconnect` (its sign-in failed or its connection is gone: reconnect it), `paused` (a member paused it, or its provider did), `warming` (warmup is not finished), `blocked_until` (a send block is in force until `sendBlock.until`) or `not_sendable` (Kenso cannot send from it for another reason, such as setup that is not finished or a daily limit of 0). For a shared campaign inbox, `ready` means it is in the pool Kenso sends campaign email from, the same pool the launch check counts. For a member's own inbox, it means its owner can send from it. The warmup age gate and today's cap are separate (`warmup.daysLeft`, `health`). A paused inbox still sends the replies a member writes. Omitted on the responses that create an inbox (read it again), and when Kenso could not work it out. |
| `oneToOneReadiness` | InboxOneToOneReadiness | Whether an approved one-to-one email that names this inbox goes out now (an account's Sends from, or the From of a workflow's send step), and if not, why and what fixes it. The same answer as `GET /v1/inboxes/{inboxId}/one-to-one-readiness`. Separate from `sendState`, which is about campaign email. Omitted on lists of the inboxes a campaign uses or can use, on the responses that create an inbox (read it again), and when Kenso could not work it out. |
| `sendingProvider` | string | The slug of the provider account this inbox sends through, when the workspace connected that account itself. Null on every other inbox. An SMTP inbox Kenso runs reads `provider: custom_smtp` and no `sendingProvider`; Kenso staff get the slug on every provider inbox. |
| `isIngestReady` | boolean | Whether Kenso can read replies from this inbox. An inbox can send before Kenso can read its replies. Present only on lists of the inboxes a campaign uses or can use. |
| `ownerMemberId` | integer (int64) | The member whose own mailbox this is. Omitted for a shared campaign inbox. A member's own mailbox never joins a campaign or warmup. |
| `isPrimary` | boolean | True when a member owns the inbox and its address is on one of the workspace's domains: its email domain or a domain listed under Settings > Company. Kenso works it out on each read, so it follows later changes to that list. Only a primary inbox sends the member's one-to-one Accounts email. |
| `isAccountsDefault` | boolean | True on the one inbox per member that their accounts' one-to-one email goes out from when nothing names another: their lowest-id primary inbox that is connected and can send. An account's Sends from inbox, or the From of a workflow's send step, picks another; left on Automatic, a workflow's email goes out from the account's Sends from inbox, else from this inbox of the account's owner. False on every other inbox, including a primary inbox that is disconnected or not the member's first one. |
| `connectionApp` | string | The Kenso app a Google or Microsoft connection was granted to: `ken_mail` (campaign mailboxes) or `ken_workspace` (a member's own mailbox). Omitted for SMTP and unconnected inboxes. |
| `trackOpens` | boolean | The owner's open tracking option, off by default. Open tracking is unavailable: Kenso adds no open-tracking pixel to replies or to one-to-one Accounts email, and turning it on is refused (`open_tracking_unavailable`). Present only on a member's own mailbox. |
| `usedBy` | UsedBy | The live campaigns that send through this inbox, and whether Accounts uses it. Omitted when Kenso could not read it. |
| `warmup` | InboxWarmupSummary | Warmup progress toward the minimum warmup age Kenso requires before cold sends. Omitted when no warmup sends were reported for the inbox, unless an outreach bypass from Kenso covers it. The full warmup state is `GET /v1/inboxes/{inboxId}/warmup`. |
| `sendBlock` | InboxSendBlock | The block that stops campaign sends from the inbox now. Omitted when the inbox is not blocked. |
| `healthScore` | integer (int32) | Kenso's health score for the inbox, from 0 to 100, from the latest mailbox health check. Omitted when no check has reported on the inbox. |
| `lastSentAt` | string (date-time) | The inbox's last send its mail server accepted, in UTC. Warmup sends do not count. Omitted when it sent nothing in the last 30 days, or when Kenso could not read it. |
| `connection` | InboxConnection | The health of Kenso's own connection to the mailbox. Omitted when Kenso has no connection of its own to the mailbox. |
| `health` | InboxHealth | Today's sends against the inbox's daily cap, its ramp, its warmup readiness and what holds it back now. Only on `GET /v1/inboxes/{inboxId}`, never on a list, and only when the workspace has the `agent_send` feature. Omitted otherwise, and when Kenso could not read it. |

### Request

```bash
curl -X PUT "https://api.ken.so/v1/campaigns/812/inboxes" \
  -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 '{
  "inboxIds": [
    5530,
    5531,
    5532
  ],
  "assignAllActive": false
}'
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "id": 5530,
      "email": "alex@mail.example.com",
      "firstName": "Alex",
      "lastName": "Rivera",
      "displayName": "Alex Rivera",
      "signature": "Alex Rivera\nNorthwind Outbound",
      "status": "active",
      "role": "sending",
      "provider": "google",
      "domainId": 640,
      "dailySendLimit": 30,
      "profilePhotoSupport": "google",
      "tagIds": [],
      "createdAt": "2026-08-31T10:15:00Z",
      "updatedAt": "2026-10-14T09:41:27Z",
      "isPrimary": false,
      "isAccountsDefault": false,
      "usedBy": {
        "campaigns": [
          {
            "id": 4821,
            "name": "Q4 SaaS founders",
            "status": "active"
          }
        ],
        "accounts": false
      },
      "warmup": {
        "daysLeft": 0
      },
      "healthScore": 94,
      "lastSentAt": "2026-10-14T09:12:40Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Types

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

### InboxOneToOneReadiness

Whether an inbox can send a 1:1 email now, and if not why.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inboxId` | integer (int64) | no | The inbox. |
| `email` | string | no | Its address. |
| `senderKind` | string | no | How it sends a 1:1 email: `member_mailbox` (a member's own mailbox, only as their primary inbox), `shared_inbox` (a shared campaign inbox on a cold sending domain) or `sending_identity` (a sending provider identity, through its provider connection). |
| `canSend` | boolean | no | True when an approved 1:1 email touch that names this inbox (an Accounts touch, or a workflow `send.email` step's `fromInbox`) goes out now, and its reply comes back to Kenso. False when the touch would wait (`connect_inbox`, or `inbox_paused` for `paused`). |
| `reason` | string | no | Why it cannot send; omitted when canSend is true. `receive_only`: retired or the replies inbox. `not_connected`: its connection, or a sending identity's provider connection, cannot send now. `replies_not_read`: a sending identity whose replies would not reach Kenso. `not_cold_sender`: not on one of the workspace's cold sending domains. `not_primary`: a member's mailbox off the workspace's domains. `paused`: a member paused it. Tolerate values not listed here. |
| `message` | string | no | What fixes it, for a person; omitted when canSend is true. |
| `signatureWarning` | string | no | `brand_domain` when the inbox is a member's mailbox whose saved signature loads from or links to a Kenso domain the mailbox's own domain does not cover in a way the brand check refuses (an image, a Kenso tracking or system link), so a 1:1 email from it goes out without the signature (the email itself still goes). A plain link to a Kenso site is allowed and is no warning. Omitted when the signature goes out as saved, or the inbox adds none. Tolerate values not listed here. |
| `signatureMessage` | string | no | What fixes the signature, for a person, naming what the check found; omitted with signatureWarning. |

### UsedBy

What an inbox or LinkedIn account is used for: the live campaigns that send through it, and whether Accounts uses it for one-to-one outreach.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `campaigns` | array of UsedByCampaign | no | The live campaigns (scheduled, launching or sending) that use this inbox or LinkedIn account, ordered by id. Empty when there are none. |
| `accounts` | boolean | no | True when Accounts uses it for one-to-one outreach. An inbox counts when it is its member's primary inbox (`isPrimary`). A LinkedIn account counts when the member who connected it owns at least one live account in Accounts, because an account's LinkedIn steps go out from the LinkedIn account its owner connected. |

### InboxWarmupSummary

An inbox's progress toward the minimum warmup age Kenso requires before cold sends.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `daysLeft` | integer (int32) | no | Days until the inbox reaches the minimum warmup age, counted from its first reported warmup send. 0 once it gets there, or when Kenso waived the age for the inbox. An outreach bypass from Kenso reports 0 even before any warmup send. |

### InboxSendBlock

A block that stops campaign sends from an inbox until a set time.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | no | Why Kenso blocked the inbox, as a code such as `mailbox_hard_bounce_rate`. Omitted when a person set the block, or a rename did. |
| `until` | string (date-time) | no | When the block ends, in UTC. The inbox sends no campaign email until then. |

### InboxConnection

The health of Kenso's own connection to a mailbox, which it uses to send and to read replies.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | Connection state: `connected`, `disconnected`, `auth_expired` (the mailbox must be signed in again) or `error`. |
| `checkedAt` | string (date-time) | no | When Kenso last checked the connection with the mail provider (UTC). Omitted before the first check. |
| `error` | string | no | Short reason from the mail provider, at most 300 characters, when `status` is `auth_expired` or `error`. It never contains credentials. Omitted otherwise. |

### InboxHealth

An inbox's sending health today: what it sent, what it may still send, and what holds it back.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sentToday` | integer (int32) | no | Emails the mail provider accepted from this inbox so far in its send day, from campaigns and one-to-one replies. |
| `reservedToday` | integer (int32) | no | Emails being sent right now, which already count against today's limit. |
| `limit` | integer (int32) | no | Today's limit: the inbox's daily limit after its ramp-up, its domain's ramp-up and the mail provider's maximum. |
| `remaining` | integer (int32) | no | Emails the inbox can still send today: `limit` minus `sentToday` and `reservedToday`, never below 0. |
| `dayEndsAt` | string (date-time) | no | When the send day ends (UTC). The day follows the time zone of the inbox's campaigns, or New York when none sets one. |
| `rampDay` | integer (int32) | no | Day of the ramp-up: 1 during the first 24 hours of sending, and still returned once the ramp-up is over. Omitted when the limit could not be worked out from send history. |
| `rampComplete` | boolean | no | True when the ramp-up reached its target and no longer lowers the limit. False when `rampDay` is omitted. |
| `warmupReadiness` | string | no | Whether warmup cleared the inbox to send, with the same values as `readiness.outcome` on `GET /v1/inboxes/{inboxId}/warmup`: `ready`, `too_young`, `unconfirmed`, `bypassed`, `provider_stale` or `unavailable` (no recent warmup data, or no result for the inbox). |
| `blocks` | array of InboxHealthBlock | no | What holds the inbox back now. Empty when nothing does. |
| `bounceRate7d` | number (double) | no | Hard bounces divided by accepted emails over the last 7 days, from 0 to 1. Omitted when nothing was accepted in that window, and when `rampDay` is omitted. |
| `notes` | array of InboxHealthNote | no | What the inbox's state shows that holds no send now. Empty when there is nothing to show. Not a block: the inbox keeps sending. |

### UsedByCampaign

A live campaign that uses an inbox or LinkedIn account.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The campaign id. |
| `name` | string | no | The campaign's name. |
| `status` | string | no | The campaign's status, with the same values as `GET /v1/campaigns`. |

### InboxHealthBlock

One thing that holds an inbox back from sending.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | no | What holds it back: `paused` (a member paused the inbox), `send_blocked` (Kenso blocked it, for example after a failed placement test) or `sending_paused` (a pause on the inbox, its domain or the workspace, that holds sends now: an operator's pause, which stops campaign sends and new agent threads, or any pause once capacity limits are enforced). |
| `reason` | string | no | Why, as recorded: usually a code such as `mailbox_hard_bounce_rate`. Omitted when no reason was recorded. |
| `until` | string (date-time) | no | When the block ends (UTC). Omitted for `paused`, which lasts until a member resumes the inbox. |

### InboxHealthNote

Something an inbox's state shows that holds no send.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | no | `sending_pause_observed`: an automatic pause (any pause Kenso opened itself, for example after a placement test, bounces, complaints or a domain breach, and not an operator's) covers the inbox, its domain or the workspace, but while capacity limits are not enforced it holds no send, so the inbox keeps sending. |
| `reason` | string | no | Why, as recorded: usually a code such as `domain_bounce`. Omitted when no reason was recorded. |
| `until` | string (date-time) | no | When the pause ends (UTC). |
