# Read sending allowance

GET /v1/outbound/quota

Source: https://cherami.to/docs/api/sending/get-outbound-quota



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`GET /v1/outbound/quota`

Requires a [Claim-issued API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

Returns the current account-wide sending allowance.

Every To/Cc/Bcc entry costs one, including repeats. All inboxes share this allowance. Accepted and unknown submissions count; rejected submissions do not when the outcome is saved. Later bounces and message or inbox deletion do not refund charges.

Sending with insufficient capacity returns `429` with `error.code: "outbound_limit_reached"`, an actionable `error.message`, `quota` containing the allowance fields, and the capacity details in the response schema.

`Retry-After` is supplied from `sufficient_capacity_at`, not the first charge expiry. No `Retry-After` is supplied when the message exceeds the entire account allowance: waiting cannot fix that. A concurrent release can make the returned snapshot already sufficient even though the earlier check blocked the request. Neither an estimate nor available Cherami capacity guarantees provider acceptance.

A quota-blocked send does not submit a message. It does not override recovery rules for an earlier uncertain attempt. Receiving, reading, organizing mail, saving drafts and feedback remain available when sending allowance runs out. Request inbox or sending increases through [feedback](https://cherami.to/docs/api/feedback) or [hello@cherami.to](mailto:hello@cherami.to); requests are reviewed manually. [Allowance policy](https://cherami.to/pricing).

## curl example [#curl-example]

Replace resource-ID placeholders with returned IDs. Supply `CHERAMI_API_KEY` through your private shell environment.

```sh
curl --silent --show-error --include --request GET \
  "https://cherami.to/v1/outbound/quota" \
  --header "Authorization: Bearer $CHERAMI_API_KEY"
```

## Responses [#responses]

### HTTP 200 [#http-200]

Successful operation; inspect resource state and outcome fields.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Quota](#schema-quota)

```json
{
  "allowance": 25,
  "used": 0,
  "remaining": 25,
  "next_capacity_at": null,
  "next_capacity_amount": 0,
  "window_hours": 24,
  "unit": "recipient_deliveries",
  "increase_request": "Describe your workflow and desired capacity in feedback or email hello@cherami.to.",
  "policy_url": "https://cherami.to/pricing"
}
```

### HTTP 401 [#http-401]

`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.

* `X-Request-ID`: Support correlation ID, not an idempotency key.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-404]

`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 503 [#http-503]

`outbound_unavailable`: Outbound operation failed and a send's outcome may be unknown. Recover using the original key and unchanged payload within its window, or inspect sent messages.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

## Schema: Quota [#schema-quota]

| Field                  | Required | Type                     | Meaning and constraints |
| ---------------------- | -------- | ------------------------ | ----------------------- |
| `allowance`            | Yes      | integer                  | `minimum`: `0`          |
| `used`                 | Yes      | integer                  | `minimum`: `0`          |
| `remaining`            | Yes      | integer                  | `minimum`: `0`          |
| `next_capacity_at`     | Yes      | string or null           |                         |
| `next_capacity_amount` | Yes      | integer                  | `minimum`: `0`          |
| `window_hours`         | Yes      | `24`                     |                         |
| `unit`                 | Yes      | `"recipient_deliveries"` |                         |
| `increase_request`     | Yes      | string                   |                         |
| `policy_url`           | Yes      | string                   |                         |

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                                                       |
| --------- | -------- | ------ | --------------------------------------------------------------------------------------------- |
| `code`    | Yes      | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
| `message` | Yes      | string | Human-readable context, not a stable string to match.                                         |

[HTTP conventions, errors and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)