DropMail Skill

Create and manage disposable email addresses via GuerrillaMail API. Emails expire after 60 minutes. All data is stored locally in SQLite at ~/.dropmail/dropmail.db.

What this skill accesses

Declared so its authority is reviewable before you run it — it does exactly this and no more:

• Network: HTTPS requests to https://api.guerrillamail.com/ajax.php only. No other host is contacted.
• Filesystem: reads and writes only under ~/.dropmail/ (the SQLite DB and sessions.json). Nothing else on disk is read or written.
• No shell execution, no environment-variable reads, no credentials. The skill runs no subprocesses and needs no API keys or secrets.

Privacy — read before use

This skill sends inbox traffic through a third-party service, GuerrillaMail, and keeps mailbox state on your local disk. Before using it, understand:

• GuerrillaMail sees everything sent to the disposable address — full message bodies, senders, and subjects pass through their servers. Do not route sensitive account recovery, financial, medical, or long-lived login flows through it.
• Received mail is cached locally. dropmail refresh/read store full message bodies in ~/.dropmail/dropmail.db. Disposable inboxes often carry verification codes and login links; treat that DB as sensitive and run dropmail <email> remove when done.
• Session cookies are stored on disk. Per-email PHPSESSID cookies live in ~/.dropmail/sessions.json. Anyone who can read that file could reuse your mailbox session, so the files are locked down (see Security below).
• No real identifying metadata is sent. The client sends a fixed loopback ip (127.0.0.1) and a static browser User-Agent to satisfy the API — your real IP is not put in the request payload (your network-level source IP is still visible to GuerrillaMail, as with any HTTPS call).

Installation

Create a symlink to dropmail.py on your PATH:

# System-wide: install a root-owned COPY (not a symlink). A symlink from a
# root PATH into the skill directory would run whatever later lands there;
# a copy owned by root:root can only be changed by root.
sudo install -o root -g root -m 0755 <skill-dir>/scripts/dropmail.py /usr/local/bin/dropmail

# User-local: a symlink is fine here — ~/.local/bin and the skill directory
# are both controlled by the same (non-root) user.
ln -s <skill-dir>/scripts/dropmail.py ~/.local/bin/dropmail

Data is stored at ~/.dropmail/ (auto-created on first run). Requires Python 3.7+, no extra dependencies.

Commands

dropmail new                            # Get a new disposable email
dropmail list                           # List all tracked emails with expiry status
dropmail <email> inbox                  # Show all messages in inbox
dropmail <email> inbox -c 3             # Show last 3 messages only
dropmail <email> refresh                # Fetch new messages from GuerrillaMail API
dropmail <email> read <id>              # Read full body of a message
dropmail <email> remove                 # Remove email + all messages from local DB
dropmail <email> expire                 # Show time remaining before expiry

The API request language defaults to English. Override it with --lang <code> (e.g. dropmail --lang de new) or the DROPMAIL_LANG environment variable.

Typical Workflow

1. dropmail new — get a fresh email
2. Share the email address with the untrusted service
3. dropmail <email> refresh - pull new messages from the server
4. dropmail <email> inbox - browse received messages
5. dropmail <email> read <id> - read a specific message
6. dropmail <email> remove - clean up when done

Notes

• Data location: All data stored in ~/.dropmail/ (DB + sessions). Auto-created on first run.
• Sessions: Per-email PHPSESSID cookies stored in ~/.dropmail/sessions.json. Expire after ~18 min of API inactivity.
• Offline inbox: Messages are cached locally. inbox reads from cache; refresh syncs from server.
• 403 errors: GuerrillaMail blocks non-browser User-Agents. The script uses Mozilla/5.0 by default. If blocked, check references/api.md.
• Expiry: Emails last 60 minutes. After expiry, old messages are still accessible by calling set_email_user via refresh.

Security

• TLS is always verified. API traffic uses the system CA store (falling back to certifi only if no system CAs exist). Verification is never disabled.
• Local data is private. ~/.dropmail/ is created 0700; the SQLite DB and sessions.json (which holds PHPSESSID cookies) are 0600, so other users on the machine can't read your sessions or cached mail.
• Untrusted mail is sanitized. Inbox content is attacker-controlled; terminal control/escape characters are stripped before anything is printed, preventing ANSI-escape injection into your terminal.
• CLI input is validated (email shape, numeric message IDs) before it reaches the DB or API.

API Reference

For full GuerrillaMail API details, see references/api.md. Load it when:

• Debugging API call failures
• Adding new API features (extend, delete messages, forget)
• Understanding session/cookie handling