Create an inbox
Issues an address and returns the token that reads it. Every field is optional, including the body.
Runs the real call on your workspace.
POST /temp-mail/inboxes
Issues an address and returns the token that reads it. Every field is optional, including the body.
No credential
export OE=https://api.nextmail.shSend no Authorization header at all. This is the only resource on the API that answers without one. It is registered above the key check rather than given a scope, because the thing being offered is an address for somebody who does not have one, and asking for a key first would make it a lead form wearing a tool’s clothes.
Example
An empty body is valid and is the common case: a generated local-part on a domain picked from the pool, leased for an hour.
curl -X POST "$OE/temp-mail/inboxes" -H "Content-Type: application/json" \ -d '{ "localPart": "octopus-signup", "ttlMinutes": 120 }'{ "object": "temp_inbox", "id": "tinb_octopus-signup", "address": "octopus-signup@freemailaddress.com", "domain": "freemailaddress.com", "createdAt": "2026-09-01T10:00:00.000Z", "expiresAt": "2026-09-01T12:00:00.000Z", "extensionsLeft": 23, "messageCount": 0, "messageLimit": 50, "lastMessageAt": null, "token": "oe_inbox_kQ8v…"}201, with the token that reads the inbox. Only this call and extend return one, and nothing on the server can recover it, so store it before you do anything else with the address.
A generated local-part is twelve characters from an alphabet with no vowels and no lookalikes, so it cannot spell anything and survives being read off a screen.
Everything that can be refused is refused by name rather than adjusted: 422 unknown_domain, invalid_address or reserved_address, 422 invalid_parameter for a ttlMinutes outside 1 to 1440 or a key the body does not take, and 503 not_configured while no disposable domain is on offer. Nothing is counted, so there is no 429, and nothing holds an address, so there is no 409.
Parameters
Body
domainstring- One of `GET /temp-mail/domains`, in any case. Omit it and the address goes on the first domain in that list. A domain that is not in the pool is refused by name (422 `unknown_domain`) rather than quietly substituted, because you would already have copied the address you asked for.
localPartstring- The part before the @, if you want to choose it: up to 64 letters, digits, dots, dashes and underscores, starting and ending on a letter or digit, lowercased on the way in. Anything else is 422 `invalid_address`, and more than 64 characters is 422 `invalid_parameter`. `+` is excluded, since sub-addressing is collapsed on the way in, so `alice+bob` would be a name you could not actually be reached at. `postmaster` and the other reserved ones answer 422 `reserved_address`. No name is ever taken: nothing holds an address, so a name you choose may be one somebody else is reading at the same time, an address the domain’s owner uses for real mail included. Leave it out for a generated one when the mail should reach you alone.
ttlMinutesnumber- How long the lease should be, in minutes, from 1 to 1440. Defaults to 60. Anything outside that range answers 422 `invalid_parameter` naming the field rather than being quietly adjusted. You would already have shown somebody the expiry you asked for. The 24 hours are measured from creation, so every hour taken up front is an hour `extend` cannot add later. `extensionsLeft` does not show it: `ttlMinutes: 1440` still comes back with 23, and none of them can add a minute.
Response: temp_inbox, plus a token
idstring- The inbox id, `tinb_` and the local part of the address. It goes in the path of every other call, and it is not a secret. The token is.
addressstring- The address to hand over. Mail addressed to `that+anything@` reaches it too, because sub-addressing is collapsed before the lookup.
domainstring- The pooled domain the address is on, split out so a client does not have to parse the address to show it.
createdAtstring- ISO-8601. The 24-hour cap is measured from this, not from the last extension.
expiresAtstring- ISO-8601. Past it the token answers 401 `inbox_expired`. Nothing is deleted.
extensionsLeftnumber- How many more times `extend` will accept the call: 23 minus the extensions spent. It counts calls, not time, so an inbox created with `ttlMinutes: 1440` reports 23 though none of them can add a minute. Zero means the call would answer 422 `extension_limit`, which is what a client should grey the button out on rather than discovering by pressing it.
messageCountnumber- How many messages the inbox is showing, counted across every page of the list. It goes down when you delete one. It is 0 on this response and on the one `extend` returns, which read no mail.
messageLimitnumber- The most messages one page of the list returns, sent on every inbox so a client does not hardcode our constant. It is not a ceiling: `hasMore` and `nextCursor` reach the rest.
lastMessageAtstring | null- When mail last arrived, ISO-8601, or null if none has. Null on a fresh inbox reads very differently from a quiet one to somebody who has been waiting two minutes.
tokenstring- The credential. `oe_inbox_`, then the lease itself and a signature over it. Nothing about it is stored, so it cannot be re-read, recovered or revoked.
Retrieve returns this object without token. Extend returns it with a new token that carries the later expiry.
Google Workspace
Fastmail