Read sending allowance
GET /v1/outbound/quota
Read as Markdown ↗GET /v1/outbound/quota
Requires an API key: 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 untilsufficient_capacity_at, whichRetry-Afteralso 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.
curl example
Supply CHERAMI_API_KEY privately.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/outbound/quota" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 200
Success.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/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
unauthorized: Send a valid API key as Authorization: Bearer <key>. If the key stopped working, get a new one through recovery.
X-Request-ID: Identifies this request; include it when reporting a problem.WWW-Authenticate:"Bearer"
Content type: application/json.
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.
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.
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
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
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. |