Disposable inboxes

A caller asks for an address on one of the disposable domains Nextmail runs, watches it for a few minutes, reads whatever arrives, and abandons it. It exists for the confirmation code, the "what does this form actually send" question, and the signup you do not want attached to the address you will still be using in five years.

• —It receives and nothing else. There is no send: an inbox has no identity to send as, and none of these nine calls will put a message on the wire.
• —The lease is 60 minutes by default and can be pushed to 24 hours, an hour at a time.
• —Every message that reaches it is listed, 50 to a page with a cursor for the rest, so nothing is hidden for arriving late. Deleting one takes it off the list.
• —At the end of the lease the token stops opening the inbox, and nothing is deleted. Nothing about a lease is stored either, so the address is never held back: anybody can be issued it again, even while your lease runs.
• —The mail lands, through the catch-all, in the mailbox of the workspace that runs the pool. These calls read that mailbox, and a lease sees only the mail delivered to its own address since the lease began.

A disposable address is typed into a signup form the moment it is issued. From there it travels in a To: header, through the sender’s logs, and into whatever CRM sits at the other end. If knowing the address were enough to read the mail, the tool would leak every inbox it issued, by design, and to precisely the party the caller was holding at arm’s length.

So creating an inbox returns a second value: a token, oe_inbox_ followed by the lease itself (the address, when it began, when it ends and the extensions spent) and a signature over it. Nothing about the lease is stored on the server, so a lost token cannot be looked up again, and a token cannot be cancelled either: it opens its inbox until the expiry written inside it. Extending the lease hands back a new token with the later expiry.

# 1. Mint one. Only this and extend return a token.curl -s -X POST "$OE/temp-mail/inboxes" -H "Content-Type: application/json" -d '{}' # 2. Keep it, and read with it.export INBOX="Authorization: Bearer oe_inbox_kQ8v…"curl -s "$OE/temp-mail/inboxes/tinb_k7m2q9xw4bdp/messages" -H "$INBOX"

An hour, rather than the ten minutes the genre is named after. Ten is enough for a confirmation code and not enough for the other half of what these are used for: a trial that emails you again the next morning, a form filled in twice because the first attempt timed out. ttlMinutes on create asks for something else, from 1 to 1440; a number outside that is refused with a 422 rather than quietly adjusted, because an expiry you did not ask for is one you have already planned around.

POST /temp-mail/inboxes/{id}/extend adds an hour to the expiry, not to now, so extending early does not waste the time you have left. It works 23 times, and the new expiry never passes 24 hours after the inbox was created, so a call on a lease that already reaches that point still succeeds, still spends an extension and buys nothing. extensionsLeft counts only the 23 calls, not the 24 hours, so compare expiresAt with createdAt before offering more time. Once all 23 are spent the call answers 422 extension_limit. Each extension returns a new token with the later expiry, and the old token keeps its old one.

Creating an inbox is limited to 10 every 10 minutes from one network, and the next one answers 429 temp_inbox_rate_limited with Retry-After. Nothing else on these routes is counted. The other ceilings are the length of a lease, the size of a page and the day a conversation is kept.

Finding out by trying is worse than being told:

• —No sending, in any form. A disposable inbox has no connection to send as, and adding one would make an anonymous, unauthenticated endpoint into an open relay.
• —No rename. Changing your address means creating a second inbox, and the old token keeps opening the old address until its lease ends.
• —No rules, filters, forwarding, webhooks or AI. spam is a flag on the message and nothing acted on it. Nothing was filed away, and nothing here is summarised or embedded.
• —No bounces. Mail to a pooled domain that names no live disposable inbox is dropped silently, on purpose: a public address generator attracts dictionary attacks, and writing a delivery report to whatever return path the attack claims would make the pool a source of backscatter.
• —No domain on offer means no service. While no disposable domain is on offer, GET /temp-mail/domains answers with an empty list and creating an inbox answers 503 not_configured. While the mailbox behind the pool cannot be read, listing, reading and deleting mail and destroying an inbox answer 503 not_configured as well. Inbound delivery to a pooled domain has not been observed end to end on a live domain.

Nextmail runs the pool and picks its domains. GET /temp-mail/domains lists them in the order they are offered, and an inbox created without a domain goes on the first one. A domain you add to your own workspace never joins the pool, and nothing in a workspace changes what the pool hands out.