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
Every API request needs an API key, sent in the X-API-Key header. Keys are free: create an account, open it, and press Create key. A request without a key gets 401. For a live stream from a client that cannot set headers, you can pass the key as ?key= instead. Your plan sets your rate limit; private inboxes can only be read by their owner, and premium domains need a paid plan.
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 | No API key was sent, or 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.