Usage limits
Understand request limits, email and WhatsApp allowances, and how to recover when you reach them.
Request sizes
| Operation | Limit |
|---|---|
| List domains or email logs | Up to 100 items per response; default 50 |
| Email recipients | 1–100 addresses per supplied recipient array |
| CC and BCC | Supported only with one primary recipient; to, cc, and bcc together at most 50 addresses |
| Page number on page-based lists | Up to 10,000 |
| Email analytics date range | Up to 366 days |
| Template versions | Up to 100 per response; default 50 |
| Email subject | Up to 500 characters |
| Sender display name | Up to 100 characters for transactional sends |
| WhatsApp recipients | One per request |
| WhatsApp variable values | Up to 1,024 characters each |
Idempotency-Key for WhatsApp sends | Up to 200 characters |
Sending and domain allowances
Sending allowances and the number of domains available depend on your subscription. They apply to the whole organization: domains in every project count toward the same domain allowance.
These responses need an allowance change, not a retry. Each has error: "quota_exceeded" (HTTP 429) unless noted, and a code:
| Code | Returned when |
|---|---|
email_max_domains_exceeded | Creating a domain would exceed the plan's domains. |
email_daily_limit_exceeded | A send would exceed today's recipient allowance. To, CC, and BCC recipients all count; suppressed recipients do not. A scheduled send counts against the day it is scheduled for, including everything already scheduled for that day. |
email_max_scheduled_recipients_exceeded | A scheduled send would exceed the recipients your plan allows to wait in scheduled emails at once. Recipients of a scheduled email you cancel keep counting for 24 hours. |
included_usage_exhausted | The plan's included emails for the period are used up. |
wallet_balance_insufficient | Paid usage is on, but the wallet cannot cover the send. |
paid_usage_disabled | HTTP 403: the included emails are used up and paid usage is off. |
Rapid retries do not increase your quota. A retried send with the same Idempotency-Key still returns its original response.
WhatsApp allowances
Your plan includes a number of WhatsApp messages each billing period and a number of connected WhatsApp numbers for the whole organization. Beyond the included messages, each message is paid from your wallet and charged only once it is delivered. See Costs.
| Code | Returned when |
|---|---|
included_usage_exhausted | The plan's included WhatsApp messages are used up, and the plan has no paid messages. |
usage_spend_limit_exceeded | The message would go past your spending limit. |
wallet_balance_insufficient | The wallet cannot cover a message beyond the included ones. |
service_not_in_plan | Your plan doesn't include WhatsApp messages. |
paid_usage_disabled | HTTP 403: the included messages are used up and paid usage is off. |
WhatsApp also limits how many different customers your business can message in 24 hours. That limit is set by Meta, not by your plan: messages past it become failed. See Messaging limits.
Rate-limited requests
A rate-limited route returns HTTP 429. Your organization's requests per second depend on your plan; past them, requests return 429 with error: "quota_exceeded" and code api_rate_limit_per_second_exceeded for a moment. Repeated requests with invalid API keys from one network are also refused with 429 and code api_key_authentication_rate_limited for about a minute; check the key you are sending. When Retry-After is present, wait at least that many seconds before retrying. Do not assume a universal requests-per-second allowance across endpoints.
Use bounded exponential backoff with jitter for transient failures. Avoid retrying validation or permission errors until you have corrected the request.
Safe send retries
Reuse the same Idempotency-Key and payload when retrying the same send. Use a new key for a new message. The Node.js SDK accepts an explicit idempotencyKey option; store that value with your application operation so it survives a process restart.
See Send an email and Errors.