--- title: "openemail temp-mail" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://openemail.uk/docs/cli/reference/temp-mail" area: "CLI" category: "Reference" --- # openemail temp-mail Every command in this namespace, with its arguments, flags and examples. ## Commands ### `openemail temp-mail list-domains` List the domains a disposable inbox can be created on ```bash openemail temp-mail list-domains [flags] ``` Resolves the pool of domains `create` accepts, as a plain array in the order the operator wrote them in `TEMP_MAIL_DOMAINS`. It takes no credential at all: no API key and no inbox token are sent, even when the client holding this namespace has one. Nothing checks that a listed domain is verified, so the list is only as good as the operator made it. An empty array is a normal answer meaning this install offers no disposable domains, and it is exactly the condition under which `create` fails with 503 `not_configured`. - No sign-in needed. **Examples** ```bash openemail temp-mail list-domains ``` Print the raw JSON ```bash openemail temp-mail list-domains --json ``` Also available in: API [`GET /temp-mail/domains`](https://openemail.uk/docs/api/reference/temp-mail#get-temp-mail-domains); SDK [`tempMail.listDomains()`](https://openemail.uk/docs/sdk/reference/temp-mail#listDomains). ### `openemail temp-mail create` Create a disposable inbox and its access token ```bash openemail temp-mail create [flags] ``` Mints a disposable address and resolves with the inbox plus its `token`. It needs no credential, and only this call and `extend` return a token. The token is the lease itself, signed, and nothing about it is stored on the server, so a lost token cannot be recovered, and every other method except `listDomains` needs it. Store it before you show the address to anyone. The body is optional and so is every field in it. With nothing, you get a 12 character generated local part on the first domain in the pool, leased for 60 minutes. A chosen `--local-part` is lowercased and must be up to 64 letters, digits, dots, dashes or underscores, starting and ending with a letter or digit, or it is 422 `invalid_address`, and one longer than 64 characters is 422 `invalid_parameter`. Names such as `postmaster`, `abuse` and `support` are 422 `reserved_address`, and an install with no pooled domain answers 503 `not_configured`. Nothing is rate limited and nothing reserves an address, so this never answers 429 or 409. A name you choose is issued to anyone who asks for it, and each of you reads the mail that reaches it from the start of your own lease. Leave `--local-part` out when the mail should reach you alone. - No sign-in needed. - Aliases: `new`, `add`. **Flags** - `--domain `: A domain from `listDomains`. Omit it for the first one in the pool. Any other name is 422 `unknown_domain` rather than a silent substitute. - `--local-part `: The part before the @. Omit it for a generated one, which nobody else is likely to be issued. - `--ttl-minutes `: Lease length from now, a whole number from 1 to 1440. Defaults to 60. Out of range is 422 `invalid_parameter`, not clamped. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail temp-mail create ``` With optional flags ```bash openemail temp-mail create --ttl-minutes 120 ``` Also available in: API [`POST /temp-mail/inboxes`](https://openemail.uk/docs/api/reference/temp-mail#post-temp-mail-inboxes); SDK [`tempMail.create()`](https://openemail.uk/docs/sdk/reference/temp-mail#create). ### `openemail temp-mail get` Read the lease and counters of a disposable inbox ```bash openemail temp-mail get [flags] ``` Resolves the inbox with its expiry, remaining extensions and message counters, without any messages. To watch an inbox, poll `listMessages` instead: it returns `expiresAt` alongside the mail, so one request covers both. This call is authorised by the inbox token, never by an API key. A workspace key sent in its place is refused with 401 `missing_inbox_token`, and no scope on any key reaches this resource. The token alone decides which inbox is read, and the id in the path is not checked against it. Once the lease is over the token answers 401 `inbox_expired`, and a token this server did not sign answers 404 `resource_not_found`. Deleting an inbox does not end its lease, so its token still reads it. `messageCount` is counted by reading every page, and is 0 when the install cannot read the mailbox that runs the pool. - No sign-in needed. - Aliases: `show`, `view`. **Arguments** - `` (required): The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox. **Flags** - `--inbox-token `: The inbox token returned when the inbox was created. Defaults to the token saved for this inbox. **Examples** ```bash openemail temp-mail get tinb_k7m2q9xw4bdp ``` Pass the token when the CLI did not create the inbox ```bash openemail temp-mail get tinb_k7m2q9xw4bdp --inbox-token "$INBOX_TOKEN" ``` Print the raw JSON ```bash openemail temp-mail get tinb_k7m2q9xw4bdp --json ``` Also available in: API [`GET /temp-mail/inboxes/{id}`](https://openemail.uk/docs/api/reference/temp-mail#get-temp-mail-inboxes-id); SDK [`tempMail.get()`](https://openemail.uk/docs/sdk/reference/temp-mail#get). ### `openemail temp-mail extend` Push the expiry of an inbox an hour further out ```bash openemail temp-mail extend [flags] ``` Adds up to 60 minutes to `expiresAt` and resolves with the updated inbox and a new `token` that carries the later expiry. There is no body. The old token keeps its old expiry, so use the new one from here on, including in a client built with `createTempMail({ inboxToken })`. The new expiry is the earlier of one hour past the current expiry and 24 hours after `createdAt`, and a lease allows at most 23 extensions. The last extension can buy less than an hour, and on a lease that already reaches the 24 hours a call still succeeds, spends an extension and buys nothing. `extensionsLeft` counts only the 23 calls, so compare `expiresAt` with `createdAt` before offering more time. When `extensionsLeft` is 0 this answers 422 `extension_limit` for good, and the only way on is a new inbox. The response reads no mail, so its `messageCount` is 0 and its `lastMessageAt` is null. - No sign-in needed. **Arguments** - `` (required): The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox. **Flags** - `--inbox-token `: The inbox token returned when the inbox was created. Defaults to the token saved for this inbox. **Examples** ```bash openemail temp-mail extend tinb_k7m2q9xw4bdp ``` Pass the token when the CLI did not create the inbox ```bash openemail temp-mail extend tinb_k7m2q9xw4bdp --inbox-token "$INBOX_TOKEN" ``` Also available in: API [`POST /temp-mail/inboxes/{id}/extend`](https://openemail.uk/docs/api/reference/temp-mail#post-temp-mail-inboxes-id-extend); SDK [`tempMail.extend()`](https://openemail.uk/docs/sdk/reference/temp-mail#extend). ### `openemail temp-mail delete` Move the mail in a disposable inbox to the bin now ```bash openemail temp-mail delete [flags] ``` Moves every message the inbox shows to the bin of the mailbox that runs the pool, at once. It does not end the lease: nothing about a lease is stored, so there is nothing to revoke, and the token keeps opening the address until its expiry. Mail that arrives afterwards is listed as usual. Nothing holds the address back either, so it can be issued again at once, to anybody. An install with no key to read the pool answers 503 `not_configured`. The response is a tombstone rather than an empty body, so a log line can name what went. - No sign-in needed. - Asks you to confirm. - Aliases: `rm`, `del`, `remove`. **Arguments** - `` (required): The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox. **Flags** - `--inbox-token `: The inbox token returned when the inbox was created. Defaults to the token saved for this inbox. **Examples** ```bash openemail temp-mail delete tinb_k7m2q9xw4bdp ``` Skip the confirmation, for scripts ```bash openemail temp-mail delete tinb_k7m2q9xw4bdp --yes ``` Pass the token when the CLI did not create the inbox ```bash openemail temp-mail delete tinb_k7m2q9xw4bdp --inbox-token "$INBOX_TOKEN" ``` Also available in: API [`DELETE /temp-mail/inboxes/{id}`](https://openemail.uk/docs/api/reference/temp-mail#delete-temp-mail-inboxes-id); SDK [`tempMail.delete()`](https://openemail.uk/docs/sdk/reference/temp-mail#delete). ### `openemail temp-mail list-messages` List one page of the messages in a disposable inbox ```bash openemail temp-mail list-messages [flags] ``` Resolves one page of the messages in the inbox newest first, by the time the server received them, together with the inbox `expiresAt`. Rows carry metadata only, and polling this is the way to wait for a confirmation email. Only mail delivered to this address since the lease began is listed. A page holds up to 50 messages. A page can hold fewer than `limit` rows, even none, while `hasMore` is true, because mail to other addresses on the pool is read and dropped. `snippet` is plain text capped at 400 characters, which is often enough to read a one time code without opening the message. `spam` is a flag, never a filing decision. A machine sent confirmation from a sender with no reputation is exactly what a disposable inbox exists to receive, so flagged messages are still listed. `from` is whatever the message claimed and has not been authenticated. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one JSON document with `--json`, shaped as Returns describes. `--max ` stops after that many items. - No sign-in needed. **Arguments** - `` (required): The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox. **Flags** - `--limit ` (default `50`): Messages per page, a whole number from 1 to 50, defaulting to 50. Out of range is 422 `invalid_parameter`. - `--cursor `: The `nextCursor` from the previous page. Never build one yourself. - `--inbox-token `: The inbox token returned when the inbox was created. Defaults to the token saved for this inbox. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** The required values only ```bash openemail temp-mail list-messages tinb_k7m2q9xw4bdp ``` With optional flags ```bash openemail temp-mail list-messages tinb_k7m2q9xw4bdp --limit 10 ``` Walk every page and stop after 100 items ```bash openemail temp-mail list-messages tinb_k7m2q9xw4bdp --all --max 100 ``` One JSON object per line when piped ```bash openemail temp-mail list-messages tinb_k7m2q9xw4bdp --all > temp-mail.ndjson ``` Pass the token when the CLI did not create the inbox ```bash openemail temp-mail list-messages tinb_k7m2q9xw4bdp --inbox-token "$INBOX_TOKEN" ``` Also available in: API [`GET /temp-mail/inboxes/{id}/messages`](https://openemail.uk/docs/api/reference/temp-mail#get-temp-mail-inboxes-id-messages); SDK [`tempMail.listMessages()`](https://openemail.uk/docs/sdk/reference/temp-mail#listMessages). ### `openemail temp-mail get-message` Read one message with its stored body ```bash openemail temp-mail get-message [flags] ``` Resolves the list row for one message plus the parsed message as stored. Reading it does not mark it seen: `seen` mirrors the unread state of the message in the mailbox that runs the pool, and nothing on these routes changes it. Render `message.decodedBody`. `body` and `processedHtml` are empty strings for every message that can reach a disposable inbox, so a client reading either shows a blank page. The body is never cut, so `truncated` is always false. The HTML came from a stranger to an address anyone could name. Render it outside your own origin, for example in a sandboxed iframe. - No sign-in needed. **Arguments** - `` (required): The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox. - `` (required): An `id` from `listMessages`, such as `thr_` and 24 hex. **Flags** - `--inbox-token `: The inbox token returned when the inbox was created. Defaults to the token saved for this inbox. **Examples** ```bash openemail temp-mail get-message tinb_k7m2q9xw4bdp thr_9e3b7c1a5f2d8e40b6a9c3f1 ``` Pass the token when the CLI did not create the inbox ```bash openemail temp-mail get-message tinb_k7m2q9xw4bdp thr_9e3b7c1a5f2d8e40b6a9c3f1 --inbox-token "$INBOX_TOKEN" ``` Print the raw JSON ```bash openemail temp-mail get-message tinb_k7m2q9xw4bdp thr_9e3b7c1a5f2d8e40b6a9c3f1 --json ``` Also available in: API [`GET /temp-mail/inboxes/{id}/messages/{messageId}`](https://openemail.uk/docs/api/reference/temp-mail#get-temp-mail-inboxes-id-messages-messageid); SDK [`tempMail.getMessage()`](https://openemail.uk/docs/sdk/reference/temp-mail#getMessage). ### `openemail temp-mail delete-message` Delete one message from a disposable inbox ```bash openemail temp-mail delete-message [flags] ``` Moves the message, attachments and all, to the bin of the mailbox that runs the pool, and no lease lists or opens it again. Nothing in this SDK restores it. `messageCount` goes down by one. There is never a slot to free: an inbox keeps every message that reaches it, and `listMessages` pages through all of them. - No sign-in needed. - Asks you to confirm. **Arguments** - `` (required): The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox. - `` (required): An `id` from `listMessages`, such as `thr_` and 24 hex. **Flags** - `--inbox-token `: The inbox token returned when the inbox was created. Defaults to the token saved for this inbox. **Examples** ```bash openemail temp-mail delete-message tinb_k7m2q9xw4bdp thr_9e3b7c1a5f2d8e40b6a9c3f1 ``` Skip the confirmation, for scripts ```bash openemail temp-mail delete-message tinb_k7m2q9xw4bdp thr_9e3b7c1a5f2d8e40b6a9c3f1 --yes ``` Pass the token when the CLI did not create the inbox ```bash openemail temp-mail delete-message tinb_k7m2q9xw4bdp thr_9e3b7c1a5f2d8e40b6a9c3f1 --inbox-token "$INBOX_TOKEN" ``` Also available in: API [`DELETE /temp-mail/inboxes/{id}/messages/{messageId}`](https://openemail.uk/docs/api/reference/temp-mail#delete-temp-mail-inboxes-id-messages-messageid); SDK [`tempMail.deleteMessage()`](https://openemail.uk/docs/sdk/reference/temp-mail#deleteMessage). ### `openemail temp-mail list-attachments` List the attachments of a message, metadata only ```bash openemail temp-mail list-attachments [flags] ``` Resolves every attachment on a message as a plain array of metadata: `attachmentId`, `filename`, `mimeType` and `size` in decoded bytes, with `body` an empty string and `headers` empty. No route on a disposable inbox serves the bytes, and there is no per attachment fetch. `filename` and `mimeType` are whatever the sender declared, and nothing here is scanned. A message this lease cannot see is 404 `resource_not_found`, and an install with no key to read the pool answers 503 `not_configured`. - No sign-in needed. **Arguments** - `` (required): The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox. - `` (required): An `id` from `listMessages`, such as `thr_` and 24 hex. **Flags** - `--inbox-token `: The inbox token returned when the inbox was created. Defaults to the token saved for this inbox. **Examples** ```bash openemail temp-mail list-attachments tinb_k7m2q9xw4bdp thr_9e3b7c1a5f2d8e40b6a9c3f1 ``` Pass the token when the CLI did not create the inbox ```bash openemail temp-mail list-attachments tinb_k7m2q9xw4bdp thr_9e3b7c1a5f2d8e40b6a9c3f1 --inbox-token "$INBOX_TOKEN" ``` Also available in: API [`GET /temp-mail/inboxes/{id}/messages/{messageId}/attachments`](https://openemail.uk/docs/api/reference/temp-mail#get-temp-mail-inboxes-id-messages-messageid-attachments); SDK [`tempMail.listAttachments()`](https://openemail.uk/docs/sdk/reference/temp-mail#listAttachments).