Sending providers
Provider accounts connected to this workspace (shown as Sending providers in the dashboard). Credentials are encrypted at rest and never returned.
List connected provider accounts with today's usage
GET /v1/connections
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"data": [{
"id": string,
"object": "connection",
"provider": string,
"name": string,
"status": "active" | "paused" | "error",
"statusReason": string or null,
"config": object,
"allowBroadcast": boolean,
"dailyLimit": number or null,
"monthlyLimit": number or null,
"perSecondLimit": number or null,
"quotaSource": "detected" | "default" | "manual" | "learned",
"health": number,
"circuitOpenUntil": string or null,
"usage": {
"today": number,
"thisMonth": number,
"remainingToday": number or null
},
"webhookUrl": string or null,
"credentialHints": map of string,
"webhookSeenAt": string or null,
"reputation": {
"status": "ok" | "marketing_paused" | "paused",
"since": string or null,
"code": "bounce_rate" | "complaint_rate" | null,
"reason": string or null,
"value": number or null,
"threshold": number or null,
"window": "24h" | "7d" | null,
"sample": number or null,
"baselineAt": string or null,
"evaluatedAt": string or null,
"rates": { … },
"manual": 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)
Connect a provider account
POST /v1/connections
Validates the credentials against the provider, detects quota where the provider exposes it (else uses the known free tier), adds it to the default routing policy and registers delivery webhooks when the instance has a public URL.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
providerrequired | string | |
namerequired | string | |
credentialsrequired | map of string | |
config | object | |
allowBroadcast | boolean | |
dailyLimit | integer or null | |
monthlyLimit | integer or null | |
priority | integer | Placement in the default routing policy: 1000 or more puts the new connection first; otherwise it goes after your other providers (before the Sandbox). onesend_cloud connections always go first. 0 to 100000. |
Responses
{
"id": string,
"object": "connection",
"provider": string,
"name": string,
"status": "active" | "paused" | "error",
"statusReason": string or null,
"config": object,
"allowBroadcast": boolean,
"dailyLimit": number or null,
"monthlyLimit": number or null,
"perSecondLimit": number or null,
"quotaSource": "detected" | "default" | "manual" | "learned",
"health": number,
"circuitOpenUntil": string or null,
"usage": {
"today": number,
"thisMonth": number,
"remainingToday": number or null
},
"webhookUrl": string or null,
"credentialHints": map of string,
"webhookSeenAt": string or null,
"reputation": {
"status": "ok" | "marketing_paused" | "paused",
"since": string or null,
"code": "bounce_rate" | "complaint_rate" | null,
"reason": string or null,
"value": number or null,
"threshold": number or null,
"window": "24h" | "7d" | null,
"sample": number or null,
"baselineAt": string or null,
"evaluatedAt": string or null,
"rates": {
"h24": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
},
"d7": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
}
},
"manual": boolean
},
"createdAt": string
}Errors: 400, 401, 402, 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.402Payment required (typepayment_required), only on the cloud edition when cloud plans are enabled (they are off by default): the plan's limit is reached,plan_limit(sending providers in use) ordomain_limit(sending domains);details.limit,details.usedanddetails.upgradeUrlsay what and where to upgrade.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 connection
GET /v1/connections/{id}
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"object": "connection",
"provider": string,
"name": string,
"status": "active" | "paused" | "error",
"statusReason": string or null,
"config": object,
"allowBroadcast": boolean,
"dailyLimit": number or null,
"monthlyLimit": number or null,
"perSecondLimit": number or null,
"quotaSource": "detected" | "default" | "manual" | "learned",
"health": number,
"circuitOpenUntil": string or null,
"usage": {
"today": number,
"thisMonth": number,
"remainingToday": number or null
},
"webhookUrl": string or null,
"credentialHints": map of string,
"webhookSeenAt": string or null,
"reputation": {
"status": "ok" | "marketing_paused" | "paused",
"since": string or null,
"code": "bounce_rate" | "complaint_rate" | null,
"reason": string or null,
"value": number or null,
"threshold": number or null,
"window": "24h" | "7d" | null,
"sample": number or null,
"baselineAt": string or null,
"evaluatedAt": string or null,
"rates": {
"h24": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
},
"d7": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
}
},
"manual": 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 connection (rename, pause, limits, credentials)
PATCH /v1/connections/{id}
Pausing (status: "paused") needs a signed-in admin: API keys get 403 session_required (pausing can stop all delivery, the owners' security alerts included). Changing where the credentials are sent (URL, host, port, TLS) needs every credential again in the same request (400 credentials_required).
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
provider | string | |
name | string | |
credentials | map of string | |
config | object | |
allowBroadcast | boolean | |
dailyLimit | integer or null | |
monthlyLimit | integer or null | |
status | "active" | "paused" |
Responses
{
"id": string,
"object": "connection",
"provider": string,
"name": string,
"status": "active" | "paused" | "error",
"statusReason": string or null,
"config": object,
"allowBroadcast": boolean,
"dailyLimit": number or null,
"monthlyLimit": number or null,
"perSecondLimit": number or null,
"quotaSource": "detected" | "default" | "manual" | "learned",
"health": number,
"circuitOpenUntil": string or null,
"usage": {
"today": number,
"thisMonth": number,
"remainingToday": number or null
},
"webhookUrl": string or null,
"credentialHints": map of string,
"webhookSeenAt": string or null,
"reputation": {
"status": "ok" | "marketing_paused" | "paused",
"since": string or null,
"code": "bounce_rate" | "complaint_rate" | null,
"reason": string or null,
"value": number or null,
"threshold": number or null,
"window": "24h" | "7d" | null,
"sample": number or null,
"baselineAt": string or null,
"evaluatedAt": string or null,
"rates": {
"h24": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
},
"d7": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
}
},
"manual": boolean
},
"createdAt": string
}Errors: 400, 401, 402, 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.402Payment required (typepayment_required), only on the cloud edition when cloud plans are enabled (they are off by default): the plan's limit is reached,plan_limit(sending providers in use) ordomain_limit(sending domains);details.limit,details.usedanddetails.upgradeUrlsay what and where to upgrade.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)
Disconnect a provider
DELETE /v1/connections/{id}
Deletes the stored credentials and takes the provider out of every routing policy and rule. Email still waiting to send goes through the next provider of its policy when it is sent (or follows the policy's fallback when none is left); sent email and logs are kept. For a personal mailbox used as a sending provider, "Use as a sending provider" is turned off on that account; the account stays connected.
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)
Check the credentials still work
POST /v1/connections/{id}/test
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"ok": boolean,
"account": object or null,
"error": string or null,
"latencyMs": number
}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)
Health, affinity, webhooks and sync of a connection
GET /v1/connections/{id}/insights
Hard bounce and complaint rates over 24 hours and 7 days against the thresholds and whether the provider is in rotation; the share of recipients whose preferred provider it is; when a provider webhook last arrived and whether delivery status is polled instead; and its suppression sync state.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"connectionId": string,
"health": {
"status": "ok" | "marketing_paused" | "paused",
"since": string or null,
"code": "bounce_rate" | "complaint_rate" | null,
"reason": string or null,
"value": number or null,
"threshold": number or null,
"window": "24h" | "7d" | null,
"sample": number or null,
"baselineAt": string or null,
"evaluatedAt": string or null,
"rates": {
"h24": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
},
"d7": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
}
},
"manual": boolean,
"thresholds": {
"enabled": boolean,
"bounceRate": number,
"complaintRate": number,
"minSample24h": number,
"minSample7d": number,
"severeFactor": number,
"cooldownHours": number
}
},
"affinity": {
"recipients": number,
"share": number
},
"webhooks": {
"supported": boolean,
"lastSeenAt": string or null,
"recent": boolean,
"polling": boolean,
"pollingSupported": boolean
},
"sync": [{
"connectionId": string,
"provider": string,
"name": string,
"kind": "suppressions" | "suppressions_push" | "status",
"supported": boolean,
"status": "idle" | "running" | "error" | "unsupported",
"inProgress": boolean,
"lastRunAt": 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)
Put a provider back in rotation
POST /v1/connections/{id}/health/reset
Ends an automatic removal for high bounce or complaint rates now; the provider is judged on email sent from now on.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"status": "ok" | "marketing_paused" | "paused",
"since": string or null,
"code": "bounce_rate" | "complaint_rate" | null,
"reason": string or null,
"value": number or null,
"threshold": number or null,
"window": "24h" | "7d" | null,
"sample": number or null,
"baselineAt": string or null,
"evaluatedAt": string or null,
"rates": {
"h24": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
},
"d7": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
}
},
"manual": boolean
}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)
Import this provider's suppression list now
POST /v1/connections/{id}/suppressions/sync
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"data": [{
"connectionId": string,
"provider": string,
"name": string,
"kind": "suppressions" | "suppressions_push" | "status",
"supported": boolean,
"status": "idle" | "running" | "error" | "unsupported",
"inProgress": boolean,
"lastRunAt": string or null,
"lastSuccessAt": string or null,
"nextRunAt": string or null,
"lastResult": {
"ok": boolean,
"at": string,
"imported": number,
"updated": number,
"seen": number,
"pushed": number,
"polled": number,
"events": number,
"pages": number,
"done": boolean,
"error": string or null,
"unsupported": boolean
},
"total": number
}]
}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)
Rotate the provider webhook URL
POST /v1/connections/{id}/rotate-webhook-url
Issues a new secret token for this connection's webhookUrl; the old URL stops working at once. OneSend re-registers the new URL with providers that support it; for others, update the URL in the provider dashboard.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"object": "connection",
"provider": string,
"name": string,
"status": "active" | "paused" | "error",
"statusReason": string or null,
"config": object,
"allowBroadcast": boolean,
"dailyLimit": number or null,
"monthlyLimit": number or null,
"perSecondLimit": number or null,
"quotaSource": "detected" | "default" | "manual" | "learned",
"health": number,
"circuitOpenUntil": string or null,
"usage": {
"today": number,
"thisMonth": number,
"remainingToday": number or null
},
"webhookUrl": string or null,
"credentialHints": map of string,
"webhookSeenAt": string or null,
"reputation": {
"status": "ok" | "marketing_paused" | "paused",
"since": string or null,
"code": "bounce_rate" | "complaint_rate" | null,
"reason": string or null,
"value": number or null,
"threshold": number or null,
"window": "24h" | "7d" | null,
"sample": number or null,
"baselineAt": string or null,
"evaluatedAt": string or null,
"rates": {
"h24": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
},
"d7": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
}
},
"manual": boolean
},
"createdAt": string
}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)
Re-detect quota from the provider
POST /v1/connections/{id}/refresh-quota
Manual limits are kept unless the provider reports a lower one.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"object": "connection",
"provider": string,
"name": string,
"status": "active" | "paused" | "error",
"statusReason": string or null,
"config": object,
"allowBroadcast": boolean,
"dailyLimit": number or null,
"monthlyLimit": number or null,
"perSecondLimit": number or null,
"quotaSource": "detected" | "default" | "manual" | "learned",
"health": number,
"circuitOpenUntil": string or null,
"usage": {
"today": number,
"thisMonth": number,
"remainingToday": number or null
},
"webhookUrl": string or null,
"credentialHints": map of string,
"webhookSeenAt": string or null,
"reputation": {
"status": "ok" | "marketing_paused" | "paused",
"since": string or null,
"code": "bounce_rate" | "complaint_rate" | null,
"reason": string or null,
"value": number or null,
"threshold": number or null,
"window": "24h" | "7d" | null,
"sample": number or null,
"baselineAt": string or null,
"evaluatedAt": string or null,
"rates": {
"h24": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
},
"d7": {
"sent": number,
"bounced": number,
"complained": number,
"bounceRate": number,
"complaintRate": number
}
},
"manual": boolean
},
"createdAt": string
}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)