---
title: "Routing API"
description: "Routing in the OneSend API: 6 endpoints. Policies decide provider order, caps, rules and what happens when quota runs out."
url: https://onesend.email/docs/api-reference/routing/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Routing

Policies decide provider order, caps, rules and what happens when quota runs out.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## List routing policies

GET `/v1/policies`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "policy",
    "name": string,
    "description": string or null,
    "strategy": "priority" | "weighted" | "round_robin",
    "steps": [{ … }],
    "rules": [{ … }],
    "fallback": "queue_until_reset" | "fail",
    "messageTypes": ["transactional" | "broadcast"],
    "isDefault": boolean,
    "createdAt": string
  }],
  "nextCursor": string or null
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Create a routing policy

POST `/v1/policies`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name`required | `string` |  |
| `description` | `string or null` |  |
| `strategy` | `"priority" \| "weighted" \| "round_robin"` |  |
| `steps`required | `array of object` |  |
| `steps[].connectionId`required | `string` |  |
| `steps[].weight` | `number` |  |
| `steps[].dailyCap` | `integer` |  |
| `steps[].enabled` | `boolean` |  |
| `steps[].stream` | `"transactional" \| "broadcast"` | Stream separation: only `transactional` or only `broadcast` (campaign) email uses this provider. Unset: both. |
| `rules` | `array of object` |  |
| `rules[].when`required | `object` |  |
| `rules[].when.recipientDomain` | `array of string` |  |
| `rules[].when.tag` | `array of string` |  |
| `rules[].when.type` | `"transactional" \| "broadcast"` |  |
| `rules[].when.fromDomain` | `array of string` |  |
| `rules[].steps`required | `array of object` |  |
| `rules[].steps[].connectionId`required | `string` |  |
| `rules[].steps[].weight` | `number` |  |
| `rules[].steps[].dailyCap` | `integer` |  |
| `rules[].steps[].enabled` | `boolean` |  |
| `rules[].steps[].stream` | `"transactional" \| "broadcast"` | Stream separation: only `transactional` or only `broadcast` (campaign) email uses this provider. Unset: both. |
| `fallback` | `"queue_until_reset" \| "fail"` |  |
| `messageTypes` | `array of "transactional" \| "broadcast"` |  |
| `isDefault` | `boolean` |  |

### Responses

`201` Success

```
{
  "id": string,
  "object": "policy",
  "name": string,
  "description": string or null,
  "strategy": "priority" | "weighted" | "round_robin",
  "steps": [{
    "connectionId": string,
    "weight": number,
    "dailyCap": integer,
    "enabled": boolean,
    "stream": "transactional" | "broadcast"
  }],
  "rules": [{
    "when": {
      "recipientDomain": [string],
      "tag": [string],
      "type": "transactional" | "broadcast",
      "fromDomain": [string]
    },
    "steps": [{ … }]
  }],
  "fallback": "queue_until_reset" | "fail",
  "messageTypes": ["transactional" | "broadcast"],
  "isDefault": boolean,
  "createdAt": string
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Get a policy

GET `/v1/policies/{id}`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "policy",
  "name": string,
  "description": string or null,
  "strategy": "priority" | "weighted" | "round_robin",
  "steps": [{
    "connectionId": string,
    "weight": number,
    "dailyCap": integer,
    "enabled": boolean,
    "stream": "transactional" | "broadcast"
  }],
  "rules": [{
    "when": {
      "recipientDomain": [string],
      "tag": [string],
      "type": "transactional" | "broadcast",
      "fromDomain": [string]
    },
    "steps": [{ … }]
  }],
  "fallback": "queue_until_reset" | "fail",
  "messageTypes": ["transactional" | "broadcast"],
  "isDefault": boolean,
  "createdAt": string
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Update a policy (reorder steps, caps, rules, fallback)

PATCH `/v1/policies/{id}`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name` | `string` |  |
| `description` | `string or null` |  |
| `strategy` | `"priority" \| "weighted" \| "round_robin"` |  |
| `steps` | `array of object` |  |
| `steps[].connectionId`required | `string` |  |
| `steps[].weight` | `number` |  |
| `steps[].dailyCap` | `integer` |  |
| `steps[].enabled` | `boolean` |  |
| `steps[].stream` | `"transactional" \| "broadcast"` | Stream separation: only `transactional` or only `broadcast` (campaign) email uses this provider. Unset: both. |
| `rules` | `array of object` |  |
| `rules[].when`required | `object` |  |
| `rules[].when.recipientDomain` | `array of string` |  |
| `rules[].when.tag` | `array of string` |  |
| `rules[].when.type` | `"transactional" \| "broadcast"` |  |
| `rules[].when.fromDomain` | `array of string` |  |
| `rules[].steps`required | `array of object` |  |
| `rules[].steps[].connectionId`required | `string` |  |
| `rules[].steps[].weight` | `number` |  |
| `rules[].steps[].dailyCap` | `integer` |  |
| `rules[].steps[].enabled` | `boolean` |  |
| `rules[].steps[].stream` | `"transactional" \| "broadcast"` | Stream separation: only `transactional` or only `broadcast` (campaign) email uses this provider. Unset: both. |
| `fallback` | `"queue_until_reset" \| "fail"` |  |
| `messageTypes` | `array of "transactional" \| "broadcast"` |  |
| `isDefault` | `boolean` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "policy",
  "name": string,
  "description": string or null,
  "strategy": "priority" | "weighted" | "round_robin",
  "steps": [{
    "connectionId": string,
    "weight": number,
    "dailyCap": integer,
    "enabled": boolean,
    "stream": "transactional" | "broadcast"
  }],
  "rules": [{
    "when": {
      "recipientDomain": [string],
      "tag": [string],
      "type": "transactional" | "broadcast",
      "fromDomain": [string]
    },
    "steps": [{ … }]
  }],
  "fallback": "queue_until_reset" | "fail",
  "messageTypes": ["transactional" | "broadcast"],
  "isDefault": boolean,
  "createdAt": string
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Delete a policy

DELETE `/v1/policies/{id}`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Dry-run: which provider would send this right now, and why the others would not

POST `/v1/route/preview`

Applies the same rules as sending: the From domain must be verified on a provider (unless the provider needs no per-domain verification) and the provider must be among the domain's allowed providers. `error` is set when no provider can send for the From domain (`no_provider_for_domain`).

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `from`required | `string` |  |
| `to`required | `array of string` |  |
| `type` | `"transactional" \| "broadcast"` | Default "transactional". |
| `tags` | `array of string` |  |
| `policy` | `string` |  |

### Responses

`200` Success

```
{
  "domain": {
    "id": string,
    "name": string,
    "allowedConnections": [string] or null
  },
  "error": {
    "code": "no_provider_for_domain",
    "message": string
  },
  "candidates": [{
    "connectionId": string,
    "provider": string,
    "eligible": boolean,
    "reason": string or null,
    "remainingToday": number or null,
    "code": "not_found" | "inactive" | "circuit_open" | "stream" | "broadcast_not_allowed" | "reputation" | "domain_not_allowed" | "domain_not_verified" | "quota_daily" | "quota_monthly" | …,
    "preferred": "campaign" | "recipient" | null,
    "lastResort": boolean
  }]
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
