imap-idle
Event-driven email monitoring using IMAP IDLE protocol. Replaces polling with instant push notifications via OpenClaw webhooks. Use when setting up email monitoring, replacing hourly email checks, or implementing event-driven email processing. Monitors multiple IMAP accounts, triggers webhooks on new mail, zero tokens while waiting.
Why use this skill?
Integrate real-time email monitoring into OpenClaw with the imap-idle skill. Replace polling with instant, event-driven push notifications and save tokens.
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/topitip/imap-idleWhat This Skill Does
The imap-idle skill transforms how OpenClaw interacts with your email inbox by shifting from inefficient polling to a real-time, event-driven architecture using the IMAP IDLE protocol. Traditionally, agents rely on cron jobs or periodic timers to check for new mail, which is not only resource-intensive and prone to high latency but also wastes valuable AI tokens by executing checks when no new mail exists.
By establishing a persistent connection to your mail server, imap-idle remains dormant until the server actively notifies it of incoming messages. Once an email arrives, the skill triggers an OpenClaw webhook, waking your agent instantly. This ensures a near-zero latency experience while maintaining maximum efficiency, as the system consumes zero processing tokens while waiting for new activity.
Installation
Installation is streamlined via the OpenClaw ecosystem. First, ensure your OpenClaw gateway is configured to accept webhooks by setting the 'enabled' flag to true in your ~/.openclaw/openclaw.json file. Next, install the necessary Python dependencies using pip3 install imapclient keyring. Using the keyring library is highly recommended, as it protects your email credentials by storing them in your operating system's secure keychain rather than in plain text configuration files. Once dependencies are resolved, execute ./imap-idle setup to walk through the account configuration wizard, then start the process with ./imap-idle start.
Use Cases
- Automated Customer Support: Instantly trigger ticket creation in your CRM the moment a client sends an email.
- Real-Time Alerting: Monitor server uptime reports or security alerts, ensuring your AI agent can respond to outages within seconds rather than waiting for the next polling cycle.
- Personal Productivity: Use the agent to automatically summarize or categorize incoming emails into your workflow management tool the second they hit your inbox.
- High-Volume Email Processing: Eliminate redundant checks to save on API costs while keeping your agent's response time competitive.
Example Prompts
- "Hey OpenClaw, monitor my support inbox and alert me the moment an email with the subject 'Urgent' arrives."
- "OpenClaw, please trigger a summary process every time I receive a new email from my project manager, but wait for 10 seconds to debounce multiple messages."
- "Can you show me the current status of my email listener to ensure I haven't missed any incoming client inquiries?"
Tips & Limitations
To maximize the reliability of the imap-idle skill, ensure your mail provider supports the IMAP IDLE command (most major providers like Gmail, Outlook, and self-hosted Dovecot/Postfix do). If you are using a custom mail server, check the firewall settings to ensure the IDLE command isn't being dropped by an idle timeout policy on the server side. Additionally, leverage the 'debounce_seconds' configuration parameter if you receive frequent email newsletters; this prevents your agent from waking up too often by batching events within a specified window. Always prefer the 'keyring' integration over editing the JSON configuration files directly to maintain high security standards.
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-topitip-imap-idle": {
"enabled": true,
"auto_update": true
}
}
}Tags(AI)
Flags: network-access, file-read, file-write, external-api