Disposable email,
from your code.
A small, fast JSON API. Create an inbox, receive mail, get verification codes back as plain fields, and stream new messages the instant they land. No account required.
Quickstart
Get a verification code out of a sign-up email in three calls.
Authentication
Most endpoints are open: an inbox is identified by its address, and anyone who knows the address can read it. The exceptions are private inboxes, which only their owner can read, and premium domains, which need a paid plan. To raise your rate limit, send an API key in the X-API-Key header. Get your own key in seconds: create a free account, open it, and press Create key.
Rate limits
| Caller | Sustained | Burst |
|---|---|---|
| Anonymous, per IP | 2 requests / second | 20 |
| Free plan key | 20 requests / second | 100 |
| Relay plan | 60 requests / second | 300 |
| Vault plan | 200 requests / second | 1,000 |
Going over a limit returns 429 with a Retry-After header. Each plan also limits how many inboxes can be open at once, and that covers both live streams and calls waiting for a code. When the server is busy, free requests wait and may return 503, while paid requests go first. See plans.
IMAP
On a paid plan, create an IMAP login for a private inbox from your account. Connect to mail.<domain> on port 993 (SSL/TLS) or 143 (STARTTLS), using the full address as the username. IMAP is read-only access to INBOX, and mail cannot be sent from it.
Codes and links
Every message is checked for one-time codes and verification links. The inbox list returns code and has_link for each message. A single message returns code, codes (the best first, up to three), verify_link and verify_label, which is the text of the button in the mail. A field is empty when nothing was found. Digit codes come back without separators, so 123-456 is returned as 123456.
A single message also returns clean_body and clean_footer, the mail as plain paragraphs without its layout, and clean_action_at, the paragraph its code or button came before (-1 when it was not on a line of its own).
Your own domains
On a paid plan you can add a domain you own. These routes work with your session or an X-API-Key header. Addresses on a private domain can only be read by the account that owns it.
POST /api/account/domains with {"name":"yourdomain.com"} returns the two DNS records to add: a TXT record that proves you own the domain, and an MX record that sends its mail here.
POST /api/account/domains/{name}/verify checks both records and returns txt, mx and verified. You can check once every 10 seconds.
GET /api/account/domains lists your domains. GET /api/account/domains/{name}/addresses lists the addresses that have received mail on a private domain.
PATCH /api/account/domains/{name} with {"shared":true} or false shares the domain with all users or makes it private. Either change deletes all mail on the domain.
POST /api/account/domains/{name}/imap creates one IMAP login for all addresses on a private domain, and returns its password once. DELETE /api/account/domains/{name} removes the domain and all of its mail.
Create addresses with POST /api/address and your domain in domain. Each domain has a daily mail limit, and over it senders are asked to try again later. We re-check your records every 6 hours, and a domain whose records stay missing for 3 days stops receiving mail until they return.
Errors
Errors return a JSON body like {"error":"invalid address"} with a matching HTTP status.
| Status | Meaning |
|---|---|
400 | Invalid input: bad address, unknown domain, or a reserved or malformed name. |
401 | The X-API-Key you sent is not valid. |
403 | The address is blocked by the operator. |
404 | Message or domain not found. |
429 | Rate limit exceeded. Wait Retry-After seconds. |
Full example
Create an inbox, then wait for the verification code over the live stream.