Skip to main content
Glama

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.

CI npm npm downloads License: MIT Node MCP

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

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

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+.

# 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

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

Read a full message, including any detected code; lists attachments. --html prints the raw HTML body, --save [dir] downloads attachments + bodies to <dir>/<message-id>/

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:

- 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

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

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

  • 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 (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

License

MIT © Mohamed Khairy

Available Tools

4 tools
create_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

    A4.1/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: create, list, read, and wait-for-code. There is no functional overlap between them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: create_inbox, list_messages, read_message, wait_for_code. The naming is uniform and predictable.

    Tool Count5/5

    Four tools is an ideal size for a disposable inbox service. Each tool covers a necessary step in the workflow without redundancy or bloat.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to create disposable email inboxes and automatically extract OTPs, magic links, and verification codes from incoming emails.
      10 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to create temporary email addresses, receive confirmation emails, and extract verification links, automating sign-up and email verification workflows without manual intervention.
      6
      27 npm
      64
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Disposable email for humans and AI agents. Enables AI agents to create mailboxes and receive verification emails through an MCP server.
      39
      MIT