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

CODEBLOCK0

Dependencies are bundled in package.json:

• - nodemailer - SMTP email sending
• INLINECODE13 - IMAP operations
• INLINECODE14 - Email parsing and attachment detection

🔐 Credentials

Set these environment variables:

CODEBLOCK1

Recommended: Use App Passwords for Gmail, Outlook, Zoho instead of main password.

Provider Setup

Zoho Mail (default):

• - Already configured for smtp.zoho.eu and INLINECODE16
• 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 / INLINECODE19
• Port 587 for SMTP (TLS)

📖 Usage

Send Email

CODEBLOCK3

Example:
CODEBLOCK4

Read Recent Emails

CODEBLOCK5

Examples:
CODEBLOCK6

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

CODEBLOCK7

Search Options:

Option	Description	Example
INLINECODE20	Filter by sender	INLINECODE21
INLINECODE22

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:

CODEBLOCK8

List Folders

CODEBLOCK9

Shows hierarchical tree of all IMAP folders with attributes.

Example output:
CODEBLOCK10

Move Email to Folder

CODEBLOCK11

Important:

• - Get the uid from read or search output
• Folder name is case-sensitive
• Script validates folder exists before moving

Examples:

CODEBLOCK12

Error handling:

• - If folder doesn't exist, shows list of available folders
• Validates UID exists before attempting move

Help

CODEBLOCK13

Shows complete usage guide with all commands and examples.

🎯 Use Cases

Daily Email Triage

CODEBLOCK14

Find Specific Email

CODEBLOCK15

Archive Old Emails

CODEBLOCK16

Check for Attachments

CODEBLOCK17

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

CODEBLOCK18

🚀 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 EMAILUSER and EMAILPASS 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. 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.