Rate limits
Each API key gets its own limits, counted over a sliding window. Every endpoint belongs to a tier, and the tier sets the quota.
Last updated
Tiers
| Tier | Limit | Description |
|---|---|---|
| read | 1,000 / min | GET requests (list, retrieve). |
| write | 200 / min | POST, PATCH, DELETE (create, update, delete). |
| send | 100 / min | Sending email (POST /v1/messages, POST /v1/messages/:id/reply, POST /v1/threads/:id/reply, POST /v1/newsletters/:id/test-send, POST /v1/newsletters/:id/schedule). |
| verification | 1 / min | Domain DNS checks (GET /v1/domains/:id/dns-records and POST /v1/domains/:id/verification). |
Response headers
Every response that goes through the main API rate limiter has these headers:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Most requests allowed in the current window. |
| X-RateLimit-Remaining | Requests left in the current window. |
| X-RateLimit-Reset | Unix timestamp (seconds) when the window resets. |
| Retry-After | Seconds to wait before you retry. Only on 429 responses. |
Mailbox export cap
On top of the tiers, a mailbox can make at most 24 exports in any 24 hours. POST /mailboxes/{id}/exports returns 429 past that, with a Retry-After header with the seconds until the oldest export drops out of the window and frees a slot. The cap counts per mailbox, not per API key, and is the same on every plan.
An export reused from the last 15 minutes, or one that is already running, doesn't count. Exports are backups, not a way to check for new mail. Use GET /mailboxes/{id}/inbox/messages or subscribe to the mailbox.export.completed webhook instead of exporting over and over.
Failed authentication
Requests with a missing, invalid, revoked or expired API key are also limited per IP address. After 60 rejected keys from one address in a minute, every request from that address gets 429 with a Retry-After header until the window clears, including requests that carry a valid key. Requests with a valid key never count toward it.
Tokenized upload URLs, such as the upload_url returned for a staged attachment, accept 120 requests per minute from one IP address.
See your API usage
Organization owners and admins can open Developer → API keys to see the last 60 complete UTC minutes, for the whole organization or for one key. Limits stay per API key on every plan. The organization total is not a shared quota.
For each tier you see accepted requests, main-limiter rejections, how many accepted requests succeeded or failed, the most attempts in any one UTC minute, and the average duration in milliseconds. That per-minute peak helps you debug. It is not the sliding window the quota uses. Rejections from other limits, such as the mailbox export cap, are not counted as main-limiter throttles. If the counters are briefly out of reach, the page says unavailable rather than showing zero.
The counters expire after 3 hours and hold no message content. Main-limiter 429 counts are kept apart from request logs, so the logs alone don't show every throttled attempt. Counting started when this page shipped. Older requests aren't in it.
If a tier has at least 20 rejected requests in at least five of the last ten complete minutes, the organization gets a notification. The check runs every five minutes and sends at most one notification per organization per 24 hours.
Handling 429 responses
Go over the limit and the API returns 429 with a Retry-After header: the seconds to wait. Wait that long before you retry, don't keep hammering the endpoint, and add some random jitter if several workers retry at once.
The TypeScript and Python SDKs read the Retry-After header, in seconds or as an HTTP date, before the response body. They retry reads and other safe methods on their own, and POST, PATCH, or PUT requests that carry an idempotency key. They never retry a DELETE. If the server asks for more than 60 seconds, the SDK returns the error instead. Schedule the retry yourself, with the same idempotency key.
For new inbound mail, subscribe to the message.received webhook instead of listing messages over and over. For operations with no event, poll, but cap how often.