imap-email – OpenClaw Skill

---

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 "sender@example.com" --unseen

Configuration

Create .env in the skill folder or set environment variables:

IMAP_HOST=127.0.0.1          # Server hostname
IMAP_PORT=1143               # Server port
IMAP_USER=your@email.com
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

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:

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 "important@company.com" --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

Install in skill folder:

cd skills/imap-email
npm install imap-simple dotenv

Or install globally:

npm install -g imap-simple dotenv

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

IMAP Email Skill

Read and manage email via IMAP protocol. Built for ProtonMail Bridge, but works with any IMAP server.

Quick Setup (ProtonMail Bridge)

1. Run the setup helper:

   cd skills/imap-email
   ./setup.sh
   

2. Get your Bridge credentials:

   • Open ProtonMail Bridge app
   • Go to Settings → IMAP/SMTP
   • Note your email address and IMAP password
   • Default IMAP port is usually 1143

3. Enter credentials when prompted

4. Test the connection:

   node scripts/imap.js check
   

Usage

Check for new emails

node scripts/imap.js check --limit 10
node scripts/imap.js check --recent 2h        # Last 2 hours
node scripts/imap.js check --recent 30m       # Last 30 minutes

Fetch specific email

node scripts/imap.js fetch <uid>

Search emails

node scripts/imap.js search --unseen
node scripts/imap.js search --from "sender@example.com"
node scripts/imap.js search --subject "important"
node scripts/imap.js search --recent 24h      # Last 24 hours
node scripts/imap.js search --recent 7d       # Last 7 days
node scripts/imap.js search --since "2026-01-20"

Time format:

• 30m = last 30 minutes
• 2h = last 2 hours
• 7d = last 7 days

Mark as read/unread

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

List mailboxes

node scripts/imap.js list-mailboxes

Integration with Clawdbot

Manual email check

From any Clawdbot session:

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

Automated email checking (cron)

Set up periodic checks:

clawdbot cron add \
  --name "email-check-hourly" \
  --cron "0 * * * *" \
  --session isolated \
  --message "Check email inbox and summarize any new emails" \
  --deliver \
  --channel imessage \
  --to "+15551234567"

The agent will automatically use this skill to check email and deliver summaries.

Configuration

Create a .env file in this folder with your IMAP settings:

# IMAP Email Configuration

# ProtonMail Bridge (example)
IMAP_HOST=127.0.0.1
IMAP_PORT=1143
IMAP_USER=your@protonmail.com
IMAP_PASS=bridge_generated_password
IMAP_TLS=false
IMAP_REJECT_UNAUTHORIZED=false  # Set to false for self-signed certs (e.g., ProtonMail Bridge)
IMAP_MAILBOX=INBOX

# Gmail IMAP (example)
# IMAP_HOST=imap.gmail.com
# IMAP_PORT=993
# IMAP_USER=your@gmail.com
# IMAP_PASS=app_specific_password
# IMAP_TLS=true
# IMAP_REJECT_UNAUTHORIZED=true  # Default (omit this line for standard IMAP servers)
# IMAP_MAILBOX=INBOX

Configuration options:

• IMAP_HOST - Server hostname
• IMAP_PORT - Server port
• IMAP_USER - Your email address
• IMAP_PASS - Your password or app-specific password
• IMAP_TLS - Use TLS (false for STARTTLS, true for SSL)
• IMAP_REJECT_UNAUTHORIZED - Accept self-signed certs (set to false for ProtonMail Bridge)
• IMAP_MAILBOX - Default mailbox (INBOX)

Troubleshooting

Connection errors:

• Verify IMAP server is running and accessible
• Check host/port settings in .env
• Test connectivity: telnet <host> <port>
• For ProtonMail Bridge: Verify Bridge app is running

Authentication failed:

• Verify email address and password in .env
• For Gmail: Use App Password (not account password if 2FA enabled)
• For ProtonMail Bridge: Use password from Bridge app (Settings → IMAP/SMTP)

TLS/SSL errors:

• For self-signed certs (ProtonMail Bridge): Set IMAP_REJECT_UNAUTHORIZED=false
• Match port to TLS setting (993 for SSL, 143 for STARTTLS)

Empty results:

• Check mailbox name (case-sensitive)
• Run node scripts/imap.js list-mailboxes to see available folders

Files

• SKILL.md - Skill documentation (loaded by Clawdbot)
• scripts/imap.js - Main IMAP CLI tool
• package.json - Node.js dependencies
• .env - Your credentials (created by setup.sh or manually)
• setup.sh - Interactive setup helper

Security

• .env contains sensitive credentials - keep it private
• Add .env to .gitignore if publishing this skill
• Use app-specific passwords when available (Gmail, Outlook, etc.)
• For ProtonMail Bridge: Password is generated by Bridge app, not your account password

Next Steps

1. Run ./setup.sh to configure credentials
2. Test with node scripts/imap.js check
3. Set up a cron job for automated email checking
4. Customize email summaries by adjusting the cron message template