SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI agentstossinbox

tossinbox

Disposable email for AI agents: create a throwaway inbox, wait for the OTP verification code, then discard it. Also available as a CLI.

Open website

About this tool

TossInbox is a temporary email (temp-mail) CLI tool and MCP server, aimed at human users and AI agents, with the core purpose of: generating a one-time inbox, waiting for verification emails, extracting OTP verification codes, and finally discarding it. The project was created by Mohamed Khairy and is licensed under MIT.

Purpose: to avoid exposing real email addresses to various registration forms, while serving registration flows, QA email flows, and test automation; it also allows AI agents to complete all operations through the built-in MCP server.

Main capabilities:

  • Create a brand-new one-time email address with a single command, wait for the verification email to arrive, extract the OTP code, and delete the inbox when done (both server-side and locally).
  • All commands support --json output for machine parsing; humans read normal output, agents parse --json.
  • Documented exit codes 0–4, with no interactive prompts.
  • Built-in MCP server that exposes several tools, enabling Claude, Cursor, and any MCP client to create inboxes and read verification codes as native tools.
  • Provides llms.txt at the repository root for LLM-friendly onboarding.
  • Supports a GitHub Action to test real registration/verification email flows in CI, outputting address (the one-time inbox) and code (the extracted OTP).
  • Provides seven upstream free providers, with no API key required; supports automatic failover when a provider fails.
  • Attachments (v0.1.6): full listing and download are supported on mailtm, mailgw, and tempmailplus; tempmailio displays attachments when its upstream returns them (downloadable only when the upstream exposes a URL); tempmaillol, guerrillamail, and maildrop upstreams do not expose attachments, and TossInbox clearly states this rather than guessing.
  • Attachments (as well as HTML/plain-text bodies) can be written to ./tossinbox-attachments/<message-id>/ via tossinbox read <id> --save.

Usage:

  • Requires Node.js 18+, with additional installation options including Homebrew, npm, npx, and a GitHub Action.
  • Four commandsComplete the flow from zero to discarding the inbox; every command can also be given --json for machine-readable output.
  • MCP server configuration: Claude Desktop / Cursor / any MCP client; after a global install, the tossinbox-mcp command can be used directly, equivalent to npx -y tossinbox mcp.
  • When used with AI agents, the CLI itself is the interface: --json, documented exit codes 0–4, zero interactive prompts.

Use cases:

  • Personal privacy protection: no longer expose your real address to every signup form.
  • Agent automation: any MCP client (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI, etc.) as well as any agent with shell capability.
  • CI/CD: test signup and verification email flows via GitHub Action, without an agent.

Limitations and notes:

  • Receiving email only, sending email is not supported; there is no bulk sending or bulk signup mode.
  • Free and MIT licensed, all seven upstream providers are free and require no API key; however, if a site blocks a known disposable email domain, you can try another provider, and if both are blocked it cannot be used.
  • The local state file (~/.tossinbox/state.json, can be overridden with TOSSINBOX_STATE) stores provider tokens with permissions 0600; the toss command deletes the account when the provider supports it, then clears the local state.
  • Temporary email is for privacy and testing, must not be abused, please comply with each provider's terms.
  • Also available on Windows: as long as Node.js 18+ can run, npx tossinbox@latest spawn behaves consistently in PowerShell.

Other details:

  • The project website and documentation are at tossinbox.pages.dev.
  • Agent-oriented discovery entry points are provided: llms.txt in the repository root, llms.txt on the website, MCP Server Card, Agent skill (SKILL.md) and skill index, API catalog (RFC 9727), and a Markdown mirror of each documentation page (you can send Accept: text/markdown to tossinbox.pages.dev, or fetch /index.md, /quickstart.md, /cli.md, /agents.md, /faq.md).
  • Adding a provider only requires implementing a small interface (createInbox, listMessages, readMessage, optionally destroyInbox).
  • Installation methods include: GitHub Action (mohamed-khairy-5i/tossinbox@v1), Homebrew tap (brew install mohamed-khairy-5i/tap/tossinbox), npm published packages tossinbox + tossinbox-mcp.
  • Version evolution includes: mail.gw provider (v0.1.3), four additional providers tempmail.lol, temp-mail.io, tempmail.plus, maildrop.cc (v0.1.4), provider failover (v0.1.5), attachments and HTML body (v0.1.6).
  • The project also provides documentation such as Quick Start, CLI Reference, Agents and MCP, FAQ, Examples, Guides, Roadmap, Changelog, Contributing, and Security.

Specific command examples, installation command details, configuration steps for each MCP client, etc. are only described in general terms in the material, and complete item-by-item content is not provided, so they are not expanded here.

Related tools

Browse category