email-otp

# Email OTP Skill A skill for creating temporary email addresses and automatically extracting OTP codes and validation links from incoming emails. Uses the free mail.tm API (no API key required). ## When to Use This Skill Invoke this skill when the user asks to: - Create a temporary email address - Get a disposable email for signup/verification - Check for OTP (one-time password) codes - Wait for email verification links - Monitor an inbox for authentication codes ## Quick Start ```bash # Create a new temporary email python3 scripts/tempmail_otp.py create # Monitor for OTP codes (5 minute timeout) python3 scripts/tempmail_otp.py check # List current account and messages python3 scripts/tempmail_otp.py list ``` ## Commands ### Create Account ```bash python3 scripts/tempmail_otp.py create [OPTIONS] ``` **Options:** - `-e, --email ADDRESS` - Custom full email address - `-d, --domain DOMAIN` - Specific domain to use - `-p, --password PASSWORD` - Account password (auto-generated if not specified) - `--json` - Output as JSON **Example:** ```bash python3 scripts/tempmail_otp.py create --domain "marcilzo.com" ``` ### Check for OTP/Links ```bash python3 scripts/tempmail_otp.py check [OPTIONS] ``` **Options:** - `--timeout SECONDS` - Max seconds to wait (default: 300) - `--poll SECONDS` - Poll interval in seconds (default: 3) - `--sender EMAIL` - Only accept emails from this sender - `--subject TEXT` - Only accept emails with this in subject - `--pattern REGEX` - Custom regex pattern for OTP extraction - `--once` - Exit after first OTP found - `--json` - Output messages as JSON **Examples:** ```bash # Wait up to 2 minutes for OTP python3 scripts/tempmail_otp.py check --timeout 120 # Only accept emails from noreply@example.com python3 scripts/tempmail_otp.py check --sender "noreply@example.com" # Exit immediately after finding OTP python3 scripts/tempmail_otp.py check --once ``` ### List Account and Messages ```bash python3 scripts/tempmail_otp.py list ``` Shows the current account details and all messages in the inbox with extracted links. ### List Available Domains ```bash python3 scripts/tempmail_otp.py domains [--json] ``` ## Output Files When an OTP or link is found, the script automatically saves them to the unified state directory: - `~/.tempmail_otp/last_otp` - Contains the last extracted OTP code - `~/.tempmail_otp/last_link` - Contains the first interesting validation link found - `~/.tempmail_otp/account.json` - Account credentials (JWT token, email, password) All state files are stored in `~/.tempmail_otp/` with restricted permissions (0600). ## OTP Detection Patterns The script automatically detects OTP codes using these patterns: - 6-8 digit numbers (most common) - 4 digit numbers - "code: XXXXXX" format - "verification: XXXXXX" format - "otp: XXXXXX" format ## Link Extraction The script extracts all HTTP/HTTPS links from email HTML, filtering out: - Unsubscribe links - Tracking links - Image files (.png, .jpg, .gif) ## State Management All state is stored in a unified directory: `~/.tempmail_otp/` - `account.json` - Account credentials and JWT token (created by `create` command) - `last_otp` - Most recent OTP code extracted (created by `check` command) - `last_link` - First validation link extracted (created by `check` command) Files have restricted permissions (0600) for security. The `check` and `list` commands automatically use stored credentials. ### Design Rationale The unified state directory follows best practices for CLI tools: 1. **No project pollution** - No temporary files are created in your working directory 2. **Predictable location** - All state is in one place, easy to find and clean up 3. **Cross-session persistence** - Works from any directory on your system 4. **Permission safety** - Sensitive credentials have proper file permissions To reset all state: `rm -rf ~/.tempmail_otp/` ## Typical Workflow 1. **Create account** - Generate a new temporary email address 2. **Use email** - Provide the email during service signup 3. **Monitor inbox** - Run the check command to wait for OTP/link 4. **Extract code** - OTP is automatically displayed and saved to `~/.tempmail_otp/last_otp` 5. **Verify** - Use the OTP or link to complete verification ## Example Session ```bash # Create a temp email $ python3 scripts/tempmail_otp.py create Email: a3b7c9d4@marcilzo.com Password: f8e4d2a1-1234-5678-9abc-123456789abc Domain: marcilzo.com Account saved to /home/user/.tempmail_otp/account.json # In another terminal, wait for OTP $ python3 scripts/tempmail_otp.py check --once Monitoring: a3b7c9d4@marcilzo.com Timeout: 300s | Poll interval: 3s -------------------------------------------------- 📧 New email from: noreply@service.com Subject: Your verification code ✅ OTP FOUND: 842197 OTP saved to /home/user/.tempmail_otp/last_otp -------------------------------------------------- ``` ## Error Handling - If email address is already taken, the script automatically retries with a new username - Network errors are logged and the script continues polling - Invalid account state prompts to recreate the account ## API This skill uses the mail.tm REST API: - Base URL: `https://api.mail.tm` - Authentication: JWT Bearer token - No API key required ## Notes - Temporary emails may expire after inactivity periods - Some services may block temporary email domains - The script automatically handles account creation and JWT token management - OTP patterns cover most common formats, but custom regex can be provided via `--pattern`