cherami.
API referenceSending and allowance

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

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.

Quota

{
  "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.

Error

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

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: Quota

FieldRequiredTypeMeaning and constraints
allowanceYesintegerRecipients the account can send to in any 24 hours. minimum: 0
usedYesintegerRecipients charged in the last 24 hours. minimum: 0
remainingYesintegerRecipients you can send to now. minimum: 0
next_capacity_atYesstring or nullWhen the next units return; null when nothing is charged.
next_capacity_amountYesintegerRecipients that become available at next_capacity_at. minimum: 0
window_hoursYes24
unitYes"recipient_deliveries"One unit per To, Cc or Bcc recipient.
increase_requestYesstringHow to ask for a larger allowance.
policy_urlYesstring

Schema: Error

FieldRequiredTypeMeaning and constraints
errorYesobject

error fields

FieldRequiredTypeMeaning and constraints
codeYesstringCode to handle. Handle a code you don't recognize by its HTTP status.
messageYesstringExplanation of this case; its wording can change.

Errors, limits and pagination · Download OpenAPI 3.1

On this page