邮件IMAP自动抓取工具：实时监控未读邮件并转发至Webhook

email-imap-fetch by tiangong-ai/skills

145 周安装量

4 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/tiangong-ai/skills --skill email-imap-fetch

Python Web框架自动化 API

🇨🇳中文介绍

Email IMAP Fetch

核心目标

使用 IMAP IDLE 等待新邮件。
每次唤醒后获取未读邮件。
支持通过环境变量配置多个邮箱账户。
通过环境变量模式（idle 或 poll）严格控制 IDLE 支持，无需运行时探测。
将每个获取到的邮件转发到 OpenClaw webhook。
为下游步骤输出机器可读的 JSON 行。
严格将此技能保持在 stage-1 路由模式：仅发送摘要片段和结构化引用，绝不发送完整的原始邮件正文，也绝不发送附件二进制内容。

工作流程

配置账户环境变量和 OpenClaw webhook 环境变量（参见 references/env.md 和 assets/config.example.env）。

验证配置：

python3 scripts/imap_idle_fetch.py check-config

为每个账户运行一个 IDLE 周期（冒烟测试）：

python3 scripts/imap_idle_fetch.py listen --cycles 1 --idle-seconds 120 --max-messages 10

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

131,500 周安装

README 国际化工具：自动化翻译与多语言文档管理 | readme-i18n

42,200 周安装

GitHub Actions 官方文档查询助手 - 精准解答 CI/CD 工作流问题

40,500 周安装

持续运行（默认常驻模式）：

python3 scripts/imap_idle_fetch.py listen

技能文件安装在本地，但监听器不会自动启动。
在 idle 模式下，IMAP IDLE 仅在监听器进程和 IMAP 连接存活时接收推送事件。
在 poll 模式下，监听器休眠轮询间隔时间，然后获取未读邮件。
如果进程退出，推送事件将被错过；下次运行时仍可使用 UNSEEN 获取现有的未读邮件。
默认运行时是常驻模式（默认 IMAP_CYCLES=0）。
默认 IDLE 模式是 poll（对于不支持 IDLE 的服务器安全）。
在生产环境中，必须始终在线的部署应在 systemd、launchd、supervisor 或等效的守护进程管理器下运行。
不要将监听器作为绑定到交互式执行会话的前台进程运行；一旦该会话退出，监听器将停止。

输出格式为 JSONL（每行一个 JSON 对象）。
type=status 用于生命周期事件。
type=message 用于获取到的邮件，包含：
- account、mailbox、seq、uid
- subject、from、to、date
- message_id_raw、message_id_norm（以及兼容字段 message_id）
- snippet（仅纯文本预览）
- attachment_count、attachment_manifest（仅摘要，无附件内容）
- mail_ref 机器可读对象（account、mailbox、uid、message_id_raw、message_id_norm、date）
Webhook 消息包含两个固定的机器可读块，用于确定性调度提取：
- <<<MAIL_REF_JSON>>> ... <<<END_MAIL_REF_JSON>>>
- <<<ATTACHMENT_MANIFEST_JSON>>> ... <<<END_ATTACHMENT_MANIFEST_JSON>>>
wait_mode 在周期状态输出中为 idle 或 poll。
wait_events 记录活动的等待策略详情。
当 OpenClaw webhook POST 成功时，输出 event=webhook_delivered 状态事件。
type=error 用于账户级故障。
当 OpenClaw webhook POST 失败时，输出 event=webhook_failed 错误事件。

--cycles: 每个账户的 IDLE 周期数（0 表示永久）。
--idle-seconds: 每次 IDLE 调用的最大等待时间。
--poll-seconds: 轮询模式激活时使用的间隔时间。
--idle-mode: idle 或 poll。
--max-messages: 每个周期获取的最大未读邮件数。
--mark-seen / --no-mark-seen: 控制未读状态更新。
--snippet-chars: 预览长度限制。
--connect-timeout: 连接超时秒数。
--retry-seconds: 失败后的重试延迟。

环境变量默认值：

IMAP_CYCLES
IMAP_IDLE_MODE
IMAP_IDLE_SECONDS
IMAP_POLL_SECONDS
IMAP_MAX_MESSAGES
IMAP_MARK_SEEN
IMAP_SNIPPET_CHARS
IMAP_CONNECT_TIMEOUT
IMAP_RETRY_SECONDS

OpenClaw webhook 转发：

OPENCLAW_WEBHOOKS_ENABLED
OPENCLAW_WEBHOOKS_TOKEN
OPENCLAW_WEBHOOKS_BASE_URL
OPENCLAW_WEBHOOKS_MODE (agent 或 wake)
OPENCLAW_WEBHOOKS_ENDPOINT（可选的端点覆盖）
OPENCLAW_WEBHOOKS_PATH
OPENCLAW_WEBHOOKS_WAKE_MODE
OPENCLAW_WEBHOOKS_DELIVER
OPENCLAW_WEBHOOKS_TIMEOUT
OPENCLAW_WEBHOOKS_NAME
OPENCLAW_WEBHOOKS_AGENT_ID
OPENCLAW_WEBHOOKS_CHANNEL
OPENCLAW_WEBHOOKS_TO
OPENCLAW_WEBHOOKS_MODEL
OPENCLAW_WEBHOOKS_THINKING
OPENCLAW_WEBHOOKS_AGENT_TIMEOUT_SECONDS
OPENCLAW_WEBHOOKS_SESSION_KEY_PREFIX

无效的环境变量配置以代码 2 退出。
在 idle 模式下，不支持的 IDLE 返回显式错误并建议 IMAP_IDLE_MODE=poll。
运行时故障以 type=error 形式发出。
当账户处理错误发生时，命令以非零状态退出。

assets/config.example.env

scripts/imap_idle_fetch.py

🇺🇸English

Email IMAP Fetch

Core Goal

Wait for new mail with IMAP IDLE.
Fetch unread messages after each wake-up.
Support multiple mailbox accounts configured with env.
Control IDLE support strictly with env mode (idle or poll) without runtime probing.
Forward each fetched email to OpenClaw webhooks.
Emit machine-readable JSON lines for downstream steps.
Keep this skill strictly in stage-1 routing mode: send snippet + structured refs only, never send full raw message body, and never send attachment binary/content.

Workflow

Configure account env variables and OpenClaw webhook env variables (see references/env.md and assets/config.example.env).
Validate configuration:

python3 scripts/imap_idle_fetch.py check-config

Run one IDLE cycle per account (smoke test):

python3 scripts/imap_idle_fetch.py listen --cycles 1 --idle-seconds 120 --max-messages 10

Run continuously (default resident mode):

python3 scripts/imap_idle_fetch.py listen

Runtime Model

Skill files are installed locally, but the listener is not auto-started.
In idle mode, IMAP IDLE receives push events only while listener process and IMAP connection are alive.
In poll mode, listener sleeps for poll interval and then fetches unread messages.
If the process exits, push events are missed; next run can still fetch existing unread emails with UNSEEN.
Default runtime is resident mode (IMAP_CYCLES=0 by default).
Default IDLE mode is poll (safe for servers without IDLE support).
In production, always-on deployment must run under systemd, launchd, supervisor, or an equivalent daemon manager.
Do not run the listener as a foreground process bound to an interactive exec session; once that session exits, the listener will stop.

Output Contract

Output format is JSONL (one JSON object per line).
type=status for lifecycle events.
type=message for fetched emails with:
- account, mailbox, seq, uid
- subject, from, to, date
- message_id_raw, (and compatibility field )

Parameters

--cycles: IDLE cycles per account (0 means forever).
--idle-seconds: max wait time for each IDLE call.
--poll-seconds: interval used when polling mode is active.
--idle-mode: idle or poll.
--max-messages: max unread emails fetched each cycle.
--mark-seen / --no-mark-seen: control unread state updates.

Environment defaults:

IMAP_CYCLES
IMAP_IDLE_MODE
IMAP_IDLE_SECONDS
IMAP_POLL_SECONDS
IMAP_MAX_MESSAGES
IMAP_MARK_SEEN
IMAP_SNIPPET_CHARS
IMAP_CONNECT_TIMEOUT
IMAP_RETRY_SECONDS

OpenClaw webhooks forwarding:

OPENCLAW_WEBHOOKS_ENABLED
OPENCLAW_WEBHOOKS_TOKEN
OPENCLAW_WEBHOOKS_BASE_URL
OPENCLAW_WEBHOOKS_MODE (agent or wake)
OPENCLAW_WEBHOOKS_ENDPOINT (optional endpoint override)
OPENCLAW_WEBHOOKS_PATH
OPENCLAW_WEBHOOKS_WAKE_MODE
OPENCLAW_WEBHOOKS_DELIVER

Error Handling

Invalid env configuration exits with code 2.
In idle mode, unsupported IDLE returns explicit error and suggests IMAP_IDLE_MODE=poll.
Runtime failures are emitted as type=error.
Command exits non-zero when account processing errors occur.

References

references/env.md

Assets

assets/config.example.env

Scripts

scripts/imap_idle_fetch.py

Weekly Installs

119

Repository

tiangong-ai/skills

GitHub Stars

First Seen

Feb 23, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

github-copilot115

codex115

opencode115

kimi-cli114

gemini-cli114

amp114

Skills CLI 使用指南：AI Agent 技能包管理器安装与管理教程

40,000 周安装

snippet (plain-text preview only)

attachment_count, attachment_manifest (summary only, no attachment content)

mail_ref machine-readable object (account, mailbox, uid, message_id_raw, message_id_norm, date)

Webhook message includes two fixed machine-readable blocks for deterministic dispatch extraction:

<<<MAIL_REF_JSON>>> ... <<<END_MAIL_REF_JSON>>>
<<<ATTACHMENT_MANIFEST_JSON>>> ... <<<END_ATTACHMENT_MANIFEST_JSON>>>

wait_mode is idle or poll in cycle status output.

wait_events records the active wait strategy details.

event=webhook_delivered status events when OpenClaw webhook POST succeeds.

type=error for account-level failures.

event=webhook_failed error events when OpenClaw webhook POST fails.

--snippet-chars: preview length limit.

--connect-timeout: connection timeout seconds.

--retry-seconds: retry delay after failure.

OPENCLAW_WEBHOOKS_TIMEOUT

OPENCLAW_WEBHOOKS_NAME

OPENCLAW_WEBHOOKS_AGENT_ID

OPENCLAW_WEBHOOKS_CHANNEL

OPENCLAW_WEBHOOKS_TO

OPENCLAW_WEBHOOKS_MODEL

OPENCLAW_WEBHOOKS_THINKING

OPENCLAW_WEBHOOKS_AGENT_TIMEOUT_SECONDS

OPENCLAW_WEBHOOKS_SESSION_KEY_PREFIX

邮件IMAP自动抓取工具：实时监控未读邮件并转发至Webhook

🇨🇳中文介绍

Email IMAP Fetch

核心目标

工作流程

相关 Skills

运行时模型

输出契约

参数

错误处理

参考文档

资源文件

脚本

🇺🇸English

Email IMAP Fetch

Core Goal

Workflow

Runtime Model

Output Contract

Parameters

Error Handling

References

Assets

Scripts

最新 Skills