# TossInbox — Disposable Email CLI & MCP Server for AI Agents
**Disposable email inboxes for humans and AI agents. Spawn a temporary inbox, wait for the OTP verification code, toss it.**
[](https://github.com/mohamed-khairy-5i/tossinbox/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/tossinbox)
[](https://www.npmjs.com/package/tossinbox?activeTab=versions)
> **Built by [Mohamed Khairy](https://github.com/mohamed-khairy-5i).**
> 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
```text
$ tossinbox spawn
✔ Inbox ready : qwd6996p1lbc@uberip.com
provider : mailtm
$ tossinbox wait --code --from noreply@github.com --timeout 120
✔ Verify your device
from : GitHub
code : 9378412
$ tossinbox toss
✔ tossed qwd6996p1lbc@uberip.com
```
## 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](https://modelcontextprotocol.io) 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+.
```bash
# Homebrew (macOS, Linux)
brew install mohamed-khairy-5i/tap/tossinbox
# npm (npmjs.com)
npm install -g tossinbox
# Or run without installing
npx tossinbox@latest spawn
```
From source:
```bash
git clone https://github.com/mohamed-khairy-5i/tossinbox.git
cd tossinbox
npm install
npm run build
node dist/cli.js --help
```
## Quickstart
Four commands from zero to a tossed inbox:
```bash
tossinbox providers # sanity check: install + network work
tossinbox spawn # create an inbox (saved locally)
tossinbox wait --code # block until a message arrives, print its OTP
tossinbox toss # delete the inbox server-side + wipe local state
```
Every command also accepts `--json` for machine-readable output:
```bash
tossinbox spawn --json
tossinbox wait --code --json
```
## 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:
```yaml
- uses: mohamed-khairy-5i/tossinbox@v1
id: mail
with:
args: "wait --code --json"
timeout: "180"
- run: echo "Verification code: ${{ steps.mail.outputs.code }}"
```
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 |
| `read_message` | Read a full message, including any detected code; reports attachment metadata and can save attachments + bodies to disk (`save_dir`) |
| `wait_for_code` | Poll until a message arrives and return its verification code |
### Claude Desktop / Cursor / any MCP client
```json
{
"mcpServers": {
"tossinbox": {
"command": "npx",
"args": ["-y", "tossinbox", "mcp"]
}
}
}
```
Or after a global install, simply use `tossinbox-mcp` as the command —
equivalent to `npx -y tossinbox mcp`.
### Works with any AI agent
TossInbox is deliberately agent-agnostic — no lock-in to one vendor:
- **Any MCP client**: Claude Desktop, Claude Code, Cursor, Windsurf, Cline,
Codex CLI, Gemini CLI, and every other MCP-compatible client
- **Any shell-capable agent**: the CLI itself is the interface — `--json` on
every command, exit codes `0–4` documented, zero interactive prompts
- **CI/CD**: the GitHub Action above needs no agent at all
## Using TossInbox with an agent (copy-paste flow)
```text
1. "Create a disposable inbox" -> tool: create_inbox
2. "Sign up at example.com with this address"
3. "Wait for the verification code from example.com"
-> tool: wait_for_code
4. "Use code 482913 to finish the signup"
5. "Toss the inbox when done" -> CLI: tossinbox toss
```
## Agent discovery surfaces
If you are an AI agent or LLM reading this: everything below is
machine-readable and kept up to date.
- [llms.txt](./llms.txt) at the repository root — full onboarding in one file
- [llms.txt on the website](https://tossinbox.pages.dev/llms.txt)
- [MCP Server Card](https://tossinbox.pages.dev/.well-known/mcp/server-card.json)
- [Agent skill (SKILL.md)](https://tossinbox.pages.dev/.well-known/agent-skills/tossinbox/SKILL.md)
· [skills index](https://tossinbox.pages.dev/.well-known/agent-skills/index.json)
- [API catalog (RFC 9727)](https://tossinbox.pages.dev/.well-known/api-catalog)
- [ARD manifest](https://tossinbox.pages.dev/.well-known/ard.json)
- Markdown mirrors of every docs page: send `Accept: text/markdown` to
[tossinbox.pages.dev](https://tossinbox.pages.dev/) or fetch `/index.md`,
`/quickstart.md`, `/cli.md`, `/agents.md`, `/faq.md`
## Providers
| Provider | API key | Notes |
|---|---|---|
| `mailtm` (default) | not required | mail.tm — reliable, fast |
| `mailgw` | not required | mail.gw — mail.tm-compatible API on independent infrastructure |
| `guerrillamail` | not required | GuerrillaMail — classic fallback |
| `tempmaillol` | not required | tempmail.lol — random inbox on rotating domains |
| `tempmailio` | not required | temp-mail.io — server-generated address, `toss` deletes server-side |
| `tempmailplus` | not required | tempmail.plus — pick-your-name inbox on 9 public domains |
| `maildrop` | not required | maildrop.cc — public inbox on one stable domain |
Adding a provider means implementing a small interface (`createInbox`,
`listMessages`, `readMessage`, optional `destroyInbox`) — PRs welcome.
**Attachments** (v0.1.6): full list + download on `mailtm`, `mailgw` and
`tempmailplus`; `tempmailio` shows them when its upstream returns them
(downloadable only if it exposes a URL); `tempmaillol`, `guerrillamail` and
`maildrop` do not expose attachments upstream — TossInbox tells you that
instead of guessing.
## FAQ
**Is it really free?**
Yes. MIT-licensed, and all seven upstream providers are free with no API keys.
**Can it send email?**
No — receive-only by design. TossInbox exists for privacy and testing and
ships no bulk-send or bulk-signup mode.
**Does it work on Windows?**
Yes, anywhere Node.js 18+ runs. `npx tossinbox@latest spawn`
works in PowerShell exactly the same.
**What if a provider is down?**
`spawn` fails over automatically: it retries the create against the remaining
providers and reports the switch (human mode prints a `⚠` warning and
`provider : mailtm (failover from mailgw)`; `--json` returns a `failover`
object). Use `--no-failover` if you need the chosen provider or nothing.
**Can I download attachments?**
Yes on `mailtm`, `mailgw` and `tempmailplus`; `tempmailio` shows them when its
upstream exposes them; the other three providers have no attachments upstream.
`tossinbox read --save` writes them (plus the HTML/plain-text bodies) to
`./tossinbox-attachments//`.
**A site blocked my disposable address. What now?**
Some sites blocklist known disposable domains. Try the other provider:
`tossinbox spawn -p guerrillamail`. If both are blocked, the site wins that
round.
## Privacy and safety
- The local state file (`~/.tossinbox/state.json`, override with
`TOSSINBOX_STATE`) contains provider tokens and is written with `0600`
permissions.
- `toss` deletes the account on the provider when supported, then wipes local
state.
- Disposable email is for privacy and testing — not for abuse. Please respect
each provider's terms of service.
## Roadmap
- [x] GitHub Action: `mohamed-khairy-5i/tossinbox@v1`
- [x] Homebrew tap: `brew install mohamed-khairy-5i/tap/tossinbox`
- [x] Project website at [tossinbox.pages.dev](https://tossinbox.pages.dev/)
- [x] Publish `tossinbox` + `tossinbox-mcp` to the [npm registry](https://www.npmjs.com/package/tossinbox)
- [x] `mail.gw` provider (v0.1.3)
- [x] Four more providers: `tempmail.lol`, `temp-mail.io`, `tempmail.plus`, `maildrop.cc` (v0.1.4)
- [x] Provider failover: auto-switch when a provider is down (v0.1.5)
- [x] Attachments & HTML bodies: `read --save` / `--html` (v0.1.6)
- [ ] Homebrew core formula (after community adoption)
## Documentation
- [Quickstart](https://tossinbox.pages.dev/quickstart) — first inbox in four commands
- [CLI reference](https://tossinbox.pages.dev/cli) — every command, flag, and exit code
- [Agents & MCP](https://tossinbox.pages.dev/agents) — setup for every MCP client
- [FAQ](https://tossinbox.pages.dev/faq) — privacy, providers, troubleshooting
- [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
- [Roadmap](https://tossinbox.pages.dev/roadmap) — what shipped and what is next
- [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md) · [Security](./SECURITY.md)
## License
[MIT](./LICENSE) © Mohamed Khairy