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

AI Skill Market Insights

Be Part of the 2,711+ Developer Community