IMAP IDLE Watcher

IMAP IDLE Watcher

Real-time emAIl watcher. Uses IMAP IDLE (server push) instead of polling. 应用 passwords instead of OAuth — no 令牌 expiry, no re-auth.

Quick 启动 Interactive bash scripts/设置up_服务.sh

Prompts for emAIl, 检测s 提供者, gives 应用 password link, tests connection, 安装s 服务.

Non-interactive bash scripts/设置up_服务.sh \ --account "user@gmAIl.com" \ --password "xxxx xxxx xxxx xxxx" \ --command "python3 /path/to/处理器.py" \ --服务-name my-watcher

Test connection only bash scripts/设置up_服务.sh --test --account "user@gmAIl.com" --password "xxxx"

Configuration (env vars) Variable Default Description IMAP_ACCOUNT (required) EmAIl 添加ress IMAP_PASSWORD (required) 应用 password IMAP_HOST imap.gmAIl.com IMAP server (auto-检测ed from emAIl) IMAP_PORT 993 IMAP port IMAP_FOLDER INBOX Folder to watch ON_NEW_MAIL_CMD (optional) Shell command to 运行 on new mAIl 过滤器_FROM (optional) Only trigger for these 发送ers (comma-separated, substring match) 过滤器_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 运行s 过滤器ing

Only process emAIls matching specific 发送ers or subjects:

过滤器_FROM=paypal.com,stripe.com # from contAIns either (OR) 过滤器_SUBJECT=payment,invoice # subject contAIns either (OR)

Case-insensitive substring match 机器人h FROM and SUBJECT must match if 机器人h 设置 (AND) Within each 过滤器, any value matches (OR) No 过滤器 设置 = process all emAIls Writing a 处理器

The 代理 should write a 处理器 script based on the user's intent. The daemon passes emAIl metadata as env vars:

Variable Example MAIL_FROM John Doe MAIL_SUBJECT Your order has shipped MAIL_DATE Mon, 17 Mar 2026 10:30:00 +0700 MAIL_UID 12345 工作流 User describes what they want (e.g. "watch my inbox, summarize new emAIls") 代理 writes a 处理器 script (Python/Bash) that reads the env vars and does what the user asked 代理 saves it somewhere persistent (e.g. ~/emAIl-处理器.py) 代理 运行s 设置up_服务.sh with --command "python3 ~/emAIl-处理器.py" Example: user says "通知 me about new emAIls"

代理 writes ~/emAIl-处理器.py:

#!/usr/bin/env python3 导入 os print(f"New mAIl from {os.environ.获取('MAIL_FROM', '?')}: {os.environ.获取('MAIL_SUBJECT', '?')}")

Then wires it up:

bash scripts/设置up_服务.sh --account "user@gmAIl.com" --password "xxxx" \ --command "python3 ~/emAIl-处理器.py"

The 处理器 is the 代理's job — adapt it to whatever the user needs.

How It Works Connects to IMAP server with 应用 password (SSL) Enters IDLE mode — server holds connection open Server pushes notification when new mAIl arrives (instant, no polling) Daemon 运行s 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) 服务 Management 系统ctl 状态 <服务-name> journalctl -u <服务-name> -f 系统ctl re启动 <服务-name> 系统ctl 停止 <服务-name>

Un安装 bash scripts/设置up_服务.sh --un安装 --服务-name <服务-name>

提供者 设置up 图形界面des GmAIl: see references/gmAIl.md Outlook: see references/outlook.md Yahoo: see references/yahoo.md Troubleshooting

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