mohamed-khairy-5i/tossinbox

**Disposable email inboxes for humans and AI agents. Spawn a temporary inbox, wait for the OTP verification code, toss it.**
> **Built by Mohamed Khairy.**
> If TossInbox saved you a signup form, consider starring the repo — it helps more people find it.
TossInbox is a temp-mail CLI and MCP server: it creates a brand-new throwaway
email address in one command, waits for the email verification to land, extracts
the OTP code, and deletes the inbox when you are done — server-side and locally.
Use it for signups, QA email flows, and test automation — or let your **AI
agent** do all of it through the built-in **MCP server**. No sign-up, no ads,
no browser, no API keys. Humans read the output; agents parse the --json.
Website & docs → tossinbox.pages.dev
Demo
Why TossInbox
- **For humans** — stop exposing your real address to every signup form.
- **For agents** — built agent-first from day one:
- --json output on every command
- documented exit codes, no interactive prompts
- an MCP server so Claude, Cursor, and any
MCP client can create inboxes and read verification codes as native tools
- an llms.txt at the repository root for LLM-friendly onboarding
| | TossInbox | temp-mail websites | tmpmail-era CLIs |
|------------------------|-------------------------|---------------------|-----------------------------|
| JSON on every command | --json | no | rarely |
| Documented exit codes | 0–4 | none | no |
| MCP server for agents | yes, built in | no | no |
| Runs headless / in CI | yes | no | partial |
| Upstream alive | 7 providers, 4 stacks, attachments on read | varies | many wrap the dead 1secmail |
| Ads, trackers, popups | none | the business model | none |
Checked September 2026. If a cell is wrong, open an issue and win the argument.
Install
Requires Node.js 18+.
From source:
Quickstart
Four commands from zero to a tossed inbox:
Every command also accepts --json for machine-readable output:
CLI Reference
| Command | Description |
|---|---|
| spawn | Create a new disposable inbox (-p provider, -l label). If the provider is down, another one is used automatically — --no-failover opts out |
| list | List messages (-a address) |
| read | Read a full message, including any detected code; lists attachments. --html prints the raw HTML body, --save [dir] downloads attachments + bodies to / / |
| wait | Poll until a message arrives (-f sender, -s subject, -c extract code, -t timeout max 600s) |
| watch | Stream new messages until Ctrl-C — only new arrivals; --json = one JSON object per line (NDJSON) |
| inboxes | List locally saved inboxes |
| toss | Delete an inbox server-side and remove it from local state (--all for every inbox) |
| clear | Remove all inboxes from local state only |
| providers | List available email providers |
| mcp | Run the MCP server over stdio |
Exit codes
A stable contract: agents script against these, not against stdout.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (provider / network / unexpected) |
| 2 | Timeout (wait expired without a matching message) |
| 3 | Not found (no saved inbox, unknown address, or message missing) |
| 4 | Usage error (bad flags, unknown command, or unknown provider) |
GitHub Action (email verification in CI)
Use TossInbox directly in your workflows to test real signup / verification
email flows:
Outputs: address (the disposable inbox) and code (the extracted OTP).
MCP Server (for AI agents)
TossInbox ships with an MCP server exposing four tools:
| Tool | Description |
|---|---|
| create_inbox | Create a disposable inbox and return its address |
| list_messages | List messages in an inbox |