email-imap-fetch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Email IMAP Fetch

邮件IMAP获取工具

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.

利用IMAP IDLE等待新邮件。
每次唤醒后获取未读消息。
支持通过环境变量配置多个邮箱账户。
通过环境变量模式（
```
idle
```
或
```
poll
```
）严格控制IDLE支持，无需运行时探测。
将每封获取到的邮件转发至OpenClaw webhooks。
输出机器可读的JSON行，供下游步骤使用。

Workflow

工作流程

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

bash

python3 scripts/imap_idle_fetch.py check-config

Run one IDLE cycle per account (smoke test):

bash

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

Run continuously (default resident mode):

bash

python3 scripts/imap_idle_fetch.py listen

配置账户环境变量和OpenClaw webhook环境变量（详见
```
references/env.md
```
和
```
assets/config.example.env
```
）。
验证配置：

bash

python3 scripts/imap_idle_fetch.py check-config

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

bash

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

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

bash

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).
For always-on behavior in production, manage the process with
```
systemd
```
,
```
launchd
```
,
```
supervisor
```
, or an equivalent daemon manager.

技能文件本地安装，但监听器不会自动启动。
在
```
idle
```
模式下，仅当监听器进程和IMAP连接保持活跃时，IMAP IDLE才能接收推送事件。
在
```
poll
```
模式下，监听器会在轮询间隔内休眠，之后获取未读消息。
若进程退出，推送事件会丢失；下次运行时仍可通过
```
UNSEEN
```
标记获取已存在的未读邮件。
默认运行模式为常驻模式（默认
```
IMAP_CYCLES=0
```
）。
默认IDLE模式为
```
poll
```
（对不支持IDLE的服务器更安全）。
若要在生产环境中实现始终在线的运行状态，可使用
```
systemd
```
、
```
launchd
```
、
```
supervisor
```
或类似的守护进程管理器来管理该进程。

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
```
```
snippet
```
(plain-text preview)

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

输出格式为JSONL（每行一个JSON对象）。
生命周期事件使用
```
type=status
```
标记。
获取到的邮件使用
```
type=message
```
标记，包含：
- ```
account
```
  ,
```
mailbox
```
  ,
```
seq
```
  ,
```
uid
```
- ```
subject
```
  ,
```
from
```
  ,
```
to
```
  ,
```
date
```
  ,
```
message_id
```
- ```
snippet
```
  （纯文本预览）
周期状态输出中的
```
wait_mode
```
为
```
idle
```
或
```
poll
```
。
```
wait_events
```
记录当前等待策略的详细信息。
OpenClaw webhook POST请求成功时，会输出
```
event=webhook_delivered
```
状态事件。
账户级失败使用
```
type=error
```
标记。
OpenClaw webhook POST请求失败时，会输出
```
event=webhook_failed
```
错误事件。

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.
```
--snippet-chars
```
: preview length limit.
```
--connect-timeout
```
: connection timeout seconds.
```
--retry-seconds
```
: retry delay after failure.

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
```
```
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
```

```
--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 webhooks转发相关变量：

```
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
```

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.

无效的环境变量配置会以退出码
```
2
```
终止程序。
在
```
idle
```
模式下，若服务器不支持IDLE，会返回明确错误并建议设置
```
IMAP_IDLE_MODE=poll
```
。
运行时失败会以
```
type=error
```
的形式输出。
当账户处理出现错误时，命令会以非零状态码退出。

References

参考文档

```
references/env.md
```

```
references/env.md
```

Assets

资源文件

```
assets/config.example.env
```

```
assets/config.example.env
```

Scripts

脚本文件

```
scripts/imap_idle_fetch.py
```

```
scripts/imap_idle_fetch.py
```