back
loading skill details...
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.
--- 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:** ```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 "sender@example.com" --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:** ```bash 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 ``` **⚠️ 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. ```bash 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. ```bash node scripts/imap.js fetch <uid> [--mailbox INBOX] ``` Returns JSON with full body (text + HTML). ### search Search emails with filters. ```bash 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. ```bash 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. ```bash node scripts/imap.js list-mailboxes ``` ## Cron Integration Set up periodic email checking with Clawdbot cron: ```bash # 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 "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 **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`
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit intent, comprehensive inputs section with server configs and external connections, numbered procedure steps with inputs/outputs, decision points for ProtonMail, Gmail, auth, TLS, rate limits, and empty results, detailed output contract for all commands, and outcome signals for each operation.
read, search, and manage email via IMAP protocol. supports ProtonMail Bridge, Gmail IMAP, and any standard IMAP server. use this skill when you need to check for new messages, fetch full email content, search across mailboxes with filters, or change message flags (read/unread). works in isolation or integrated into cron jobs and agent workflows for periodic email monitoring and digests.
environment variables (required):
IMAP_HOST: server hostname (e.g., 127.0.0.1, imap.gmail.com)IMAP_PORT: server port (e.g., 1143 for ProtonMail Bridge, 993 for Gmail SSL)IMAP_USER: email address or account usernameIMAP_PASS: IMAP password or app-specific passwordIMAP_TLS: boolean, use TLS/SSL connection (true for SSL on port 993, false for STARTTLS on port 143)IMAP_REJECT_UNAUTHORIZED: boolean, validate server certificate (set false for self-signed certs like ProtonMail Bridge, omit or true for public servers)IMAP_MAILBOX: default mailbox name (default: INBOX)setup file location: .env in skill folder, copy from .env.example, never commit to git.
external dependencies: imap-simple (npm package), mailparser (npm package), dotenv (npm package). run npm install in skill folder.
external connections:
127.0.0.1:1143common server configs:
127.0.0.1, port 1143, TLS false, reject-unauthorized falseimap.gmail.com, port 993, TLS true, reject-unauthorized true (default), requires app password if 2FA enabledimap-mail.outlook.com, port 993, TLS true, reject-unauthorized trueset up environment: copy .env.example to .env in skill folder, fill in IMAP credentials for your server (use ProtonMail Bridge password, not account password, for ProtonMail; use app-specific password for Gmail with 2FA).
verify connection: run node scripts/imap.js list-mailboxes to confirm IMAP server responds and authentication succeeds. if connection fails, check host, port, TLS setting, and reject-unauthorized flag.
check for new emails: run node scripts/imap.js check [--limit N] [--mailbox NAME] [--recent TIME] to list unread/new messages. default limit 10, default mailbox INBOX. optional --recent flag (e.g., 2h, 7d) filters to emails in last X time. outputs JSON array with uid, from, subject, date, snippet, flags.
search emails: run node scripts/imap.js search [options] with filters: --unseen (unread only), --seen (read only), --from (sender), --subject (text), --since (YYYY-MM-DD), --before (YYYY-MM-DD), --recent (time format), --limit (max results, default 20), --mailbox (folder name). returns JSON array of matching message UIDs and metadata.
fetch full email: run node scripts/imap.js fetch <uid> [--mailbox NAME] to retrieve complete email body (text + HTML), headers, and attachment info. requires valid UID from check or search step.
mark message flags: run node scripts/imap.js mark-read <uid> [uid2 uid3...] to flag message(s) as read, or node scripts/imap.js mark-unread <uid> [uid2 uid3...] to flag as unread. accepts multiple UIDs in single command.
list mailboxes: run node scripts/imap.js list-mailboxes to enumerate all available folders/labels (e.g., INBOX, Sent, Drafts, custom folders). useful for verifying mailbox names before search/check operations.
127.0.0.1, port 1143, TLS to false, reject-unauthorized to false, use Bridge-generated password (not account password).telnet <host> <port>), verify host and port are correct in .env, check firewall does not block port.false, verify port matches TLS mode.check command output: JSON array, each object contains:
["\Seen", "\Flagged"])search command output: JSON array, each object contains:
fetch command output: JSON object containing:
mark-read / mark-unread output: JSON object:
list-mailboxes output: JSON array of mailbox objects:
["\All", "\HasNoChildren"])/ or .)all outputs are UTF-8 JSON written to stdout.