imap-email

name	imap-email
description	Read and manage email via IMAP (ProtonMail Bridge, Gmail, etc.). Check for new/unread messages, fetch content, search mailboxes, and mark as read/unread. Works with any IMAP server including ProtonMail Bridge.

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:

node skills/imap-email/scripts/imap.js check

Fetch specific email:

node skills/imap-email/scripts/imap.js fetch <uid>

Mark as read:

node skills/imap-email/scripts/imap.js mark-read <uid>

Search mailbox:

node skills/imap-email/scripts/imap.js search --from "[e-mail]" --unseen

Configuration

Quick setup (ProtonMail Bridge):

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=[e-mail]
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 "[phone]"

Inside the isolated session, the agent can run:

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 "[e-mail]" --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:

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