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:

IMAP_HOST=127.0.0.1          # Server hostname
IMAP_PORT=1143               # Server port
IMAP_USER=[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.

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.

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

Returns JSON with full body (text + HTML).

search

Search emails with filters.

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.

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.

node scripts/imap.js list-mailboxes

Cron Integration

Set up periodic email checking with Clawdbot cron:

# 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