Limits
Everything that is capped, in one place. Published rather than discovered — a limit you meet by surprise is a bug in the documentation.
At a glance
1–5/sec
API requests, per address
One without a key; 2, 3 or 5 with a key from a paid plan. Polling once a second is the intended pattern.
60/min
Free API requests, per minute
Per IP address, without a key. Paid plans have no per-minute cap.
1,000/day
Free API requests, per day
Per IP address, reset at 00:00 UTC. Paid plans have no daily cap.
5days
Message retention
From arrival, read or not. Hard limit.
5MB
Maximum message size
Refused at SMTP time, so the sender is told.
∞
Addresses per domain
Nothing is created in advance, so nothing is counted.
200
Messages returned per call
Default 50. This caps one response, not the mailbox:
nextpages through the rest, however many there are.0
Outbound messages
There is no sending endpoint. By design.
Rate limits
Free, without a key: 60 requests a minute and 1,000 a day, per IP address. Every call on a mailbox counts — listing it, reading a message, its HTML body, an attachment, a delete — and so does every MCP tool call. The day resets at 00:00 UTC.
Within that, one read per second per address: polling a mailbox once a second is the intended rhythm.
With a free API key, the same allowance follows your account instead of your IP address — useful when your calls come from changing addresses, like a CI runner. A free account has one key, and the mailboxes it reads are listed in your inboxes. Create a free key
Paid plans have no per-minute cap and no daily cap. Send the key of a paid plan as Authorization: Bearer and only the per-address rate of the plan remains — 2, 3 or 5 requests per second, on every domain, counted per account. Premium starts at $12.99 a month. See the plans
The inbox on this website does not draw on the free API allowance: a page left open keeps checking for mail for as long as you need it.
Over a limit you get 429 with a Retry-After header in whole seconds: rate_limited for the minute or the address, daily_limit_reached for the day, with the time left until midnight UTC. Every free response says where you stand: X-RateLimit-Remaining for the minute, X-RateLimit-Daily-Remaining for the day.
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
X-RateLimit-Daily-Limit: 1000
X-RateLimit-Daily-Remaining: 0
Content-Type: application/json
{
"error": "daily_limit_reached",
"message": "free daily limit reached: 1000 requests a day per IP address, resets at 00:00 UTC — paid plans have no daily cap",
"upgrade": { "from": "$12.99/month", "url": "https://grabmail.io/pricing", … }
}Back off on Retry-After rather than a fixed sleep. If the limit ever changes, code that reads the header keeps working.
Message size
Messages up to 5 MB, attachments included. That ceiling is enforced by the mail server during the SMTP conversation, which matters: the sending server is told at the moment it tries, and reports a real failure to its user, instead of the message vanishing.
- What counts
- The whole encoded message — headers, body and every attachment after MIME encoding. Base64 inflates a binary by about a third, so a file of roughly 3.5 MB already fills the ceiling.
- What happens over the line
- A
552at SMTP time. The message is never stored and never appears in the mailbox. - Attachments per message
- Twenty. The size ceiling is what you meet first in practice — but a message carrying more than twenty parts with filenames keeps the first twenty.
Retention
A message is deleted 5 days after it arrives, whether or not it has been read, and the clock starts at delivery rather than at first read.
Every message carries expires_at, so a client never has to compute that date or track the policy.
It is a hard limit, not a setting: no parameter, plan or account extends it. If something must outlive the window, fetch it and store it on your side.
Addresses and domains
- Addresses per domain
- Unlimited, and not counted. Since a mailbox is never created, there is no list of them to grow.
- Local-part rules
- One to 64 characters: letters, digits, dot, dash, underscore and plus. It must start and end with a letter or digit. Anything else is rejected before it reaches the mail server, in the browser and again on the server.
- Plus addressing
name+tag@domainis a distinct mailbox here, not an alias ofname@domain. That is deliberate — tags are how people separate signups, and folding them together would merge inboxes that were meant to stay apart.- Case
- Everything is lower-cased.
Name@andname@are the same mailbox. - Custom domains
- No limit on how many you point here. Each needs its own MX record.
Fair use
There is no quota to buy your way past, and no plan that raises these numbers. What there is instead: if a single source makes the service worse for everybody else, it gets stopped.
- Bulk polling
- Thousands of mailboxes polled every second from one source will be throttled at the edge before it reaches the API.
- Mail floods
- A sending host that opens an unreasonable number of SMTP connections is parked for ten minutes. Normal senders never come close.
- Using us as a relay
- Impossible rather than forbidden: the mail server only accepts messages addressed to domains hosted here, so it cannot forward anything anywhere.
None of this is aimed at ordinary automation. Poll once a second, all day, across thousands of mailboxes — that is the intended use, not the edge of it.