mails

面向 AI Agent 的邮件基础设施。通过编程方式收发邮件。

English | 日本語 | 中文

工作原理

                        发送                                        接收

  Agent                                               外部发件人
    |                                                   |
    |  mails send --to user@example.com                 |  发送邮件到 agent@mails.dev
    |                                                   |
    v                                                   v
+--------+                                    +-------------------+
|  CLI   |                                    | Cloudflare Email  |
|  /SDK  |                                    |     Routing       |
+--------+                                    +-------------------+
    |                                                   |
    |  /v1/send                                         |  email() handler
    |  /api/send                                        |
    v                                                   v
+-----------------------------------------------------------+
|                       Worker                              |
|                                                           |
|  provider 链：Cloudflare Email Service → Resend           |
|                                                           |
|  mails.dev（托管）            或      自己部署（自部署）     |
|  +-----------------------------------------+              |
|  |  +----------+    +----------------+     |  +---------+ |
|  |  |  db9.ai  |    |  fs9（文件）    |     |  |   D1    | |
|  |  | 全文搜索  |    | （附件存储）    |     |  | （存储） | |
|  |  | 高级查询  |    +----------------+     |  +---------+ |
|  |  +----------+                           |              |
|  +-----------------------------------------+              |
+-----------------------------------------------------------+
          |                           |
   通过 CLI/SDK 查询            mails sync
    （remote provider）       （拉取到本地）
          |                           |
          v                     +-----+------+
       Agent                    |            |
                          +---------+  +-----------+
                          | SQLite  |  |  db9.ai   |
                          | （本地） |  | （云端）   |
                          +---------+  +-----------+
                           离线查询     全文搜索
                           本地备份     高级过滤

特性

• 发送邮件 — 多 provider 链：Cloudflare Email Service（原生 env.EMAIL.send() binding，公开 beta）与 Resend 互为兜底，默认顺序 cloudflare,resend，通过 EMAIL_PROVIDERS 覆盖
• 接收邮件 — 通过 Cloudflare Email Routing Worker
• 搜索收件箱 — 按关键词搜索主题、正文、发件人、验证码
• 验证码自动提取 — 自动从邮件中提取验证码（支持中/英/日/韩）
• 附件 — CLI --attach 或 SDK 发送，Worker 自动解析 MIME 附件
• 存储 Provider — 本地 SQLite、db9.ai 云端 PostgreSQL、或远程 Worker API
• Provider 可见性 — /api/send 响应与 /api/inbox 的 outbound 行携带 provider 字段（cloudflare/resend），知道是谁真正投递的
• 零运行时依赖 — provider 全部走 Workers binding 或原生 fetch()，不引 SDK
• 托管服务 — 通过 mails claim 免费获取 @mails.dev 邮箱
• 自部署 — 部署自己的 Worker，并使用 mailbox 级 token 鉴权

安装

npm install -g mails
# 或
bun install -g mails
# 或直接使用
npx mails

CLI 最多每 24 小时检查一次 npm；发现新版本时，会在 stderr 打印升级提醒。可用 MAILS_NO_UPDATE_CHECK=1 关闭（设置 NO_UPDATE_NOTIFIER=1 或 CI=1 时也会跳过检查）。

快速开始

托管模式 (mails.dev)

mails claim myagent                  # 免费认领 myagent@mails.dev
mails send --to user@example.com --subject "Hello" --body "World"  # 每月 100 封免费
mails inbox                          # 查看收件箱
mails inbox --query "密码"            # 搜索邮件
mails code --to myagent@mails.dev    # 等待验证码

无需 Resend key — 托管用户每月 100 封免费发件。无限发送请配置自己的 key：mails config set resend_api_key re_YOUR_KEY

自部署模式