tempmail-watcher

A disposable inbox in one command. The verification code lands in your clipboard.

Install • Usage • Scripting • How it works • FAQ

_{Sped up. Rendered from the tool's real output by demo.py.}

Paste the address into a signup form, and by the time you switch back, the code or confirmation link is already in your clipboard. Useful for testing signup flows, QA, and keeping your real address out of throwaway registrations.

• Zero setup. No account, no API key, no dependencies. It's a single Python file.
• Finds the right thing. Codes like 482913, 482-913 or ABC-789, and ranked confirmation links. Zip codes, promo codes, unsubscribe and tracking links are ignored.
• Clipboard first. The address is copied right away, then the code or link the moment it arrives, with a desktop notification.
• Scriptable. --raw and --json output and meaningful exit codes for test pipelines.
• Runs everywhere. Linux (Wayland and X11), macOS, Windows and WSL, all tested in CI.
• Two providers. GuerrillaMail by default, Mail.tm as an alternative.

Install

# Recommended: an isolated install with pipx
pipx install tempmail-watcher

# Or with uv
uv tool install tempmail-watcher

# Or with pip
python -m pip install tempmail-watcher

Requires Python 3.10+. On Linux, clipboard support needs wl-clipboard (Wayland) or xclip/xsel (X11).

curl -fsSLO https://raw.githubusercontent.com/omsingh02/tempmail-watcher/main/tempmail.py
python3 tempmail.py          # Windows: py tempmail.py

Usage

tempmail                         # new inbox, wait, copy the code or link, exit
tempmail -o                      # also open the confirmation link in your browser
tempmail -a                      # just print and copy a fresh address
tempmail -w                      # keep watching (multi-step signups)
tempmail -r                      # resume the last inbox (within 60 minutes)
tempmail -p mailtm               # use Mail.tm instead of GuerrillaMail
tempmail -u mybot99 -d grr.la    # choose the username and domain

Emails without a code or link, like welcome mails and newsletters, are shown and skipped. Run tempmail --help for everything else.

Scripting

Create an address, run your signup test with it, then wait for the code:

email=$(tempmail -a --no-copy-address)             # create an address
./my-signup-test.sh "$email"                       # sign up with it
otp=$(tempmail -r --raw | sed -n 's/^OTP: //p')    # wait for the code

--raw prints EMAIL:, then OTP:, LINK:, FROM: and SUBJECT: lines per email. --json prints one event per line. If the timeout passes without a code or link, the exit code is 124.

How it works

1. Creates an inbox on GuerrillaMail or Mail.tm and copies the address.
2. Polls the inbox every 2.5 seconds, for up to 5 minutes by default.
3. Reads each email, extracts codes and ranks the links, then copies the best match, notifies you and exits.

Clipboard and notifications use what each platform provides: wl-copy/xclip/xsel and notify-send on Linux, pbcopy and Notification Center on macOS, the Windows clipboard and toast notifications on Windows and WSL. If a tool is missing, that step is skipped and everything is still printed.

Privacy and security

⚠️ Temporary inboxes are not private. Anyone who knows a GuerrillaMail address can read its inbox, so don't use these addresses for accounts or data you care about.

• Email content is treated as untrusted: control characters are stripped before printing, and --open only opens links that look like real verification links.
• To make -r work, the provider session is saved in your user cache directory, readable only by you. Delete it to forget the inbox.
• Please respect the terms of the sites you sign up for and the providers' fair-use limits.

Found a vulnerability? See the security policy.

FAQ

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md to get started.

License

MIT © Om Singh. Not affiliated with GuerrillaMail or Mail.tm.