Source Code

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

Use UIDs for automation: Save UIDs from search results to move emails programmatically
Combine filters: Multiple filters create AND conditions for precise searches
Folder organization: List folders first to plan your organization strategy
Date format: Use natural language dates like "Jan 1, 2026" or "December 25, 2025"
Attachment filtering: Look for "Attachments: X" in search output to find emails with files

📄 License

ISC - Use freely in your OpenClaw setup.

email-manager-lite

Email Manager Lite v0.2

✨ What's New in v0.2

🔍 Advanced Search & Filters

📁 Folder Management

📎 Attachment Information

🔧 Installation

🔐 Credentials

Provider Setup

📖 Usage

Send Email

Read Recent Emails

Advanced Search

List Folders

Move Email to Folder

Help

🎯 Use Cases

Daily Email Triage

Find Specific Email

Archive Old Emails

Check for Attachments

🔒 Security

⚙️ Configuration

🚀 Performance Notes

🐛 Troubleshooting

📝 Version History

v0.2.0 (Current)

v0.1.0

🤝 Compatibility

💡 Tips

📄 License