Rate limits and request limits
The rate limit
Your organisation can make 50 requests a second, with bursts of up to 100, by default. The limit is shared by all your keys and all endpoints. A bulk or batch send counts as one request, however many recipients it has, so send many messages in one request rather than one request each.
Every response to a request that reaches the rate limit carries its state, errors included:
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests a second you can sustain |
RateLimit-Remaining | Requests left right now |
RateLimit-Reset | Seconds until your full allowance is back |
Over the limit, the API answers 429 rate_limited with a Retry-After header in seconds, and does nothing else: nothing is sent or charged.
These responses come before the rate limit is checked, so they carry no rate-limit headers: a 401; the 429 for an address blocked after too many failed authentications, which has its own Retry-After; a 403 for email_not_verified, tenant_suspended or insufficient_scope; a 413 payload_too_large; and a 415 unsupported_media_type. While our rate limiter is unavailable, requests are served without the check and without the headers. Do not depend on them.
Request limits
| Limit | Default |
|---|---|
| Recipients or items in one bulk or batch send | 1,000 |
| Body of a bulk or batch send | 5 MiB |
| Body of any other request | 256 KiB |
| Segments in one message | 10 |
send_at | Between 1 minute and 90 days from now |
| Messages in one page of a list | 100 |
| Time range of one list request | 92 days |
The rate limit can differ for your organisation, and each default can change; the responses give the current values. Over the recipient limit a send answers 422 too_many_recipients with the limit, and a body over its size answers 413 payload_too_large.
Compression
Send Accept-Encoding: gzip and responses of 500 bytes or more come back compressed. Request bodies must not be compressed: a compressed body answers 415 unsupported_media_type.