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 and errors are described in the overview.

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.

FieldTypeDescription
namerequiredstring
descriptionstring or null
strategy"priority" | "weighted" | "round_robin"
stepsrequiredarray of object
steps[].connectionIdrequiredstring
steps[].weightnumber
steps[].dailyCapinteger
steps[].enabledboolean
steps[].stream"transactional" | "broadcast"Stream separation: only transactional or only broadcast (campaign) email uses this provider. Unset: both.
rulesarray of object
rules[].whenrequiredobject
rules[].when.recipientDomainarray of string
rules[].when.tagarray of string
rules[].when.type"transactional" | "broadcast"
rules[].when.fromDomainarray of string
rules[].stepsrequiredarray of object
rules[].steps[].connectionIdrequiredstring
rules[].steps[].weightnumber
rules[].steps[].dailyCapinteger
rules[].steps[].enabledboolean
rules[].steps[].stream"transactional" | "broadcast"Stream separation: only transactional or only broadcast (campaign) email uses this provider. Unset: both.
fallback"queue_until_reset" | "fail"
messageTypesarray of "transactional" | "broadcast"
isDefaultboolean

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

NameInTypeDescription
idrequiredpathstring

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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
namestring
descriptionstring or null
strategy"priority" | "weighted" | "round_robin"
stepsarray of object
steps[].connectionIdrequiredstring
steps[].weightnumber
steps[].dailyCapinteger
steps[].enabledboolean
steps[].stream"transactional" | "broadcast"Stream separation: only transactional or only broadcast (campaign) email uses this provider. Unset: both.
rulesarray of object
rules[].whenrequiredobject
rules[].when.recipientDomainarray of string
rules[].when.tagarray of string
rules[].when.type"transactional" | "broadcast"
rules[].when.fromDomainarray of string
rules[].stepsrequiredarray of object
rules[].steps[].connectionIdrequiredstring
rules[].steps[].weightnumber
rules[].steps[].dailyCapinteger
rules[].steps[].enabledboolean
rules[].steps[].stream"transactional" | "broadcast"Stream separation: only transactional or only broadcast (campaign) email uses this provider. Unset: both.
fallback"queue_until_reset" | "fail"
messageTypesarray of "transactional" | "broadcast"
isDefaultboolean

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

NameInTypeDescription
idrequiredpathstring

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.

FieldTypeDescription
fromrequiredstring
torequiredarray of string
type"transactional" | "broadcast"Default "transactional".
tagsarray of string
policystring

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)