Documentation
Three endpoints and no account. There is not much to learn, so there is not much to read.
Start here
Quickstart
A working mailbox and a message read back, in four commands. Start here if you have never called the API.
API reference
All three endpoints with parameters, examples and status codes. The contract, in full.
Limits
Rate limit, message size, retention and everything else that is capped. Short page, no surprises.
Guides
Longer walkthroughs, with the failure modes in them: what to do rather than what a parameter means.
How long an inbox lasts
What the 5-day window applies to and what it does not, when the clock actually starts, everything that goes with a message, reading the deadline straight off the API, and the habit that stops any of it mattering.
What temp mail is
The definition, the mechanics (one MX record and a mailbox that exists the moment mail arrives), temp mail against disposable, burner and alias addresses, what it is good for, the four places it is the wrong tool, and how long an address lasts.
Testing verification flows
The full sign-up loop against a real mailbox: unique address per run, polling with a wall-clock deadline, extracting the code or the confirmation link, and working Playwright and pytest helpers.
The four things worth knowing
- A mailbox is not created
- There is no “create address” call. An address exists the moment mail arrives at it, and stops existing when the last message expires.
- The address is the credential
- On a public domain, whoever knows the address can read it — through the API exactly as through the site. Use your own domain when that is not acceptable.
- Everything expires
- Messages are deleted 5 days after they arrive.
expires_atis on every message so you never compute it. - Receive only
- No endpoint sends mail. That is deliberate: it is what keeps a free, unauthenticated service from becoming a spam relay.
When something is wrong
If a call behaves differently from this documentation, the documentation is the bug — tell us and it gets fixed.
- Mail never arrives
- Check the MX record first:
smtp.grabmail.ioand nothing else. A leftover MX from a previous provider takes part of your traffic silently. - The API answers 404
- Either the domain is not pointed here, or the message has passed its retention window. The two cases are distinguished by the
errorslug. - Mail claims to come from us
- It is forged. Nothing here can send email — our SPF is
v=spf1 -alland our DMARC isp=reject, which tells every receiving server on earth to bin it.