Tossinbox

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.

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

$ tossinbox spawn
✔ Inbox ready : qwd6996p1lbc@uberip.com
  provider    : mailtm

$ tossinbox wait --code --from noreply@github.com --timeout 120
✔ Verify your device
  from : GitHub <noreply@github.com>
  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 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

Checked September 2026. If a cell is wrong, open an issue and win the argument.

Install

Requires Node.js 18+.

# 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:

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:

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:

tossinbox spawn --json
tossinbox wait --code --json

CLI Reference

Exit codes

A stable contract: agents script against these, not against stdout.

GitHub Action (email verification in CI)

Use TossInbox directly in your workflows to test real signup / verification email flows:

- 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:

Claude Desktop / Cursor / any MCP client

{
  "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)

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 at the repository root — full onboarding in one file
• llms.txt on the website
• MCP Server Card
• Agent skill (SKILL.md) · skills index
• API catalog (RFC 9727)
• ARD manifest
• Markdown mirrors of every docs page: send Accept: text/markdown to tossinbox.pages.dev or fetch /index.md, /quickstart.md, /cli.md, /agents.md, /faq.md

Providers

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 <id> --save writes them (plus the HTML/plain-text bodies) to ./tossinbox-attachments/<message-id>/.

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
• [x] Publish tossinbox + tossinbox-mcp to the npm registry
• [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 — first inbox in four commands
• CLI reference — every command, flag, and exit code
• Agents & MCP — setup for every MCP client
• FAQ — privacy, providers, troubleshooting
• Examples — copy-paste recipes: shell, CI, Node.js, MCP
• Guide — providers, state, flags, exit codes, troubleshooting
• Roadmap — what shipped and what is next
• Changelog · Contributing · Security

License

MIT © Mohamed Khairy