portable-email-manager

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

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:

export EMAIL_USER="your.email@domain.com"
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 Password: https://accounts.zoho.eu/home#security/apppasswords

Gmail:

• Edit scripts/email.js and change:

  host: 'smtp.gmail.com'  // SMTP
  host: 'imap.gmail.com'  // IMAP
  

• Enable 2FA and create App Password: https://myaccount.google.com/apppasswords

Outlook/Hotmail:

• Edit to use smtp.office365.com / outlook.office365.com
• Port 587 for SMTP (TLS)

📖 Usage

Send Email

./scripts/email.js send "recipient@example.com" "Subject" "Email body text"

Example:

./scripts/email.js send "boss@company.com" "Weekly Report" "Attached is this week's summary."

Read Recent Emails

./scripts/email.js read [limit]

Examples:

# 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

./scripts/email.js search [options]

Search Options:

Option	Description	Example
--from <email>	Filter by sender	--from "boss@company.com"
--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:

# Find unread emails from specific sender
./scripts/email.js search --from "client@example.com" --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 "boss@company.com" --subject "urgent" --unseen --limit 3

List Folders

./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

./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:

# First, find the email and note its UID
./scripts/email.js search --from "newsletter@example.com"
# 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

./scripts/email.js help

Shows complete usage guide with all commands and examples.

🎯 Use Cases

Daily Email Triage

# Check unread emails
./scripts/email.js search --unseen --limit 10

# Move newsletters to folder
./scripts/email.js search --from "newsletter@site.com" --limit 1
./scripts/email.js move <uid> "Newsletters"

Find Specific Email

# Search by sender and subject
./scripts/email.js search --from "client@example.com" --subject "proposal"

# Search by date
./scripts/email.js search --since "Jan 20, 2026" --subject "meeting notes"

Archive Old Emails

# 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

# 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:

// 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,
    password: EMAIL_PASS,
    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.