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="[email protected]"
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: javascript 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 "[email protected]" "Subject" "Email body text"

Example:

./scripts/email.js send "[email protected]" "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:

Examples:

# Find unread emails from specific sender
./scripts/email.js search --from "[email protected]" --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 "[email protected]" --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 "[email protected]"

# 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 "[email protected]" --limit 1
./scripts/email.js move <uid> "Newsletters"

Find Specific Email

# Search by sender and subject
./scripts/email.js search --from "[email protected]" --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.