tossinbox
Provides a GitHub Action (mohamed-khairy-5i/tossinbox@v1) that runs TossInbox inside GitHub Actions workflows, allowing real signup/verification email flows to be tested in CI by waiting for a disposable inbox to receive a message and exposing the inbox address and extracted OTP code as workflow outputs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tossinbox create an inbox and wait for the verification code from example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.comRelated MCP server: agent-inbox
Why TossInbox
For humans — stop exposing your real address to every signup form.
For agents — built agent-first from day one:
--jsonoutput on every commanddocumented 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.txtat the repository root for LLM-friendly onboarding
TossInbox | temp-mail websites | tmpmail-era CLIs | |
JSON on every command |
| 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+.
# Homebrew (macOS, Linux)
brew install mohamed-khairy-5i/tap/tossinbox
# npm (npmjs.com)
npm install -g tossinbox
# Or run without installing
npx tossinbox@latest spawnFrom source:
git clone https://github.com/mohamed-khairy-5i/tossinbox.git
cd tossinbox
npm install
npm run build
node dist/cli.js --helpQuickstart
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 stateEvery command also accepts --json for machine-readable output:
tossinbox spawn --json
tossinbox wait --code --jsonCLI Reference
Command | Description |
| Create a new disposable inbox ( |
| List messages ( |
| Read a full message, including any detected code; lists attachments. |
| Poll until a message arrives ( |
| Stream new messages until Ctrl-C — only new arrivals; |
| List locally saved inboxes |
| Delete an inbox server-side and remove it from local state ( |
| Remove all inboxes from local state only |
| List available email providers |
| Run the MCP server over stdio |
Exit codes
A stable contract: agents script against these, not against stdout.
Code | Meaning |
| Success |
| Error (provider / network / unexpected) |
| Timeout ( |
| Not found (no saved inbox, unknown address, or message missing) |
| 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:
- 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 a disposable inbox and return its address |
| List messages in an inbox |
| Read a full message, including any detected code; reports attachment metadata and can save attachments + bodies to disk ( |
| Poll until a message arrives and return its verification code |
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 —
--jsonon every command, exit codes0–4documented, zero interactive promptsCI/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 tossAgent 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
Markdown mirrors of every docs page: send
Accept: text/markdownto tossinbox.pages.dev or fetch/index.md,/quickstart.md,/cli.md,/agents.md,/faq.md
Providers
Provider | API key | Notes |
| not required | mail.tm — reliable, fast |
| not required | mail.gw — mail.tm-compatible API on independent infrastructure |
| not required | GuerrillaMail — classic fallback |
| not required | tempmail.lol — random inbox on rotating domains |
| not required | temp-mail.io — server-generated address, |
| not required | tempmail.plus — pick-your-name inbox on 9 public domains |
| 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 <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 withTOSSINBOX_STATE) contains provider tokens and is written with0600permissions.tossdeletes 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@v1Homebrew tap:
brew install mohamed-khairy-5i/tap/tossinboxProject website at tossinbox.pages.dev
Publish
tossinbox+tossinbox-mcpto the npm registrymail.gwprovider (v0.1.3)Four more providers:
tempmail.lol,temp-mail.io,tempmail.plus,maildrop.cc(v0.1.4)Provider failover: auto-switch when a provider is down (v0.1.5)
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
License
MIT © Mohamed Khairy
Available Tools
4 toolscreate_inboxCreate a disposable inboxA
Create a brand new disposable email inbox. The inbox is saved locally so the other tools can use it. Returns the full email address to use in sign-up forms.
Inputs: label, provider, no_failover.
list_messagesList inbox messagesA
List the messages currently in a disposable inbox (defaults to the most recently created inbox).
Inputs: address.
read_messageRead a messageA
Read the full body of a message by id, including any verification code detected in it. Lists attachment metadata; pass save_dir to also save the attachments and the HTML body to disk (where the provider supports downloads).
Inputs: id (required), address, save_dir.
wait_for_codeWait for a verification codeA
Poll a disposable inbox until a message arrives, then return the verification code (OTP) found in it. Ideal right after submitting a sign-up form. Times out gracefully.
Inputs: from, address, subject, timeout_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: create, list, read, and wait-for-code. There is no functional overlap between them.
All tool names follow a consistent verb_noun pattern: create_inbox, list_messages, read_message, wait_for_code. The naming is uniform and predictable.
Four tools is an ideal size for a disposable inbox service. Each tool covers a necessary step in the workflow without redundancy or bloat.
The core lifecycle is well covered: creation, listing, reading, and polling for codes. A minor gap is the lack of an explicit delete_inbox or get_inbox, but these are not essential for the stated purpose.
Maintenance
Related MCP Connectors
Disposable email inboxes for AI agents: create an address, wait for mail, read OTP codes and links.
Disposable email inboxes for AI agents: create an address, wait for the OTP or verify link.
Disposable email inboxes for AI agents — read messages and verification codes.
Real email inboxes for AI agents: create inboxes, catch verification codes, extract OTPs, reply.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to create disposable email inboxes and automatically extract OTPs, magic links, and verification codes from incoming emails.10 npmMIT
- AlicenseAqualityDmaintenanceEnables AI agents to create temporary email addresses, receive confirmation emails, and extract verification links, automating sign-up and email verification workflows without manual intervention.627 npm64MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to generate temporary email addresses, receive emails, and automatically extract OTP codes and links from incoming messages for automation and testing workflows.MIT
- AlicenseNot gradedqualityBmaintenanceDisposable email for humans and AI agents. Enables AI agents to create mailboxes and receive verification emails through an MCP server.39MIT