eMail manager lite

# 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

```bash 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:

```bash 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

```bash ./scripts/email.js send "[email protected]" "Subject" "Email body text" ```

**Example:** ```bash ./scripts/email.js send "[email protected]" "Weekly Report" "Attached is this week's summary." ```

### Read Recent Emails

```bash ./scripts/email.js read [limit] ```

**Examples:** ```bash # 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

```bash ./scripts/email.js search [options] ```

**Search Options:**

| Option | Description | Example | |--------|-------------|---------| | `--from <email>` | Filter by sender | `--from "[email protected]"` | | `--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:**

```bash # 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

```bash ./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

```bash ./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:**

```bash # 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

```bash ./scripts/email.js help ```

Shows complete usage guide with all commands and examples.

## 🎯 Use Cases

### Daily Email Triage ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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`:

```javascript // 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.