Skip to content

README.zh.md

Latest commit

 

History

History
341 lines (269 loc) · 12.6 KB

README.zh.md

File metadata and controls

341 lines (269 loc) · 12.6 KB

mails

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

npm license

English | 日本語

工作原理

                        发送                                        接收

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

特性

  • 发送邮件 — 通过 Resend，支持附件
  • 接收邮件 — 通过 Cloudflare Email Routing Worker
  • 搜索收件箱 — 按关键词搜索主题、正文、发件人、验证码
  • 验证码自动提取 — 自动从邮件中提取验证码（支持中/英/日/韩）
  • 附件 — CLI --attach 或 SDK 发送，Worker 自动解析 MIME 附件
  • 存储 Provider — 本地 SQLite、db9.ai 云端 PostgreSQL、或远程 Worker API
  • 零运行时依赖 — Resend provider 仅使用原生 fetch()
  • 托管服务 — 通过 mails claim 免费获取 @mails.dev 邮箱
  • 自部署 — 部署自己的 Worker，并使用 mailbox 级 token 鉴权

安装

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

快速开始

托管模式 (mails.dev)

mails claim myagent                  # 免费认领 [email protected]
mails send --to [email protected] --subject "Hello" --body "World"  # 每月 100 封免费
mails inbox                          # 查看收件箱
mails inbox --query "密码"            # 搜索邮件
mails code --to [email protected]    # 等待验证码

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

自部署模式

cd worker && wrangler deploy             # 部署你自己的 Worker
wrangler secret put RESEND_API_KEY       # 在 Worker 上设置 Resend 密钥（用于发送）
# 单邮箱：
#   [email protected]
#   AUTH_TOKEN=YOUR_MAILBOX_TOKEN
# 多邮箱：
#   AUTH_TOKENS_JSON={"[email protected]":"token1","[email protected]":"token2"}
mails config set worker_url https://your-worker.example.com
mails config set worker_token YOUR_MAILBOX_TOKEN
mails config set mailbox [email protected]
mails send --to [email protected] --subject "Hello" --body "Hi"  # 通过 Worker 发送
mails inbox                              # 查询 Worker API
mails sync                               # 下载邮件到本地 SQLite

CLI 参考

claim

mails claim <name>                   # 认领 [email protected]（每人最多 10 个）

send

mails send --to <email> --subject <subject> --body <text>
mails send --to <email> --subject <subject> --html "<h1>Hello</h1>"
mails send --from "Name <email>" --to <email> --subject <subject> --body <text>
mails send --to <email> --subject "Report" --body "See attached" --attach report.pdf

inbox

mails inbox                                  # 最近邮件列表
mails inbox --mailbox [email protected]         # 指定邮箱
mails inbox --query "password reset"         # 全文搜索（按相关性排序）
mails inbox --query "invoice" --direction inbound --limit 10
mails inbox <id>                             # 查看邮件详情 + 附件

# 高级过滤（mails.dev 托管 / db9）
mails inbox --has-attachments                # 只看带附件的邮件
mails inbox --attachment-type pdf            # 按附件类型过滤
mails inbox --from github.com               # 按发件人过滤
mails inbox --since 2026-03-01 --until 2026-03-20  # 时间范围
mails inbox --header "X-Mailer:sendgrid"    # 按邮件头过滤

# 任意组合
mails inbox --from github.com --has-attachments --since 2026-03-13
mails inbox --query "deploy" --attachment-type log --direction inbound

stats

mails stats senders                          # 按发件人频率排行

code

mails code --to [email protected]              # 等待验证码（默认 30 秒）
mails code --to [email protected] --timeout 60 # 自定义超时

验证码输出到 stdout，方便管道使用：CODE=$(mails code --to [email protected])

config

mails config                    # 查看所有配置
mails config set <key> <value>  # 设置配置项
mails config get <key>          # 获取配置项

sync

mails sync                              # 从 Worker 同步邮件到本地存储
mails sync --since 2026-03-01           # 从指定日期同步
mails sync --from-scratch               # 全量重新同步

从 Worker（托管或自部署）拉取邮件到本地 SQLite。适用于离线访问或本地备份。

SDK 用法

import { send, getInbox, searchInbox, waitForCode } from 'mails'

// 发送
const result = await send({
  to: '[email protected]',
  subject: 'Hello',
  text: 'World',
})

// 发送附件
await send({
  to: '[email protected]',
  subject: 'Report',
  text: 'See attached',
  attachments: [{ path: './report.pdf' }],
})

// 收件箱列表
const emails = await getInbox('[email protected]', { limit: 10 })

// 搜索收件箱（全文搜索，按相关性排序）
const results = await searchInbox('[email protected]', {
  query: 'password reset',
  direction: 'inbound',
})

// 高级过滤（mails.dev 托管 / db9）
const pdfs = await getInbox('[email protected]', {
  has_attachments: true,
  attachment_type: 'pdf',
  since: '2026-03-01',
})

// 等待验证码
const code = await waitForCode('[email protected]', { timeout: 30 })
if (code) console.log(code.code) // "123456"

Email Worker

worker/ 目录包含用于接收邮件的 Cloudflare Email Routing Worker。

部署

cd worker
bun install
wrangler d1 create mails
# 编辑 wrangler.toml — 设置你的 D1 数据库 ID
wrangler d1 execute mails --file=schema.sql
wrangler deploy

然后在 Cloudflare Email Routing 中配置转发到该 Worker。

安全配置

# 单邮箱：
#   [email protected]
#   AUTH_TOKEN=YOUR_MAILBOX_TOKEN
# 多邮箱：
#   AUTH_TOKENS_JSON={"[email protected]":"token1","[email protected]":"token2"}

所有 /api/* 端点都需要 Authorization: Bearer <mailbox-token>。这个 token 必须和 ?to=、被读取的邮件、或发送时的 from 邮箱一致。/health 始终公开。若未配置 mailbox token，访问 /api/* 会返回 503。

Worker API

端点 说明
GET /api/inbox?to=<addr>&limit=20 邮件列表
GET /api/inbox?to=<addr>&query=<text> 搜索邮件
GET /api/code?to=<addr>&timeout=30 长轮询等待验证码
GET /api/email?id=<id> 邮件详情（含附件）
POST /api/send 通过 Resend 发送邮件（需要 RESEND_API_KEY）
GET /api/sync?to=<addr>&since=<iso> 增量邮件同步（含附件）
GET /health 健康检查（始终公开）

存储 Provider

CLI 自动检测存储 Provider：

  • 配置了 api_key → 远程（mails.dev 托管）
  • 配置了 worker_url → 远程（自部署 Worker）
  • 否则 → 本地 SQLite

SQLite（默认）

本地数据库，路径 ~/.mails/mails.db。零配置。

db9.ai

面向 AI Agent 的云端 PostgreSQL。支持全文搜索（按相关性排序）、附件内容搜索和高级过滤。

mails config set storage_provider db9
mails config set db9_token YOUR_TOKEN
mails config set db9_database_id YOUR_DB_ID

使用 db9 后可获得：

  • 加权全文搜索 — 主题（最高权重）> 发件人 > 正文 > 附件文本
  • 附件过滤 — 按类型、按名称、有/无附件
  • 发件人 & 时间过滤 — --from、--since、--until
  • 邮件头查询 — 搜索 JSONB 邮件头
  • 发件人统计 — 所有发件人的频率排行

Remote（Worker API）

直接查询 Worker HTTP API。配置了 api_key 或 worker_url 时自动启用。

配置项

键 默认值 说明
mailbox 接收邮箱地址
api_key mails.dev 托管服务 API key
worker_url 自部署 Worker URL
worker_token 自部署 Worker 的 mailbox token
resend_api_key Resend API 密钥
default_from 默认发件人地址
storage_provider auto sqlite、db9 或 remote

测试

bun test              # 单元 + E2E 测试（无需外部依赖）
bun test:coverage     # 附带覆盖率报告
bun test:live         # 实时 E2E 测试（需要 .env 配置）
bun test:all          # 全部测试（包括实时 E2E）

198 个单元测试 + 27 个 E2E 测试 = 225 个测试，覆盖全部 Provider。

各 Provider E2E 覆盖情况

SQLite db9 Remote (OSS) Remote (托管)
存储 inbound 邮件 ✅ ✅ N/A N/A
存储邮件 + 附件 ✅ ✅ N/A N/A
发送 → 接收（真实链路） ✅ — ✅ ✅
收件箱列表 ✅ ✅ ✅ ✅
has_attachments 标记 ✅ ✅ ✅ ✅
方向过滤 ✅ ✅ ✅ ✅
分页 ✅ ✅ ✅ ✅
邮件详情 ✅ ✅ ✅ ✅
附件元数据 ✅ ✅ ✅ ✅
搜索 ✅ ✅ ✅ ✅
附件内容搜索 ✅ ✅ — —
验证码 ✅ ✅ ✅ ✅
附件下载 ✅ ✅ — ✅
保存到磁盘 (--save) ✅ — — ✅
邮箱隔离 ✅ ✅ — —
Outbound 记录 ✅ — ✅ N/A
通过 Worker 发送 (/api/send) — — ✅ —
同步到本地 — — ✅ —

许可证

MIT