# TossInbox

> Disposable email inboxes for humans and AI agents. Spawn an inbox, wait for the OTP, toss it.

TossInbox creates disposable email addresses from the command line or through
an MCP server, collects verification codes (OTP) from them, and deletes the
inboxes when done. It is designed agent-first: every CLI command supports
`--json`, exit codes are documented, and there are no interactive prompts.

## Site

- [Home](https://tossinbox.pages.dev/): overview, install options, comparison table
- [Quickstart](https://tossinbox.pages.dev/quickstart): first inbox in four commands
- [CLI reference](https://tossinbox.pages.dev/cli): all commands, flags, exit codes
- [Agents & MCP](https://tossinbox.pages.dev/agents): MCP server setup for AI agents
- [Examples](https://tossinbox.pages.dev/examples): copy-paste recipes (shell, CI, Node.js, MCP)
- [Guide](https://tossinbox.pages.dev/guide): providers, state, flags, exit codes, troubleshooting
- [FAQ](https://tossinbox.pages.dev/faq): privacy, providers, troubleshooting
- [Roadmap](https://tossinbox.pages.dev/roadmap): shipped and planned
- [Changelog](https://tossinbox.pages.dev/changelog): every change by version
- [Arabic home](https://tossinbox.pages.dev/ar/): الصفحة الرئيسية بالعربية
- [Arabic quickstart](https://tossinbox.pages.dev/ar/quickstart): البداية السريعة بالعربية
- [Source repository](https://github.com/mohamed-khairy-5i/tossinbox): code, issues, releases

## CLI (binary: `tossinbox`)

- `tossinbox spawn` — create a new disposable inbox (flags: `-p provider`, `-l label`);
  if the provider is down, another one is used automatically (`--no-failover` opts out)
- `tossinbox list` — list messages in an inbox (flag: `-a address`)
- `tossinbox read <id>` — read a full message by id; `--save [dir]` saves every attachment plus the
  HTML/plain-text bodies to `<dir>/<message-id>/` (default dir `./tossinbox-attachments`),
  `--html` prints the raw HTML body
- `tossinbox wait --code` — poll until a message arrives and print its verification code
  (flags: `-f sender`, `-s subject`, `-t timeout`, `-i interval`)
- `tossinbox watch` — stream new messages as they arrive until Ctrl-C (NDJSON with `--json`; events
  include attachment names when a new message has them)
- `tossinbox inboxes` — list locally saved inboxes
- `tossinbox toss` — delete an inbox server-side and wipe local state (`--all` for all)
- `tossinbox providers` — list providers (default: `mailtm`; also `mailgw`, `guerrillamail`, `tempmaillol`, `tempmailio`, `tempmailplus`, `maildrop`)

All commands accept `--json`. Exit codes: 0 success, 1 error, 2 timeout,
3 not found, 4 usage error (bad flags / unknown provider).

## MCP server (binary: `tossinbox-mcp`, or `tossinbox mcp`)

Stdio MCP server exposing four tools:

- `create_inbox` — create a disposable inbox, returns its email address
- `list_messages` — list messages in an inbox
- `read_message` — read a full message including any detected code; reports attachment metadata and
  accepts an optional `save_dir` input that saves attachments + bodies to `<save_dir>/<message-id>/`
- `wait_for_code` — poll until a message arrives and return its verification code

Typical agent flow: `create_inbox` -> use the address in a signup form ->
`wait_for_code` -> submit the code -> delete the inbox from the CLI with
`tossinbox toss`.

## Installation

```bash
npm install -g tossinbox
# or run without installing:
npx tossinbox@latest spawn
```

## Notes

- Providers: `mailtm` (default), `mailgw`, `guerrillamail`, `tempmaillol`,
  `tempmailio`, `tempmailplus`, `maildrop`; no API keys required. When a
  provider is down, `spawn` fails over to another one automatically.
- Attachments: full list + download on `mailtm`, `mailgw` and `tempmailplus`;
  `tempmailio` shows them when its upstream returns them (download only if it
  exposes a URL); `tempmaillol`, `guerrillamail` and `maildrop` have no
  attachment support upstream.
- Local state is stored in `~/.tossinbox/state.json` (override with the
  `TOSSINBOX_STATE` environment variable) with 0600 permissions.
- TossInbox intentionally has no bulk mode; use it for privacy and testing and
  respect the providers' terms of service.
- License: MIT. Repository: https://github.com/mohamed-khairy-5i/tossinbox