Rate limits
Requests are limited in two layers: per-minute limits, per account and per IP, and hourly, daily and 30-day quotas behind them. A limited request returns 429 rate_limited with a Retry-After header in seconds, and a message that says how long in words.
Reads and writes are limited separately.
Per-minute limits are counted per session, API key or device credential when signed in, and per IP when not. They are approximate:
| Requests | A minute |
|---|---|
| Any request without a token, per IP | 600 |
| Any request with a token, or a device checking on its pairing session, per IP, shared by everyone signed in behind that address | 3,000 |
| A device checking on its own pairing session, per session | 60 |
| Sign-in, account creation and pairing-code lookups, per IP | 20 |
| Other endpoints that need no sign-in (plans, starting a pairing session, abuse reports), per IP | 60 |
| Reads that open no message bodies | 300 |
| Writes | 120 |
| Reads that open message bodies or attachments, including long-polls | 120 |
| Sending | 10 |
A long-poll of GET /workers/messages with wait counts once however long it is held, so an agent waiting for mail uses about three a minute. To show mail from many addresses, list them together with GET /messages rather than one request each.
The quotas you are likely to meet:
| Limit | Value |
|---|---|
| Messages received | Your plan’s monthly allowance, from 3,000 on Free to 4,000,000 on Fleet |
| Message bodies and attachments read | Per hour, scaled to the plan, at least 2,000 |
| Mail sent | 60 an hour per account, 20 an hour per device or agent, and 200 an hour per IP |
| Mail sent in a day | The plan’s limit: none on Free, 20 on Personal, 50 on Operator, 250 on Scale, 1,000 on Fleet, 5,000 on Enterprise. Past it, 429 daily_send_limit until 00:00 UTC. |
| Addresses created | Twice the plan’s address allowance a day, and at least 25 |
| Rolled-name lists | 300 an hour |
| Pairing-code lookups | 10 failed in 5 minutes, per account and per IP |
| Pairing sessions started | 120 an hour per IP |
| Accounts created | 10 an hour per IP |
| Sign-in challenges | 60 an hour per IP |
| Webhook tests and redeliveries | 60 an hour |
| Checkouts opened | 20 a day |
| Support requests opened | 5 a day |
| Support replies | 30 an hour |
| Custom domain checks | 60 an hour |
| Abuse reports | 30 an hour per IP |
Higher limits on Fleet and Enterprise
Section titled “Higher limits on Fleet and Enterprise”On Fleet, the per-account and per-device limits in the table run at three times the numbers shown: 180 sends an hour per account, 60 per device or agent, and three times the reads, addresses created, webhook tests, domain checks, checkouts and support requests. On Enterprise they run at five times, or at whatever is agreed with us. Mail sent per IP rises with them, to 600 an hour on Fleet and 1,000 on Enterprise, so the plan’s daily limit can be reached from one server. The other per-IP limits, the monthly message allowance and the daily send limit are the plan’s own and do not change. GET /usage reports the numbers your account actually runs at.
Rarely, sending can be paused for the rest of the day. It returns 503 sending_paused until 00:00 UTC, with a Retry-After header. Receiving is never affected.
GET /usage says how much of each of these the account has spent, and when each counter starts again.
Planning a bulk import or a migration that may hit these? Tell us first.
© Northlab Studios Ltd, trading as Mailcycle. Registered in England and Wales, company no. 17462734. Registered office: 167-169 Great Portland Street, London W1W 5PF.