Routing
Policies decide provider order, caps, rules and what happens when quota runs out.
List routing policies
GET /v1/policies
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Create a routing policy
POST /v1/policies
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
namerequired | string | |
description | string or null | |
strategy | "priority" | "weighted" | "round_robin" | |
stepsrequired | array of object | |
steps[].connectionIdrequired | 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[].whenrequired | 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[].stepsrequired | array of object | |
rules[].steps[].connectionIdrequired | 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
name | string | |
description | string or null | |
strategy | "priority" | "weighted" | "round_robin" | |
steps | array of object | |
steps[].connectionIdrequired | 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[].whenrequired | 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[].stepsrequired | array of object | |
rules[].steps[].connectionIdrequired | 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Field | Type | Description |
|---|---|---|
fromrequired | string | |
torequired | array of string | |
type | "transactional" | "broadcast" | Default "transactional". |
tags | array of string | |
policy | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)