# 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 an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

Returns the account's sending allowance: how many recipients all its inboxes together can send to in a rolling 24 hours.

Every To, Cc and Bcc entry uses one unit, repeats included. Accepted and `unknown` sends count; `rejected` ones don't. Bounces and deleting mail or inboxes don't give units back. Units return 24 hours after the send that used them; `next_capacity_at` and `next_capacity_amount` say when the next ones return and how many.

A send that needs more than `remaining` returns `429 outbound_limit_reached`, and nothing is sent or charged. Its `reason` says what to do:

* `temporary_exhaustion`: wait until `sufficient_capacity_at`, which `Retry-After` also gives.
* `message_exceeds_allowance`: the message has more recipients than the whole allowance, so waiting won't help. Send to fewer recipients, or [request a larger allowance](https://cherami.to/docs/guides/support).

## curl example [#curl-example]

Supply `CHERAMI_API_KEY` privately.

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

Success.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

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": "Send feedback describing the workflow and the inbox or sending capacity it needs, or email hello@cherami.to. Feedback works with no free inbox slot or sending allowance, and replies go to the account owner's email.",
  "policy_url": "https://cherami.to/pricing"
}
```

### HTTP 401 [#http-401]

`unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-404]

`not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 503 [#http-503]

`outbound_unavailable`: The request failed. If it was a send, reply or forward, its outcome is unknown: repeat it with the same idempotency key and unchanged payload within 24 hours of the first request; without a key, check sent messages before sending again. Retry a read.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

## Schema: Quota [#schema-quota]

| Field                  | Required | Type                     | Meaning and constraints                                                |
| ---------------------- | -------- | ------------------------ | ---------------------------------------------------------------------- |
| `allowance`            | Yes      | integer                  | Recipients the account can send to in any 24 hours. `minimum`: `0`     |
| `used`                 | Yes      | integer                  | Recipients charged in the last 24 hours. `minimum`: `0`                |
| `remaining`            | Yes      | integer                  | Recipients you can send to now. `minimum`: `0`                         |
| `next_capacity_at`     | Yes      | string or null           | When the next units return; null when nothing is charged.              |
| `next_capacity_amount` | Yes      | integer                  | Recipients that become available at next\_capacity\_at. `minimum`: `0` |
| `window_hours`         | Yes      | `24`                     |                                                                        |
| `unit`                 | Yes      | `"recipient_deliveries"` | One unit per To, Cc or Bcc recipient.                                  |
| `increase_request`     | Yes      | string                   | How to ask for a larger allowance.                                     |
| `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 | Code to handle. Handle a code you don't recognize by its HTTP status. |
| `message` | Yes      | string | Explanation of this case; its wording can change.                     |

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