Skip to content

README.md

Latest commit

 

History

History
165 lines (131 loc) · 4.36 KB

README.md

File metadata and controls

165 lines (131 loc) · 4.36 KB

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