ClawHub

mail-imap-sync

Other

高性能IMAP邮件同步工具，支持多账号增量同步，按时间结构本地存储Markdown邮件，适合AI分析和邮件知识库构建。

Install

openclaw skills install mail-imap-sync

📬 Mail IMAP Sync Skill

🧠 功能概述

本技能用于：

  • 📥 从 IMAP 邮箱同步邮件（支持 Gmail / 企业邮箱）
  • ⚡ 高性能拉取（服务器端过滤，不扫全量）
  • 🔁 自动增量（基于 UID）
  • 🧱 本地结构化存储（Markdown + 时间分层）
  • 🧠 为 AI 提供可读邮件数据源

🚀 支持的同步模式

🥇 1. init（纯增量模式）

"mode": "init"
  • 第一次运行：不拉历史邮件
  • 后续：只同步新邮件

👉 适合长期运行系统

🥈 2. recent（推荐）

"mode": "recent",
"recent_days": 7
  • 第一次：拉取最近 N 天邮件
  • 后续：自动增量

👉 推荐用于 AI 分析 / 日报

🥉 3. since（指定日期）

"mode": "since",
"since": "2026-01-01"
  • 第一次：拉取指定日期之后邮件
  • 后续：增量同步

👉 用于历史导入

📁 存储结构

邮件以 Markdown 格式存储：

emails/
  {account}/
    YYYY/
      MM/
        DD/
          UID_MessageID_标题.md

🧾 邮件结构（标准化）

每封邮件包含：

# Subject

From: xxx
Date(raw): 原始时间
Date(local): 本地时间（Asia/ShangHai）
Date(ISO): ISO标准格式
Timestamp: Unix时间戳

UID: xxx
Message-ID: xxx
Account: xxx

---

正文内容

⏱ 时间处理（核心特性）

  • 自动解析各种邮件时间格式

  • 统一转换为：

    • Asia/ShangHai 时区
    • ISO标准格式
    • 时间戳（用于排序/分析）

👉 保证 AI 可稳定理解时间

⚡ 性能优化

本技能使用：

  • IMAP SEARCH SINCE（服务器过滤）
  • UID 增量同步
  • 避免扫描整个邮箱

👉 支持万级邮件秒级同步

🔁 去重机制

  • UID 去重
  • Message-ID 去重
  • 文件存在即跳过

🧱 稳定性保障

  • state.json 原子写入（防损坏）
  • Ctrl+C 不会丢状态
  • 自动检测异常状态并修复
  • 支持断点恢复

⚙️ 配置方式（config.json）

{
  "accounts": [
    {
      "name": "bettermsao",
      "imap_host": "imap.gmail.com",
      "user": "xxx@gmail.com",
      "pass": "应用专用密码",
      "mode": "recent",
      "recent_days": 7
    }
  ]
}

▶️ 运行方式

./run.sh

📤 输出说明

返回：

{
  "synced_emails": [
    "emails/.../xxx.md"
  ]
}

🧩 适用场景

  • 📊 邮件数据分析
  • 🤖 AI 邮件总结（日报 / 周报）
  • 🚨 重要邮件监控
  • 🧠 本地 LLM 数据输入

🔮 可扩展方向

  • 邮件自动总结（LLM）
  • 分类（订单 / 客户 / 系统）
  • 向量化（语义搜索）
  • 通知推送（微信 / Telegram）
  • 多邮箱聚合分析

⚠️ 注意事项

  • Gmail 需开启 IMAP 并使用应用专用密码
  • 企业邮箱可能限制 IMAP 频率
  • 初次运行建议使用 recent 模式

🏁 总结

本技能将邮件系统转化为：

👉 可结构化存储 👉 可被 AI 理解 👉 可持续增量更新