Create an inbox
Issues an address and returns the token that reads it. Every field is optional, including the body.
Runs the real call against your workspace, with your own key.
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.openemail.ukSend 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_9c2f41ab7d3e4c118a0f5d72", "address": "[email protected]", "domain": "freemailaddress.com", "createdAt": "2026-09-01T10:00:00.000Z", "expiresAt": "2026-09-01T12:00:00.000Z", "extensionsLeft": 22, "messageCount": 0, "messageLimit": 50, "lastMessageAt": null, "token": "oe_inbox_kQ8v…"}201, and the only response in the whole API that carries token. 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, reserved_address, or invalid_parameter for a ttlMinutes outside 1 to 1440; 409 address_taken for a local-part already spoken for; 429 too_many_inboxes at the mint ceiling; 503 temp_mail_unavailable on an install with no pooled domain at all.
Parameters
Body
domainstring- One of `GET /temp-mail/domains`. Omit it and the pool picks at random rather than filling the first domain. One domain receiving every throwaway signup on the internet earns the reputation to match, and that reputation is shared by every address on it. 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: 3 to 32 characters of letters, digits, dots, dashes and underscores, starting and ending on a letter or digit. Narrower than RFC 5321 allows, because this string goes into a URL path, a `To:` header and a page of HTML. `+` 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. Taken names answer 409 `address_taken`, which covers two cases: another visitor holds it (or held it within the last week, while the address is still out of circulation), and the domain’s owner has created it as a real address, which is refused under the same code because mail to it reaches them and never you. `postmaster` and the other reserved ones answer 422 `reserved_address`.
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 extension that cannot be spent later: `ttlMinutes: 120` comes back with 22 of them, and 1440 with none.
Response: temp_inbox, plus a token
idstring- The inbox id, `tinb_` and twenty-four hex characters. 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 stops authenticating immediately, and the sweep deletes the mail on its next run.
extensionsLeftnumber- How many more times `extend` will actually buy time, counting both ceilings: the 23 extensions a lease allows, and the 24 hours from `createdAt` it can never run past, whichever is reached first. An inbox created with `ttlMinutes: 1440` reports 0 having spent nothing. Zero means the call would answer 409, which is what a client should grey the button out on rather than discovering by pressing it.
messageCountnumber- Messages this inbox has ACCEPTED, not how many are showing. It does not go down when you delete one: the ceiling counts arrivals, so deleting frees storage but not room.
messageLimitnumber- The ceiling, sent on every inbox so a client can say "full" without hardcoding our constant.
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, on this response and no other. `oe_inbox_` and 43 base64url characters; the row stores only a keyed hash, so it cannot be re-read or recovered.
Every other inbox response (retrieve, extend) is this object without token.