Read sending allowance
GET /v1/outbound/quota
Read as Markdown ↗GET /v1/outbound/quota
Requires a Claim-issued API key: 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 or hello@cherami.to; requests are reviewed manually. Allowance policy.
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/outbound/quota" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 200
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
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": "Describe your workflow and desired capacity in feedback or email hello@cherami.to.",
"policy_url": "https://cherami.to/pricing"
}HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
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.
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.
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
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
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 · Download OpenAPI 3.1