# Send Imap Idle Review to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "imap-idle", "name": "Imap Idle Review", "source": "tencent", "type": "skill", "category": "效率提升", "sourceUrl": "https://clawhub.ai/topitip/imap-idle", "canonicalUrl": "https://clawhub.ai/topitip/imap-idle", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/imap-idle", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=imap-idle", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "CHANGELOG.md", "README.md", "SECURITY.md", "SKILL.md", "scripts/listener.py", "scripts/listener_old.py" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "imap-idle", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T04:59:34.146Z", "expiresAt": "2026-05-07T04:59:34.146Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=imap-idle", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=imap-idle", "contentDisposition": "attachment; filename=\"imap-idle-1.4.0.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "imap-idle" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/imap-idle" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/imap-idle", "downloadUrl": "https://openagent3.xyz/downloads/imap-idle", "agentUrl": "https://openagent3.xyz/skills/imap-idle/agent", "manifestUrl": "https://openagent3.xyz/skills/imap-idle/agent.json", "briefUrl": "https://openagent3.xyz/skills/imap-idle/agent.md" } } ``` ## Documentation ### IMAP IDLE Listener Event-driven email notifications for OpenClaw using IMAP IDLE protocol. ### What This Does Replaces polling-based email checks with push notifications: Before (polling): Cron job checks email every hour 16-24 checks per day Up to 1 hour delay for new emails Token burn on empty checks After (IMAP IDLE): Persistent connection to IMAP server Server pushes notification when new mail arrives <1 second notification latency Zero tokens while waiting ### 1. Enable OpenClaw Webhooks Edit ~/.openclaw/openclaw.json: { "hooks": { "enabled": true, "token": "generate-secure-random-token-here", "path": "/hooks" } } Restart gateway: openclaw gateway restart ### 2. Install Dependencies pip3 install imapclient --user --break-system-packages Optional but recommended: Install keyring for secure password storage: pip3 install keyring --user --break-system-packages With keyring, passwords are stored in your system's secure keychain (macOS Keychain, GNOME Keyring, etc.) instead of plain text in config files. ### 3. Run Setup ./imap-idle setup Follow the interactive wizard to configure: IMAP account(s) (host, port, username, password) OpenClaw webhook URL and token Log file location ### 4. Start Listener ./imap-idle start Verify it's running: ./imap-idle status ./imap-idle logs ### 5. Test Send yourself an email. You should see: Log entry in listener logs OpenClaw wakes instantly Email processed in main session ### CLI Commands imap-idle start # Start listener in background imap-idle stop # Stop listener imap-idle restart # Restart listener imap-idle status # Check if running imap-idle logs # Show recent logs (default: 50 lines) imap-idle logs N # Show last N lines imap-idle setup # Run interactive setup wizard ### Configuration Config file: ~/.openclaw/imap-idle.json { "accounts": [ { "host": "mail.example.com", "port": 993, "username": "user@example.com", "password": "password", "ssl": true } ], "webhook_url": "http://127.0.0.1:18789/hooks/wake", "webhook_token": "your-webhook-token", "log_file": "~/.openclaw/logs/imap-idle.log", "idle_timeout": 300, "reconnect_interval": 900, "debounce_seconds": 10 } Fields: accounts - Array of IMAP accounts to monitor webhook_url - OpenClaw webhook endpoint webhook_token - Webhook authentication token (from openclaw.json) log_file - Path to log file (null for stdout) idle_timeout - IDLE check timeout in seconds (default: 300 = 5 min) reconnect_interval - Full reconnect interval in seconds (default: 900 = 15 min) debounce_seconds - Batch events for N seconds before webhook (default: 10 sec) ### Secure Password Storage (Keyring) 🔐 Recommended: Store passwords in system keychain instead of config file. ### Setup with Keyring When you run ./imap-idle setup, the wizard will ask if you want to use keyring. If you say yes: Passwords are stored in your system's secure keychain Config file only contains usernames (no passwords) Keyring uses OS-level encryption ### Manual Keyring Setup If you already have a config with plain text passwords, migrate to keyring: # Install keyring pip3 install keyring --user --break-system-packages # Store password for each account python3 -c " import keyring, getpass username = 'user@example.com' password = getpass.getpass(f'Password for {username}: ') keyring.set_password('imap-idle', username, password) " # Remove password from config # Edit ~/.openclaw/imap-idle.json and remove "password" field ### How Keyring Works The listener automatically tries keyring first, then falls back to config: Try keyring.get_password('imap-idle', username) If not found, use config['password'] If still no password, abort connection ### Security Benefits ✅ No plain text passwords in config files ✅ OS-level encryption (macOS Keychain, GNOME Keyring, Windows Credential Manager) ✅ Reduces VirusTotal false positives ✅ Better security audit trail ### How It Works Connect: Opens persistent IMAP connection per account IDLE: Enters IDLE mode (server will push notifications) Wait: Blocks until server sends "new mail" notification Fetch: Retrieves new email headers (From, Subject, body preview) Queue: Adds event to debounce buffer (batches for 10 seconds) Webhook: Sends batched events via webhook (single or grouped) Resume: Re-enters IDLE mode Key Implementation Details: Debouncing: Batches emails for 10 seconds before webhook to prevent flooding during spikes (e.g., GitHub mention storms) Smart Batching: Single email → full details, multiple emails → grouped summary with counts UID Tracking: Tracks last processed message UID per account to prevent duplicate webhooks Keep-alive: IDLE timeout every 5 minutes, sends NOOP command Reconnect: Full reconnect every 15 minutes to prevent stale connections Threading: One thread per account for concurrent monitoring Error handling: Exponential backoff (5s → 300s) on connection failures ### Systemd Service (Optional) For automatic startup on boot: Generate service file: skill_dir="$(pwd)" listener_script="$skill_dir/scripts/listener.py" config_file="$HOME/.openclaw/imap-idle.json" log_file="$HOME/.openclaw/logs/imap-idle.log" log_dir="$(dirname "$log_file")" sed -e "s|%USER%|$USER|g" \\ -e "s|%PYTHON%|$(which python3)|g" \\ -e "s|%LISTENER_SCRIPT%|$listener_script|g" \\ -e "s|%CONFIG_FILE%|$config_file|g" \\ -e "s|%LOG_FILE%|$log_file|g" \\ -e "s|%LOG_DIR%|$log_dir|g" \\ imap-idle.service.template > imap-idle.service Install service: sudo cp imap-idle.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable imap-idle sudo systemctl start imap-idle Check status: sudo systemctl status imap-idle sudo journalctl -u imap-idle -f ### Troubleshooting Listener won't start: Check config file exists: cat ~/.openclaw/imap-idle.json Verify imapclient installed: python3 -c "import imapclient" Check logs: imap-idle logs Duplicate webhooks: Fixed in v2 - uses UID tracking to prevent duplicates Check logs for "UID tracking" messages Connection drops: Increase reconnect_interval in config Check IMAP server allows IDLE (most do) Verify firewall allows persistent connections No webhooks triggering: Test webhook manually: curl -X POST http://127.0.0.1:18789/hooks/wake \\ -H "Authorization: Bearer YOUR_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{"text": "test", "mode": "now"}' Check OpenClaw config: hooks.enabled: true Verify token matches in both configs ### Removing Polling Once IMAP IDLE is working, remove old polling cron jobs: # List cron jobs openclaw cron list # Remove email check job openclaw cron remove ### Token Savings Before: 16-24 email checks per day Each check = ~500-1000 tokens (even if no new mail) Total: ~8,000-24,000 tokens/day for email monitoring After: 0 tokens while waiting Tokens only spent when email actually arrives 90%+ reduction in email-related token usage ### Credits Inspired by @claude-event-listeners' critique on Moltbook about polling vs event-driven architecture. Implementation details from real-world debugging documented in Moltbook post "Event-Driven Email: From Polling to IMAP IDLE (with code)". ## Trust - Source: tencent - Verification: Indexed source record - Publisher: topitip - Version: 1.4.0 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-04-30T04:59:34.146Z - Expires at: 2026-05-07T04:59:34.146Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/imap-idle) - [Send to Agent page](https://openagent3.xyz/skills/imap-idle/agent) - [JSON manifest](https://openagent3.xyz/skills/imap-idle/agent.json) - [Markdown brief](https://openagent3.xyz/skills/imap-idle/agent.md) - [Download page](https://openagent3.xyz/downloads/imap-idle)