> 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 sender routing rules

> **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 sender routing rules

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

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

Replaces every sender routing rule of the campaign and returns the routing as
`GET /v1/campaigns/{campaignId}/sender-routing` does. Send `[]` in `rules` to clear them.

Each rule names one mailbox provider or security gateway in `provider` (one rule per provider) and at least
one whole sending domain in `domains` or single inbox in `inboxIds`. Inboxes added later on a listed
domain join the rule. The rules apply to first emails planned from now on and to queued first emails when they
send. Follow-ups always come from the inbox that sent the first email.

Errors:

- `400 validation_failed`: a rule is invalid. Detail codes: `unknown_provider`,
`unsupported_provider`, `duplicate_provider`, `empty_rule` (no domain and no inbox),
`unknown_domain` (no workspace inbox on that domain), `unknown_inbox`, or `feature_disabled`
when 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/sender-routing)

### 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 |
| --- | --- | --- | --- |
| `rules` | array of ReplaceCampaignSenderRouteRule | yes | The rules, at most one per provider. Required. |

### Response 200

`data` is a `SenderRouting`.

| Field | Type | Description |
| --- | --- | --- |
| `allInboxes` | boolean | True when the campaign uses all inboxes, so inboxes connected later join it. False when it uses a saved list. Change it with `PUT /v1/campaigns/{campaignId}/inboxes`. |
| `rules` | array of SenderRouteRule | The routing rules, sorted by provider name. |
| `everyoneElse` | SenderRouteGroup | The inboxes no rule claims and the contacts no rule matches. |
| `warnings` | array of SenderRoutingWarning | Problems that would make contacts wait. Empty when there are none. |

### Request

```bash
curl -X PUT "https://api.ken.so/v1/campaigns/812/sender-routing" \
  -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 '{
  "rules": [
    {
      "provider": "microsoft_365",
      "domains": [
        "outreach.example.net"
      ]
    }
  ]
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "allInboxes": false,
    "rules": [
      {
        "provider": {
          "slug": "microsoft_365",
          "name": "Microsoft 365",
          "kind": "mailbox_provider"
        },
        "domains": [
          "outreach.example.net"
        ],
        "inboxIds": [],
        "sendableInboxCount": 2,
        "dailyCapacity": 100,
        "leadCount": 736
      }
    ],
    "everyoneElse": {
      "sendableInboxCount": 4,
      "dailyCapacity": 200,
      "leadCount": 1191
    },
    "warnings": [
      {
        "code": "rule_slow",
        "provider": "microsoft_365",
        "leadCount": 736,
        "days": 8
      }
    ]
  }
}
```

## Types

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

### ReplaceCampaignSenderRouteRule

One rule: contacts on `provider` get their first email only from these domains and inboxes.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | string | no | Slug of a mailbox provider or security gateway, such as `google_workspace` or `mimecast`. |
| `domains` | array of string | no | Whole sending domains: the part after `@` of a workspace inbox. Inboxes added on them later join the rule. Saved in lower case. |
| `inboxIds` | array of integer (int64) | no | Ids of single workspace inboxes. |

### SenderRouteRule

One routing rule, with the inboxes and contacts it covers now.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | RecipientProvider | no | The mailbox provider or security gateway the rule matches. |
| `domains` | array of string | no | Whole sending domains, in lower case. Inboxes added on these domains later join the rule. |
| `inboxIds` | array of integer (int64) | no | Ids of single inboxes in the rule. |
| `sendableInboxCount` | integer (int32) | no | The campaign's inboxes in the rule that can send now: they can send through Kenso and are not paused. |
| `dailyCapacity` | integer (int32) | no | Sum of those inboxes' daily send limits, in emails per day. An inbox with no limit set counts as 0. |
| `leadCount` | integer (int32) | no | The campaign's contacts that can still get an email and that the rule matches now. Contacts whose provider is still being detected are in no group. At most 100,000 contacts are counted. |

### SenderRouteGroup

The inboxes no rule claims and the contacts no rule matches.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sendableInboxCount` | integer (int32) | no | Inboxes in no rule that can send now: they can send through Kenso and are not paused. |
| `dailyCapacity` | integer (int32) | no | Sum of those inboxes' daily send limits, in emails per day. |
| `leadCount` | integer (int32) | no | Contacts that can still get an email and that no rule matches. |

### SenderRoutingWarning

A routing problem that would make contacts wait.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | no | The problem. `rule_no_inbox`: none of the rule's inboxes can send, so its contacts wait. `everyone_else_no_inbox`: every inbox that can send is in a rule, so contacts no rule matches wait. `rule_slow`: the rule needs more than 5 days to reach its contacts at its daily capacity. |
| `provider` | string | no | The rule's provider slug. Omitted for `everyone_else_no_inbox`. |
| `leadCount` | integer (int32) | no | Contacts that wait or are slow to reach. |
| `days` | integer (int32) | no | For `rule_slow` only: contacts divided by daily capacity, rounded up, in days. |

### RecipientProvider

A mailbox provider or security gateway Kenso recognizes.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | no | Stable short id, such as `google_workspace`, `microsoft_365` or `mimecast`. |
| `name` | string | no | Display name. |
| `kind` | string | no | Provider type: `mailbox_provider` or `security_gateway`. |
