burnbox 1.2.1

Temporary email that burns after reading

burnbox

Temporary email that burns after reading.

burnbox creates a disposable email address, watches for incoming messages, auto-detects OTP codes, copies them to your clipboard — then burns the account when you're done.

Requires Python >= 3.10.

Install

pip install burnbox

Or with pipx (recommended for CLI tools):

pipx install burnbox

How it works

1. Register — burnbox creates a temporary email account
2. Poll — watches for incoming messages every few seconds
3. Detect — finds OTP codes, verification links, and copies them to clipboard
4. Burn — deletes the account and session on exit (Ctrl+C)

The --keep flag preserves the account for later use with burnbox resume.

Quick start

$ burnbox

That's it. You'll get a temp address, it auto-copies to clipboard, and burnbox watches for messages. When a verification code arrives, it's detected and copied. Press Ctrl+C to exit — the account is deleted automatically.

╭─────────── burnbox ───────────╮
│ Temp email that burns after   │
│ reading                       │
╰───────────────────────────────╯

  Provider: mailtm
  Address:  [e-mail]
  Address copied to clipboard

  Ctrl+C to exit and burn · --keep to preserve · burnbox resume

CLI usage

Command	Description
burnbox	Create temp email, watch for messages, burn on exit
burnbox address	Generate a temp email address and exit (account is burned immediately)
burnbox resume	Reconnect to the last saved session

Options

--provider       Provider: mailtm, guerrillamail
--poll, -p       Polling interval in seconds (default: 5)
--timeout, -t    HTTP request timeout (default: 10)
--keep, -k       Keep account alive after exit
--no-clipboard   Do not copy to clipboard
--no-notify      Disable desktop notifications
--version, -v    Show version
--help, -h       Show help

Examples

# Use a specific provider
burnbox --provider guerrillamail

# Keep account alive for later resume
burnbox --keep

# Resume a kept session
burnbox resume

# One-shot: just get a temp address (burned immediately)
burnbox address

# Headless mode: no clipboard, no notifications
burnbox --no-clipboard --no-notify

Programmatic API

Use burnbox as a Python library:

import asyncio
import burnbox

async def main():
    box = await burnbox.create()
    async with box:
        print(f"Address: {box.address}")
        msg = await box.wait_for_message(timeout=60)
        if msg:
            print(f"Code: {msg.best_code}")
            print(f"From: {msg.sender}")
        # Account auto-burns on exit

asyncio.run(main())

API reference

• burnbox.create(provider=None, config=None) — Create a BurnBox instance (await it first, then use as context manager)
• box.address — The temp email address
• box.fetch_new() — Fetch new messages
• box.wait_for_message(timeout=60) — Wait for the first message (returns None on timeout)
• box.messages() — Async iterator yielding messages as they arrive
• box.burn() — Delete the account manually
• msg.id, msg.sender, msg.subject — Message metadata
• msg.content — Message body as plain text
• msg.best_code — Highest-confidence OTP code detected (string or None)
• msg.codes — All detected codes as CodeMatch objects (.value, .confidence, .kind)
• msg.links — All detected links

Configuration

Config file: ~/.config/burnbox.toml

[provider]
default = "mailtm"             # Preferred provider
custom_url = "https://..."     # Custom API URL for mailtm

[polling]
interval = 5.0                 # Seconds between polls
timeout = 10.0                  # HTTP timeout

[output]
copy_address = true             # Copy address to clipboard
copy_code = true                # Copy OTP codes to clipboard
notifications = true            # Desktop notifications on OTP

Environment variables override the config:

BURNBOX_PROVIDER=guerrillamail
BURNBOX_POLL_INTERVAL=3
BURNBOX_TIMEOUT=15
BURNBOX_CUSTOM_URL=https://...

Providers

Provider	Auth	Delete account	Domains	Custom URL
mail.tm	Register + token	Yes	Multiple	Yes
guerrillamail	Session-based	Best-effort (forget_me)	sharklasers.com, grr.la, etc	No

burnbox automatically selects the first available provider with a health check. If one is down, it falls back to the next. You can also add custom providers via the plugin system.

OTP Detection

burnbox detects verification codes from incoming emails using a multi-parser engine:

• Labeled OTP — "code: 1234", "Your verification code: 8472", "Ваш код: 5531", etc.
• Alphanumeric codes — Recovery codes, backup keys (e.g., A1B2-C3D4-E5F6)
• URL-embedded codes — ?code=, ?token=, ?otp= in links
• Reset/verify links — Password reset, account verification URLs
• Numeric OTP — Standalone digit clusters with context-aware confidence boosting

Supports 12 languages for label detection: English, Russian, German, French, Spanish, Portuguese, Chinese, Japanese, Korean, Hindi, Arabic, Turkish. Context-aware confidence boosting is available for all 12 languages.

Each match has a confidence score (0–1). The highest-confidence code is auto-copied to your clipboard and auto-cleared after 30 seconds.

Plugin system

Add custom providers via Python entry points:

# my_provider.py
from burnbox import Provider
from burnbox.models import Session, InboxMessage

class MyProvider:
    name = "myprovider"
    supports_custom_url = False

    async def is_alive(self) -> bool:
        # Check if the provider API is reachable

    async def register(self) -> Session:
        # Create a new temp email account, return Session

    async def restore(self, session: Session) -> None:
        # Restore auth state from a saved session

    async def fetch_messages(self, seen_ids: set[str]) -> list[InboxMessage]:
        # Fetch new (unseen) messages

    async def delete_account(self, account_id: str) -> bool:
        # Delete the account, return True on success

    async def aclose(self) -> None:
        # Close the HTTP client

# pyproject.toml
[project.entry-points."burnbox.providers"]
myprovider = "my_provider:MyProvider"

After pip install, burnbox discovers your provider automatically.

Security considerations

• OTP codes transit through third-party email providers. Only use burnbox for non-sensitive verifications.
• Session files are stored with 0600 permissions at ~/.config/burnbox/session.json. Files are created with restrictive permissions from the start (no exposure window).
• The account is deleted before the session file is removed, so a failed burn can be retried.
• OTP codes are auto-cleared from the clipboard after 30 seconds. An atexit handler also clears the clipboard on process termination. Clipboard managers may retain copied text.
• Notifications show only "Verification code received" — OTP values are never sent to the notification system.
• Accounts are deleted ("burned") on exit by default. Use --keep only if you need persistence.
• GuerrillaMail does not support true account deletion; forget_me abandons the session but emails may persist on the server for up to 1 hour.

Troubleshooting

• Clipboard not working on Linux: Install xclip or xsel (X11) or wl-clipboard (Wayland). burnbox detects Wayland automatically and uses wl-copy first.
• All providers down: burnbox falls back to trying providers even if health checks fail. Check your network.
• "Session expired" on resume: The temp email account has expired. Start a new one with burnbox.
• "Guerrilla Mail forget_me failed": The GuerrillaMail API may be temporarily unavailable. The session is still abandoned locally.

Development

uv sync --extra dev
uv run ruff check .
uv run mypy burnbox/
uv run pytest

License

MIT