An event-driven email monitoring skill that replaces periodic polling with instant push notifications to trigger Openclaw Skills workflows.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install imap-idle
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install imap-idle using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is IMAP IDLE Listener?
The IMAP IDLE Listener is a high-performance integration designed to transition email-based AI workflows from inefficient polling to a modern, event-driven architecture. By maintaining a persistent connection to IMAP servers, this skill enables Openclaw Skills to receive immediate notifications the moment a new message arrives, rather than waiting for scheduled cron jobs. This approach effectively eliminates the delay between receiving an email and processing it with an AI agent.
Beyond speed, the primary advantage is significant resource optimization. Traditional polling methods consume thousands of tokens daily even when no new mail is present. This skill ensures that your Openclaw Skills environment remains dormant and token-efficient, only waking up when there is actual data to process. It includes robust security features like system keychain integration to keep your credentials safe while providing professional-grade logging and monitoring.
IMAP IDLE Listener Use Cases
- Reducing token costs by over 90% by eliminating empty polling cycles within Openclaw Skills.
- Implementing instant-response support bots that reply to customer inquiries in real-time.
- Building automated triaging systems for GitHub notifications or server alerts delivered via email.
- Triggering complex multi-agent workflows the second a specific keyword appears in an inbox.
How IMAP IDLE Listener Works
- The listener establishes a secure, persistent IMAP connection for every configured email account.
- It issues the IDLE command to the mail server, entering a low-power state where it waits for server-initiated updates.
- Upon receiving a new mail notification, the skill instantly fetches the relevant headers and body preview.
- Events are passed through a debouncing buffer for 10 seconds to group rapid-fire emails into a single notification.
- The processed data is sent as a secure POST request to the configured Openclaw Skills webhook endpoint.
- Internal UID tracking ensures that no email is processed more than once, even after a reconnection.
- The system automatically handles keep-alives and exponential backoff to maintain a 24/7 connection.
IMAP IDLE Listener Setup
First, enable the webhook receiver in your ~/.openclaw/openclaw.json file:
{
"hooks": {
"enabled": true,
"token": "your-secure-token",
"path": "/hooks"
}
}
Install the necessary Python dependencies for IMAP handling and secure credential storage:
pip3 install imapclient keyring --user --break-system-packages
Initialize the configuration and link your accounts to your Openclaw Skills setup:
./imap-idle setup
Start the listener in the background:
./imap-idle start
IMAP IDLE Listener Data Schema & Taxonomy
The skill manages its operations using a JSON configuration file and local state tracking to ensure reliability.
| Component | Detail |
|---|---|
| Config Path | ~/.openclaw/imap-idle.json |
| Account Storage | Supports multiple IMAP profiles with host, port, and SSL toggles. |
| Security | Supports OS-level Keychain (macOS) or Secret Service (Linux) via Python Keyring. |
| Webhook Target | Configurable endpoint URL and Bearer token for Openclaw Skills integration. |
| State Tracking | Persistent UID tracking per account to prevent duplicate processing. |
| Logging | Detailed runtime logs including connection status and event triggers. |
IMAP IDLE Listener Advanced Features
- Systemd integration for persistent background operation and automatic recovery after system reboots.
- Smart Batching which automatically switches between detailed single-email reports and grouped summaries during traffic spikes.
- Multi-threaded architecture allowing the monitoring of dozens of mailboxes simultaneously without blocking.
- Configurable IDLE timeouts and reconnection intervals to adapt to various mail provider requirements.
- Secure credential isolation that removes plain-text passwords from configuration files using system-level encryption.
SKILL.md
Loading
Related Openclaw Skills
OpenClawdy
OpenClawdy is a memory infrastructure for autonomous agents providing persistent storage, semantic recall, and cross-agent knowledge sharing.
OpenClawdy
A persistent memory infrastructure for autonomous agents that enables semantic recall, reputation tracking, and cross-agent knowledge sharing.
OpenOCR Skill
An intelligent OCR and document parsing engine that extracts text, mathematical formulas, and tables from images and PDFs with high precision.
Habitica Gamified Task Management Skill
A comprehensive gamification integration that allows AI agents to manage habits, dailies, and character progression using the Habitica API.
Agent MBTI Personality Diagnosis
A framework for diagnosing and adjusting AI Agent personalities using the MBTI psychological model to align behavior with user expectations.
Agent MBTI Personality Diagnosis & Optimization
A comprehensive system for diagnosing AI agent MBTI personality types and automatically optimizing their configuration to match user expectations.
METADATA
Featured*
