eMail manager lite

---

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

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 | Filter by sender | --from "boss@company.com" | | --subject | Filter by subject keywords | --subject "invoice" | | --since | Emails after date | --since "Jan 1, 2026" | | --before | Emails before date | --before "Feb 1, 2026" | | --unseen | Only unread emails | --unseen | | --seen | Only read emails | --seen | | --body | Search in body (slow!) | --body "meeting" | | --limit | 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  

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