Reference
Usage, limits, and rate limiting
What counts toward your allowance, what happens past it, and how to check where you stand.
API send allowance
Mini, Professional, and Enterprise include a monthly allowance of API sends: agent mail and transactional email sent through the API (POST /emails and POST /emails/batch) or SMTP relay. Every send counts once, with up to 50 recipients. Mail sent from your team's mailboxes doesn't count toward it and isn't billed.
Flex includes 500 API sends a month; they reset each month. It sells more in prepaid 1,000-send blocks, which carry over, charged as the balance runs out; auto top-up can buy a block when the balance is empty. If a block cannot be charged, API sends pause until the charge is retried.
Past the monthly allowance, sending continues and extra API sends are billed per 1,000, up to a cap of twice the allowance by default:
| Plan | API sends / month | Sending stops at |
|---|---|---|
| Flex | 500 included + prepaid | When the included sends and prepaid balance are empty |
| Mini | 10K | 20K |
| Professional | 40K | 80K |
| Enterprise | 100K | 200K |
At the cap, sends fail with 429 monthly_quota_exceeded until the next billing period. If a payment is overdue, sending is held to the included allowance. See pricing for per-1,000 rates.
Rate limiting
Chebu limits how quickly requests can arrive. If you send too fast, requests fail with 429 rate_limit_exceeded. Responses carry these headers so you can back off:
| Header | Meaning |
|---|---|
ratelimit-limit | Requests allowed per window. |
ratelimit-remaining | Requests left in the current window. |
ratelimit-reset | Seconds until the window resets. |
retry-after | On a 429, seconds to wait before retrying. |
Wait for retry-after and try again, or use batch sends to send more per request.
Size limits
| Limit | Value |
|---|---|
Recipients per email (to + cc + bcc) | 50 |
| Attachments per email, total | 40 MB |
| Emails per batch | 100 |
| Batch request body | 20 MB |
| Scheduling window | 30 days |
| Idempotency key lifetime | 24 hours |
Paused sending
To protect deliverability for everyone, Chebu watches bounce and complaint rates over the last 7 days once a workspace has sent at least 200 emails. At a 10% bounce rate or a 0.5% complaint rate, sending pauses until our team reviews it, and requests fail with 403 workspace_paused. Keeping lists clean and honoring the suppression list keeps you well below that.
Check usage
/usagecurl https://api.chebu.io/usage \
-H "Authorization: Bearer $CHEBU_API_KEY"{
"period_start": "2026-09-01T00:00:00Z",
"period_end": "2026-10-01T00:00:00Z",
"plan": "professional",
"transactional": { "used": 18240, "included": 40000, "cap": 80000 },
"storage": {
"used_bytes": 21474836480,
"included_bytes": 536870912000
},
"domains": { "used": 2, "included": 10, "extra": 0 },
"mailboxes": { "used": 14, "included": 30, "extra": 0 }
}