---
title: "Read sending allowance"
method: GET
path: "/v1/outbound/quota"
tags: ["sending"]
---

# Read sending allowance

`GET /v1/outbound/quota`

## Request

- Base URL: `https://cherami.to`
- URL: `https://cherami.to/v1/outbound/quota`
- Auth: HTTP bearer

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

## Response `200`

Success.

- Quota
  - `allowance` integer, required: Recipients the account can send to in any 24 hours.
  - `used` integer, required: Recipients charged in the last 24 hours.
  - `remaining` integer, required: Recipients you can send to now.
  - `next_capacity_at` string, date-time, nullable, required: UTC timestamp with milliseconds.
  - `next_capacity_amount` integer, required: Recipients that become available at next_capacity_at.
  - `window_hours` unknown, required
  - `unit` 'recipient_deliveries', required: One unit per To, Cc or Bcc recipient.
  - `increase_request` string, required: How to ask for a larger allowance.
  - `policy_url` string, required

## Other responses

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

---

[API](https://skmtc.dev/cherami/apis/cherami-http-api.md) · [All operations](https://skmtc.dev/cherami/apis/cherami-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cherami/apis/cherami-http-api/revisions/7bd993d538af?raw)