imap-idle-watcher

What This Skill Does

The imap-idle-watcher is a high-performance, persistent background service designed for real-time email monitoring on Linux systems. Unlike traditional email clients or agents that use 'polling' (repeatedly checking for mail, which is inefficient and often subject to API rate limits), this skill utilizes the IMAP IDLE command. This allows the server to 'push' notifications directly to your machine the moment a message hits the inbox. By leveraging App Passwords, it bypasses the friction of OAuth token refreshes and expiration issues, ensuring a set-it-and-forget-it reliability that is perfect for long-running automation pipelines.

Installation

To begin, ensure you have the OpenClaw agent installed and the required system dependencies for a Linux environment with systemd. You can install the skill by running the command: clawhub install openclaw/skills/skills/axellageraldinc/imap-idle-watcher. Once installed, you can trigger the interactive setup script via bash scripts/setup_service.sh, which will guide you through provider detection and service installation. For advanced users or headless deployments, you can use the non-interactive mode by supplying flags for your account credentials and command path. The service automatically handles reconnections and ensures your script is triggered within seconds of email arrival.

Use Cases

This skill is ideal for any scenario requiring immediate reaction to incoming email. Common use cases include:

1. Real-time Alerting: Triggering push notifications or Slack webhooks when an invoice or high-priority email arrives.
2. Automation Pipelines: Converting email-based triggers into database updates or cloud functions without waiting for a sync interval.
3. System Monitoring: Monitoring email-based alerts from servers or hardware that report errors to a specific address.
4. Workflow Integration: Automating data entry into CRM or project management tools as soon as a client inquiry is received.

Example Prompts

1. "Monitor my inbox for any emails from '[email protected]' with the subject 'Invoice' and append the metadata to my ~/invoices.csv file."
2. "Set up a service that watches my Gmail and runs a Python script to forward the subject and sender of any new email to my Discord webhook."
3. "I need a persistent listener on my server that alerts me via a terminal notification whenever an email with the word 'Urgent' in the subject line arrives."

Tips & Limitations

• Security: Always use App Passwords instead of your primary account password. The skill will prompt you to generate these based on your provider.
• Linux Only: This tool requires systemd for process management. It will not function on Windows or macOS.
• Filtering: Use the FILTER_FROM and FILTER_SUBJECT environment variables to reduce the overhead of unnecessary script executions, ensuring your custom handlers only fire for relevant communications.
• Scope: This skill is strictly for watching/triggering. It does not possess the capability to send, reply, or parse the body of the emails itself—your custom handler script must perform those specific actions.