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

Related MCP server: useblip/email

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.

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.

FAQ

Is it really free? Yes. MIT-licensed, and both 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.

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

• GitHub Action: mohamed-khairy-5i/tossinbox@v1

• Homebrew tap: brew install mohamed-khairy-5i/tap/tossinbox

• Project website at tossinbox.pages.dev

• Publish tossinbox + tossinbox-mcp to the npm registry

• mail.gw provider (mail.tm-compatible API — small lift)

• tempmail.lol provider (free API)

• Provider failover: auto-switch when a provider is down

• 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

• Changelog · Contributing · Security

License

MIT © Mohamed Khairy