email-imap-full-fetch

邮件 IMAP 完整抓取

核心目标

• 通过稳定的邮件引用从 IMAP 抓取一封目标邮件。
• 强制按以下顺序查找：先精确匹配 HEADER Message-Id，再回退到 uid。
• 通过 BODY.PEEK[] 下载完整原始 MIME。
• 解析并返回邮件头、完整纯文本正文、HTML 正文和附件元数据。
• 将 .eml 和附件文件保存到磁盘，并确保文件名安全且索引具备幂等性。

标准流程

1. 输入必须包含阶段 1 路由输出中的 message_id_norm（mail_ref.message_id_norm）。
2. 默认使用 fetch --message-id "<message_id_norm or raw Message-Id>"。
3. 仅当没有可用的 message-id 时，才使用 fetch --uid "<uid>"。
4. 邮箱选择应与阶段 1 保持一致（--mailbox 或 IMAP_MAILBOX）。
5. 读取 JSON 输出，并使用返回的 mail_ref 继续下游处理。

命令

按 Message-Id 抓取（首选）：

python3 scripts/imap_full_fetch.py fetch --message-id "<[email protected]>"

按 UID 抓取（仅用作回退）：

python3 scripts/imap_full_fetch.py fetch --uid "123456"

按需同时使用（先通过 message-id 查找，再回退到 uid）：

python3 scripts/imap_full_fetch.py fetch --message-id "<[email protected]>" --uid "123456"

输出约定

• 输出为单个 JSON 对象。
• 必需的顶层字段：
  • mail_ref
  • headers
  • text_plain
  • text_html
  • attachments
  • saved_eml_path
• mail_ref 包含：
  • account、mailbox、uid、message_id_raw、message_id_norm、date
• attachments[] 包含每个文件的元数据和持久化结果：
  • filename、content_type、bytes、disposition、saved_path、skipped_reason

存储与幂等性

• saved_eml_path 指向通过 BODY.PEEK[] 保存到本地的 .eml 文件。
• 保存附件时不会在 JSON 中返回附件二进制内容。
• 会清理文件名，移除路径分隔符和不安全字符。
• 重名附件会通过附加内容哈希后缀进行去重。
• 重复请求通过 message_id_norm 索引实现幂等，并直接返回已持久化的 JSON 记录。

参数

• --message-id：主要查找键。
• --uid：回退查找键。
• --mailbox：要查询的邮箱（默认使用 IMAP_MAILBOX 或 INBOX）。
• --save-eml-dir：.eml 文件的目标目录（环境变量 IMAP_FULL_SAVE_EML_DIR）。
• --index-dir：幂等性索引 JSON 文件的目标目录（环境变量 IMAP_FULL_INDEX_DIR，默认值为 <save-eml-dir>/.index）。
• --save-attachments-dir：附件的目标目录（环境变量 IMAP_FULL_SAVE_ATTACHMENTS_DIR）。
• --max-attachment-bytes：要保存的附件大小上限（环境变量 IMAP_FULL_MAX_ATTACHMENT_BYTES）。
• --allow-ext：允许的附件扩展名，以逗号分隔（环境变量 IMAP_FULL_ALLOW_EXT）。
• --connect-timeout：IMAP 连接超时秒数（默认值来自 IMAP_CONNECT_TIMEOUT）。

必需的环境变量

• IMAP_HOST
• IMAP_USERNAME
• IMAP_PASSWORD

可选的账户默认值：

• IMAP_NAME
• IMAP_PORT
• IMAP_SSL
• IMAP_MAILBOX

脚本

• scripts/imap_full_fetch.py