mails

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

工作原理

 发送 接收
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

自部署模式

cd worker && wrangler deploy # 部署你自己的 Worker# 至少配置一个发送 provider：
wrangler secret put RESEND_API_KEY # 选项 A：Resend# 选项 B：Cloudflare Email Service（公开 beta）— 在 wrangler.toml 中添加：# [[send_email]]# name = "EMAIL"# 同时配置时，默认链顺序 cloudflare → resend。# 强制指定顺序 / 禁用某个：# wrangler secret put EMAIL_PROVIDERS # 例如 "resend" 或 "cloudflare,resend"## 单邮箱：# MAILBOX=agent@yourdomain.com# AUTH_TOKEN=YOUR_MAILBOX_TOKEN# 多邮箱：# AUTH_TOKENS_JSON={"agent@yourdomain.com":"token1","other@yourdomain.com":"token2"}
mails config set worker_url https://your-worker.example.com
mails config set worker_token YOUR_MAILBOX_TOKEN
mails config set mailbox agent@yourdomain.com
mails send --to user@example.com --subject "Hello" --body "Hi"# 通过 Worker 发送
mails inbox # 查询 Worker API
mails sync # 下载邮件到本地 SQLite

CLI 参考

claim

mails claim <name># 认领 name@mails.dev（每人最多 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 <subject> --body <text> --reply-to <email>
mails send --to <email> --subject "Report" --body "See attached" --attach report.pdf

inbox

mails inbox # 最近邮件列表
mails inbox --full-id # 列表显示完整邮件 ID（默认只显示前 8 位）
mails inbox --mailbox agent@test.com # 指定邮箱
mails inbox --query "password reset"# 全文搜索（按相关性排序）
mails inbox --query "invoice" --direction inbound --limit 10
mails inbox <id># 查看邮件详情 + 附件
mails inbox <id> --save # 下载附件到当前目录
mails inbox <id> --save ./downloads # 下载附件到指定目录

高级查询能力（附件 / 发件人 / 时间 / 邮件头过滤，以及发件人统计）目前仅通过 mails.dev 托管 HTTP API 提供，尚未接入 mails CLI 或 SDK。详见 docs/advanced-query-api.md。

code

mails code --to agent@test.com # 等待验证码（默认 30 秒）
mails code --to agent@test.com --timeout 60 # 自定义超时

验证码输出到 stdout，方便管道使用：CODE=$(mails code --to agent@test.com)

config

mails config # 查看所有配置
mails config set<key><value># 设置配置项
mails config get <key># 获取配置项
mails config path # 显示配置文件路径

sync

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

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

SDK 用法

import{send,getInbox,searchInbox,waitForCode}from'mails'// 发送constresult=awaitsend({to: 'user@example.com',subject: 'Hello',text: 'World',})// 发送附件awaitsend({to: 'user@example.com',subject: 'Report',text: 'See attached',attachments: [{path: './report.pdf'}],})// 收件箱列表constemails=awaitgetInbox('agent@mails.dev',{limit: 10})// 搜索收件箱（全文搜索，按相关性排序）constresults=awaitsearchInbox('agent@mails.dev',{query: 'password reset',direction: 'inbound',})// 等待验证码constcode=awaitwaitForCode('agent@mails.dev',{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。

安全配置

# 单邮箱：# MAILBOX=agent@yourdomain.com# AUTH_TOKEN=YOUR_MAILBOX_TOKEN# 多邮箱：# AUTH_TOKENS_JSON={"agent@yourdomain.com":"token1","other@yourdomain.com":"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`	通过 provider 链发送邮件（Cloudflare Email Service、Resend）
`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 后可获得：

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

以上高级能力通过 mails.dev 托管 HTTP API 暴露（见 docs/advanced-query-api.md）；mails CLI/SDK 目前只透传 query、direction 和 limit。

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`
`db9_token`		db9.ai 云存储 token
`db9_database_id`		db9.ai 数据库 ID
`last_sync`		上次 `mails sync` 运行的时间戳（自动管理）

测试

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

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
src		src
test		test
worker		worker
.env.example		.env.example
.gitignore		.gitignore
README.en.md		README.en.md
README.ja.md		README.ja.md
README.md		README.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
package.json		package.json
plan.md		plan.md
skill.md		skill.md
tsconfig.json		tsconfig.json

Navigation Menu

Uh oh!

Repository files navigation

mails

工作原理

特性

安装

快速开始

托管模式 (mails.dev)

自部署模式

CLI 参考

claim

send

inbox

code

config

sync

SDK 用法

Email Worker

部署

安全配置

Worker API

存储 Provider

SQLite（默认）

db9.ai

Remote（Worker API）

配置项

测试

各 Provider E2E 覆盖情况

许可证

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

mails

工作原理

特性

安装

快速开始

托管模式 (mails.dev)

自部署模式

CLI 参考

claim

send

inbox

code

config

sync

SDK 用法

Email Worker

部署

安全配置

Worker API

存储 Provider

SQLite（默认）

db9.ai

Remote（Worker API）

配置项

测试

各 Provider E2E 覆盖情况

许可证

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages