IMAP Email Reader

# IMAP Email Reader

Read, search, and manage email via IMAP protocol. Supports ProtonMail Bridge, Gmail IMAP, and any standard IMAP server.

## Quick Start

**Check for new emails:** ```bash node skills/imap-email/scripts/imap.js check ```

**Fetch specific email:** ```bash node skills/imap-email/scripts/imap.js fetch <uid> ```

**Mark as read:** ```bash node skills/imap-email/scripts/imap.js mark-read <uid> ```

**Search mailbox:** ```bash node skills/imap-email/scripts/imap.js search --from "[email protected]" --unseen ```

## Configuration

**Quick setup (ProtonMail Bridge):** ```bash cd skills/imap-email ./setup.sh ``` The setup helper will prompt for Bridge credentials and test the connection.

**Manual setup:** 1. Copy `.env.example` to `.env` in the skill folder 2. Fill in your IMAP credentials 3. The `.env` file is automatically ignored by git

**Environment variables:**

```bash IMAP_HOST=127.0.0.1 # Server hostname IMAP_PORT=1143 # Server port [email protected] IMAP_PASS=your_password IMAP_TLS=false # Use TLS/SSL connection IMAP_REJECT_UNAUTHORIZED=false # Set to false for self-signed certs (optional) IMAP_MAILBOX=INBOX # Default mailbox ```

**⚠️ Security:** Never commit your `.env` file! It's already in `.gitignore` to prevent accidents.

**ProtonMail Bridge setup:** - Install and run ProtonMail Bridge - Use `127.0.0.1:1143` for IMAP - Password is generated by Bridge (not your ProtonMail password) - TLS: Use `false` (Bridge uses STARTTLS) - `REJECT_UNAUTHORIZED`: Set to `false` (Bridge uses self-signed cert)

**Gmail IMAP setup:** - Host: `imap.gmail.com` - Port: `993` - TLS: `true` - Enable "Less secure app access" or use App Password - `REJECT_UNAUTHORIZED`: Omit or set to `true` (default)

## Commands

### check Check for unread/new emails in mailbox.

```bash node scripts/imap.js check [--limit 10] [--mailbox INBOX] [--recent 2h] ```

Options: - `--limit <n>`: Max results (default: 10) - `--mailbox <name>`: Mailbox to check (default: INBOX) - `--recent <time>`: Only show emails from last X time (e.g., 30m, 2h, 7d)

Returns JSON array of messages with: - uid, from, subject, date, snippet, flags

### fetch Fetch full email content by UID.

```bash node scripts/imap.js fetch <uid> [--mailbox INBOX] ```

Returns JSON with full body (text + HTML).

### search Search emails with filters.

```bash node scripts/imap.js search [options]

Options: --unseen Only unread messages --seen Only read messages --from <email> From address contains --subject <text> Subject contains --recent <time> From last X time (e.g., 30m, 2h, 7d) --since <date> After date (YYYY-MM-DD) --before <date> Before date (YYYY-MM-DD) --limit <n> Max results (default: 20) --mailbox <name> Mailbox to search (default: INBOX) ```

Time format examples: - `30m` = last 30 minutes - `2h` = last 2 hours - `7d` = last 7 days

### mark-read / mark-unread Mark message(s) as read or unread.

```bash node scripts/imap.js mark-read <uid> [uid2 uid3...] node scripts/imap.js mark-unread <uid> [uid2 uid3...] ```

### list-mailboxes List all available mailboxes/folders.

```bash node scripts/imap.js list-mailboxes ```

## Cron Integration

Set up periodic email checking with Clawdbot cron:

```bash # Check email every 15 minutes, deliver to iMessage clawdbot cron add \ --name "email-check" \ --cron "*/15 * * * *" \ --session isolated \ --message "Check for new ProtonMail emails and summarize them" \ --deliver \ --channel imessage \ --to "+15085600825" ```

Inside the isolated session, the agent can run: ```bash node /Users/mike/clawd/skills/imap-email/scripts/imap.js check --limit 5 ```

## Workflow Examples

**Morning email digest:** 1. Run `check --limit 10 --recent 12h` 2. Summarize unread emails from overnight 3. Deliver summary to preferred channel

**Check recent emails from specific sender:** 1. Run `search --from "[email protected]" --recent 24h` 2. Fetch full content if needed 3. Mark as read after processing

**Hourly urgent email check:** 1. Run `search --recent 1h --unseen` 2. Filter for important keywords 3. Extract action items 4. Deliver notification if urgent

**Weekly digest:** 1. Run `search --recent 7d --limit 20` 2. Summarize activity 3. Generate weekly report

## Dependencies

**Required packages:** imap-simple, mailparser, dotenv

**Installation:** ```bash cd skills/imap-email npm install ```

This will install all dependencies listed in `package.json`.

## Security Notes

- Store credentials in `.env` (add to `.gitignore`) - ProtonMail Bridge password is NOT your account password - Bridge must be running for ProtonMail IMAP access - Consider using app-specific passwords for Gmail

## Troubleshooting

**Connection timeout:** - Verify IMAP server is running and accessible - Check host/port configuration - Test with: `telnet <host> <port>`

**Authentication failed:** - Verify username (usually full email address) - Check password is correct - For ProtonMail Bridge: use Bridge-generated password, not account password - For Gmail: use App Password if 2FA is enabled

**TLS/SSL errors:** - Match `IMAP_TLS` setting to server requirements (true for SSL, false for STARTTLS) - For self-signed certs (e.g., ProtonMail Bridge): set `IMAP_REJECT_UNAUTHORIZED=false` - Check port matches TLS setting (993 for SSL, 143 for STARTTLS)

**Empty results:** - Verify mailbox name (case-sensitive) - Check search criteria - List mailboxes with `list-mailboxes`