imap-email

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