Skill: jorgermp/email-manager-lite (version 1.0.1)

--- name: portable-email-manager version: 0.2.0 description: Lightweight email manager with IMAP/SMTP support, advanced search, folder management, and attachment detection. Works with Zoho, Gmail, Outlook, and any IMAP/SMTP provider. --- # Email Manager Lite v0.2 A fully self-contained email management skill for OpenClaw. Uses standard IMAP and SMTP protocols with zero external dependencies. ## ✨ What's New in v0.2 ### 🔍 Advanced Search & Filters - Search by sender (`--from`) - Search by subject keywords (`--subject`) - Filter by date range (`--since`, `--before`) - Filter by read/unread status (`--seen`, `--unseen`) - Search in email body (`--body`, warning: can be slow) ### 📁 Folder Management - List all IMAP folders with `folders` command - Move emails between folders with `move` command - Automatic validation of folder existence ### 📎 Attachment Information - Automatic detection of attachments - Display attachment details: - Filename - MIME type - File size (formatted KB/MB) - Shown in both `read` and `search` results ## 🔧 Installation ```bash cd skills/portable-email-manager npm install ``` Dependencies are bundled in `package.json`: - `nodemailer` - SMTP email sending - `imap-simple` - IMAP operations - `mailparser` - Email parsing and attachment detection ## 🔐 Credentials Set these environment variables: ```bash export EMAIL_USER="[REDACTED_SECRET]" export EMAIL_PASS="your-app-password" ``` **Recommended:** Use App Passwords for Gmail, Outlook, Zoho instead of main password. ### Provider Setup **Zoho Mail (default):** - Already configured for `smtp.zoho.eu` and `imap.zoho.eu` - Generate App [REDACTED_SECRET] **Gmail:** - Edit `scripts/email.js` and change: ```javascript host: 'smtp.gmail.com' // SMTP host: 'imap.gmail.com' // IMAP ``` - Enable 2FA and create App [REDACTED_SECRET] **Outlook/Hotmail:** - Edit to use `smtp.office365.com` / `outlook.office365.com` - Port 587 for SMTP (TLS) ## 📖 Usage ### Send Email ```bash ./scripts/email.js send "[REDACTED_SECRET]" "Subject" "Email body text" ``` **Example:** ```bash ./scripts/email.js send "[REDACTED_SECRET]" "Weekly Report" "Attached is this week's summary." ``` ### Read Recent Emails ```bash ./scripts/email.js read [limit] ``` **Examples:** ```bash # Read last 5 emails (default) ./scripts/email.js read # Read last 20 emails ./scripts/email.js read 20 ``` **Output includes:** - UID (unique ID for moving) - From/To addresses - Subject and date - Attachment count and details - Email body preview (first 500 chars) ### Advanced Search ```bash ./scripts/email.js search [options] ``` **Search Options:** | Option | Description | Example | |--------|-------------|---------| | `--from <email>` | Filter by sender | `--from "[REDACTED_SECRET]"` | | `--subject <text>` | Filter by subject keywords | `--subject "invoice"` | | `--since <date>` | Emails after date | `--since "Jan 1, 2026"` | | `--before <date>` | Emails before date | `--before "Feb 1, 2026"` | | `--unseen` | Only unread emails | `--unseen` | | `--seen` | Only read emails | `--seen` | | `--body <text>` | Search in body (slow!) | `--body "meeting"` | | `--limit <n>` | Max results | `--limit 10` | **Examples:** ```bash # Find unread emails from specific sender ./scripts/email.js search --from "[REDACTED_SECRET]" --unseen # Search by subject ./scripts/email.js search --subject "invoice" --limit 5 # Date range search ./scripts/email.js search --since "Jan 15, 2026" --before "Feb 1, 2026" # Search in body (use sparingly - can be slow) ./scripts/email.js search --body "quarterly review" # Combine multiple filters ./scripts/email.js search --from "[REDACTED_SECRET]" --subject "urgent" --unseen --limit 3 ``` ### List Folders ```bash ./scripts/email.js folders ``` Shows hierarchical tree of all IMAP folders with attributes. **Example output:** ``` 📁 INBOX 📁 Sent 📁 Archive 📁 Drafts 📁 Spam 📁 Trash ``` ### Move Email to Folder ```bash ./scripts/email.js move <uid> <folder-name> ``` **Important:** - Get the `uid` from `read` or `search` output - Folder name is case-sensitive - Script validates folder exists before moving **Examples:** ```bash # First, find the email and note its UID ./scripts/email.js search --from "[REDACTED_SECRET]" # Output shows: UID: 12345 # Move to Archive folder ./scripts/email.js move 12345 "Archive" # Move to custom folder ./scripts/email.js move 67890 "Projects/Work" ``` **Error handling:** - If folder doesn't exist, shows list of available folders - Validates UID exists before attempting move ### Help ```bash ./scripts/email.js help ``` Shows complete usage guide with all commands and examples. ## 🎯 Use Cases ### Daily Email Triage ```bash # Check unread emails ./scripts/email.js search --unseen --limit 10 # Move newsletters to folder ./scripts/email.js search --from "[REDACTED_SECRET]" --limit 1 ./scripts/email.js move <uid> "Newsletters" ``` ### Find Specific Email ```bash # Search by sender and subject ./scripts/email.js search --from "[REDACTED_SECRET]" --subject "proposal" # Search by date ./scripts/email.js search --since "Jan 20, 2026" --subject "meeting notes" ``` ### Archive Old Emails ```bash # Find old read emails ./scripts/email.js search --before "Dec 1, 2025" --seen --limit 50 # Move each to Archive (use UID from output) ./scripts/email.js move <uid> "Archive" ``` ### Check for Attachments ```bash # Read recent emails and see attachment info ./scripts/email.js read 10 # Search output automatically shows: # - Number of attachments # - Filename, type, and size for each ``` ## 🔒 Security - Credentials never logged or stored in files - TLS/SSL encryption for all connections - App Passwords recommended over account passwords - No data leaves your machine except IMAP/SMTP connections ## ⚙️ Configuration Default configuration is optimized for **Zoho Mail EU**. To use another provider, edit `scripts/email.js`: ```javascript // SMTP Configuration const smtpConfig = { host: 'smtp.your-provider.com', port: 465, // or 587 for TLS secure: true, // true for SSL (465), false for TLS (587) auth: { user: EMAIL_USER, pass: EMAIL_PASS } }; // IMAP Configuration const imapConfig = { imap: { user: EMAIL_USER, [REDACTED_SECRET], host: 'imap.your-provider.com', port: 993, tls: true, authTimeout: 20000 } }; ``` ## 🚀 Performance Notes - **Body search** (`--body`) can be slow on large mailboxes - use sparingly - **Subject/From search** is fast - uses IMAP server-side filtering - **Date filters** are efficient - Limit results with `--limit` for faster responses ## 🐛 Troubleshooting **"Authentication failed"** - Verify EMAIL_USER and EMAIL_PASS are set correctly - Use App Password, not account password - Check provider settings (2FA, less secure apps, etc.) **"Folder not found"** - Use `folders` command to see exact folder names - Folder names are case-sensitive - Some providers use different names (e.g., "Sent Items" vs "Sent") **"Connection timeout"** - Check firewall/network settings - Verify IMAP/SMTP ports are accessible - Try increasing `authTimeout` in config **"No emails found"** - Check search criteria - Verify emails exist in INBOX (not other folders) - Try broader search (remove some filters) ## 📝 Version History ### v0.2.0 (Current) - ✨ Advanced search with multiple filters - 📁 Folder management (list, move) - 📎 Attachment detection and info - 🎨 Improved output formatting - 📚 Comprehensive documentation ### v0.1.0 - Basic send/read functionality - Zoho Mail support - IMAP/SMTP foundation ## 🤝 Compatibility Tested with: - ✅ Zoho Mail (EU & US) - ✅ Gmail - ✅ Outlook/Hotmail - ✅ iCloud Mail - ✅ Custom IMAP/SMTP servers ## 💡 Tips 1. **Use UIDs for automation:** Save UIDs from search results to move emails programmatically 2. **Combine filters:** Multiple filters create AND conditions for precise searches 3. **Folder organization:** List folders first to plan your organization strategy 4. **Date format:** Use natural language dates like "Jan 1, 2026" or "December 25, 2025" 5. **Attachment filtering:** Look for "Attachments: X" in search output to find emails with files ## 📄 License ISC - Use freely in your OpenClaw setup.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: clean (LOW)