---
title: "Sending providers API"
description: "Sending providers in the OneSend API: 11 endpoints. Provider accounts connected to this workspace (shown as Sending providers in the dashboard). Credentials are encrypted at rest and never returned."
url: https://onesend.email/docs/api-reference/sending-providers/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Sending providers

Provider accounts connected to this workspace (shown as Sending providers in the dashboard). Credentials are encrypted at rest and never returned.

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 connected provider accounts with today's usage

GET `/v1/connections`

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

### Responses

`200` Success

```
{
  "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**

- `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`)

## 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

application/json, required.

| Field | Type | Description |
|---|---|---|
| `provider`required | `string` |  |
| `name`required | `string` |  |
| `credentials`required | `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

`201` Success

```
{
  "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**

- `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`.
- `402` Payment required (type `payment_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) or `domain_limit` (sending domains); `details.limit`, `details.used` and `details.upgradeUrl` say what and where to upgrade.
- `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 connection

GET `/v1/connections/{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": "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**

- `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 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 |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| 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

`200` Success

```
{
  "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**

- `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`.
- `402` Payment required (type `payment_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) or `domain_limit` (sending domains); `details.limit`, `details.used` and `details.upgradeUrl` say what and where to upgrade.
- `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`)

## 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 |
|---|---|---|---|
| `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`)

## 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 |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "ok": boolean,
  "account": object or null,
  "error": string or null,
  "latencyMs": number
}
```

**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`)

## 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 |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "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**

- `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`)

## 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 |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "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**

- `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`)

## 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 |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`202` Success

```
{
  "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**

- `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`)

## 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 |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "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**

- `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`)

## 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 |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "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**

- `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`)
