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

CODEBLOCK1

Test connection only

CODEBLOCK2

Configuration (env vars)

Variable	Default	Description
INLINECODE0	(required)	Email address
INLINECODE1

Filtering

Only process emails matching specific senders or subjects:

CODEBLOCK3

- 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
INLINECODE15	INLINECODE16
INLINECODE17

Workflow

1. 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 INLINECODE25

Example: user says "notify me about new emails"

Agent writes ~/email-handler.py:
CODEBLOCK4

Then wires it up:
CODEBLOCK5

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

How It Works

1. 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

CODEBLOCK6

Uninstall

CODEBLOCK7

Provider Setup Guides

Troubleshooting

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

IMAP IDLE 监视器

实时邮件监视器。使用 IMAP IDLE（服务器推送）而非轮询。
使用应用密码而非 OAuth — 无令牌过期，无需重新认证。

快速开始

交互式

bash bash scripts/setup_service.sh

提示输入邮箱，自动检测提供商，提供应用密码链接，测试连接，安装服务。

非交互式

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

仅测试连接

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

配置（环境变量）

变量	默认值	描述
IMAPACCOUNT	（必填）	邮箱地址
IMAPPASSWORD

过滤

仅处理匹配特定发件人或主题的邮件：

bash
FILTER_FROM=paypal.com,stripe.com # 发件人包含任一（OR）
FILTER_SUBJECT=payment,invoice # 主题包含任一（OR）

- 不区分大小写的子字符串匹配
如果同时设置了 FROM 和 SUBJECT，两者必须都匹配（AND）
在每个过滤器内，任意值匹配（OR）
未设置过滤器 = 处理所有邮件

编写处理器

代理应根据用户意图编写处理器脚本。守护进程通过环境变量传递邮件元数据：

变量	示例
MAILFROM	John Doe <john@example.com>
MAILSUBJECT

工作流程

1. 用户描述他们想要的功能（例如监视我的收件箱，总结新邮件）
代理编写一个处理器脚本（Python/Bash），读取环境变量并执行用户要求的操作
代理将其保存在持久化位置（例如 ~/email-handler.py）
代理运行 setup_service.sh，参数为 --command python3 ~/email-handler.py

示例：用户说有新邮件时通知我

代理编写 ~/email-handler.py：
python
#!/usr/bin/env python3
import os
print(f来自 {os.environ.get(MAILFROM, ?)} 的新邮件：{os.environ.get(MAILSUBJECT, ?)})

然后进行配置：
bash
bash scripts/setup_service.sh --account user@gmail.com --password xxxx \
--command python3 ~/email-handler.py

处理器是代理的任务 — 根据用户需求进行调整。

工作原理

1. 使用应用密码连接到 IMAP 服务器（SSL）
进入 IDLE 模式 — 服务器保持连接打开
新邮件到达时服务器推送通知（即时，无需轮询）
守护进程运行 ONNEWMAILCMD，并将邮件元数据作为环境变量传递（MAILFROM、MAILSUBJECT、MAILDATE、MAIL_UID）
返回 IDLE 模式。根据 RFC 2177 每 20 分钟续订一次。
断开连接时自动重连（退避策略：5秒 → 10秒 → 30秒 → 60秒 → 120秒）

服务管理

bash
systemctl status
journalctl -u -f
systemctl restart
systemctl stop

卸载

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

提供商设置指南

- Gmail：参见 references/gmail.md
Outlook：参见 references/outlook.md
Yahoo：参见 references/yahoo.md

故障排除

常见错误及修复方法，请参见 references/troubleshooting.md。

imap-idle-watcherIMAP空闲监控