IMAP IDLE Watcher

通过应用密码连接 Gmail、Outlook、Yahoo 等 IMAP 服务器，以 IDLE 模式实时监听收件箱；检测到新邮件后运行用户指定命令，并提供 systemd 服务安装、断线重连、过滤与卸载流程。仅支持 Linux systemd，不负责发送或解析邮件正文。

axellageraldinc

热度 54.44

最近更新 2026-05-18 12:28:28

分类：自动化依赖：代码执行 / 读写文件 / 第三方 API应用场景：自动化脚本 / 工作流

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add imap-idle-watcher

Metadata

name: imap-idle-watcher
description: Real-time email monitoring using IMAP IDLE — no OAuth, no token expiration. Sets up a persistent connection to any IMAP server (Gmail, Outlook, Yahoo, etc.) and triggers a user-defined command instantly when new email arrives. Runs as a systemd service with auto-reconnect. Use when: (1) setting up email-triggered automation, (2) watching an inbox for new messages in real-time, (3) replacing OAuth-based email polling that keeps breaking due to token expiry, (4) building email-to-webhook or email-to-script pipelines. NOT for: sending email, reading/parsing email bodies, or non-Linux systems without systemd.

IMAP IDLE Watcher

Real-time email watcher. Uses IMAP IDLE (server push) instead of polling. App passwords instead of OAuth — no token expiry, no re-auth.

Quick Start

Interactive

bash scripts/setup_service.sh

Prompts for email, detects provider, gives app password link, tests connection, installs service.

Non-interactive

bash scripts/setup_service.sh \
  --account "user@gmail.com" \
  --password "xxxx xxxx xxxx xxxx" \
  --command "python3 /path/to/handler.py" \
  --service-name my-watcher

Test connection only

bash scripts/setup_service.sh --test --account "user@gmail.com" --password "xxxx"

Configuration (env vars)

Variable	Default	Description
`IMAP_ACCOUNT`	(required)	Email address
`IMAP_PASSWORD`	(required)	App password
`IMAP_HOST`	`imap.gmail.com`	IMAP server (auto-detected from email)
`IMAP_PORT`	`993`	IMAP port
`IMAP_FOLDER`	`INBOX`	Folder to watch
`ON_NEW_MAIL_CMD`	(optional)	Shell command to run on new mail
`FILTER_FROM`	(optional)	Only trigger for these senders (comma-separated, substring match)
`FILTER_SUBJECT`	(optional)	Only trigger for these subjects (comma-separated, substring match)
`IDLE_TIMEOUT`	`1200`	Seconds before IDLE renewal (max 1740)
`DEBOUNCE_SECONDS`	`10`	Min seconds between command runs

Filtering

Only process emails matching specific senders or subjects:

FILTER_FROM=paypal.com,stripe.com      # from contains either (OR)
FILTER_SUBJECT=payment,invoice         # subject contains either (OR)

Case-insensitive substring match
Both FROM and SUBJECT must match if both set (AND)
Within each filter, any value matches (OR)
No filter set = process all emails

Writing a Handler

The agent should write a handler script based on the user's intent. The daemon passes email metadata as env vars:

Variable	Example
`MAIL_FROM`	`John Doe <john@example.com>`
`MAIL_SUBJECT`	`Your order has shipped`
`MAIL_DATE`	`Mon, 17 Mar 2026 10:30:00 +0700`
`MAIL_UID`	`12345`

Workflow

User describes what they want (e.g. "watch my inbox, summarize new emails")
Agent writes a handler script (Python/Bash) that reads the env vars and does what the user asked
Agent saves it somewhere persistent (e.g. ~/email-handler.py)
Agent runs setup_service.sh with --command "python3 ~/email-handler.py"

Example: user says "notify me about new emails"

Agent writes ~/email-handler.py:

#!/usr/bin/env python3
import os
print(f"New mail from {os.environ.get('MAIL_FROM', '?')}: {os.environ.get('MAIL_SUBJECT', '?')}")

Then wires it up:

bash scripts/setup_service.sh --account "user@gmail.com" --password "xxxx" \
  --command "python3 ~/email-handler.py"

The handler is the agent's job — adapt it to whatever the user needs.

How It Works

Connects to IMAP server with app password (SSL)
Enters IDLE mode — server holds connection open
Server pushes notification when new mail arrives (instant, no polling)
Daemon runs ON_NEW_MAIL_CMD with email metadata as env vars (MAIL_FROM, MAIL_SUBJECT, MAIL_DATE, MAIL_UID)
Returns to IDLE. Renews every 20 min per RFC 2177.
Auto-reconnects on disconnect (backoff: 5s → 10s → 30s → 60s → 120s)

Service Management

systemctl status <service-name>
journalctl -u <service-name> -f
systemctl restart <service-name>
systemctl stop <service-name>

Uninstall

bash scripts/setup_service.sh --uninstall --service-name <service-name>

Provider Setup Guides

Troubleshooting

See references/troubleshooting.md for common errors and fixes.