内容
# smails
[](https://www.npmjs.com/package/@smails/cli)
[](https://smails.dev)
[](./LICENSE)
**为人类和AI代理提供的临时邮箱。** 一个即时、匿名的临时邮箱，用于注册、一次性验证码和确认 — 配备REST API、命令行界面和 **MCP服务器**，让您的AI代理也能接收验证邮件。无需注册，无需密码。
→ **[smails.dev](https://smails.dev)** · `npx @smails/cli create`
> 为您的代理提供专属邮箱：将MCP服务器连接到Claude、Cursor或任何MCP客户端，它就可以自行创建邮箱和读取传入的邮件（验证码、神奇链接）。
## 功能特点
- **即时邮箱** — 打开网站即可获得地址，无需点击
- **实时** — 新邮件通过WebSocket实时推送，无需轮询
- **为代理设计** — REST API、命令行界面和MCP服务器共享同一邮箱
- **多域名** — 可从可配置的接收域名中选择
- **自动清理** — 邮箱在7天不活动后自动过期
- **无服务器** — Cloudflare Workers + Durable Objects（每个邮箱一个DO，SQLite存储）
## 快速开始
### 网页
访问 **[smails.dev](https://smails.dev)** — 首次加载时为您创建邮箱。
### 命令行界面
```bash
npx @smails/cli create # 创建邮箱（令牌保存到 ~/.smails）
npx @smails/cli inbox # 列出消息
npx @smails/cli read <id> # 读取消息（id前缀足够）
npx @smails/cli whoami # 显示当前地址
npx @smails/cli create --new # 替换为全新邮箱
```
### MCP（适用于AI代理）
将服务器添加到任何MCP客户端（例如Claude Desktop，`~/.claude/mcp.json`）：
```json
{
"mcpServers": {
"smails": { "command": "npx", "args": ["@smails/cli", "mcp"] }
}
}
```
工具：`create_mailbox`、`list_messages`、`read_message`、`delete_message`、`get_address`.
### REST API
```bash
# 创建邮箱
curl -X POST https://smails.dev/api/mailbox
# → { "address": "...", "token": "..." }
# 使用返回的令牌列出消息
curl https://smails.dev/api/mailbox/messages \
-H "Authorization: Bearer <token>"
```
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/api/mailbox` | 创建邮箱 → `{ address, token }` |
| `GET` | `/api/mailbox/messages` | 列出消息 |
| `GET` | `/api/mailbox/messages/:id` | 读取消息（完整解析正文） |
| `DELETE` | `/api/mailbox/messages/:id` | 删除消息 |
| `WS` | `/api/mailbox/connect?token=` | 流式推送新邮件通知 |
除创建外，每个请求都使用 `Authorization: Bearer <token>` 进行身份验证。
## 工作原理
```
传入邮件 ──▶ Cloudflare 邮件路由（通配符）
│
▼
Worker email() 处理程序 ──┐
▼
网页 / 命令行界面 / MCP ──REST + WS──▶ Durable Object （每个邮箱一个）
├─ SQLite（消息）
├─ 令牌身份验证
└─ 7天定时器 → 清理
```
- 每个邮箱都是一个单独的 **Durable Object**，由其名称寻址；消息存储在DO的SQLite中。
- 令牌是 `{address}.{secret}`；Worker按地址路由，DO验证完整令牌。
- 7天定时器会清除不活动的邮箱；任何活动都会刷新它。
## 项目结构
```
frontend/ React Router 单页应用（预渲染）— Tailwind v4 + shadcn
worker/ Cloudflare Worker + Durable Objects — Hono 路由，postal-mime 解析
cli/ npm 包 — 命令行界面 + MCP 服务器（@smails/cli）
```
## 开发
每个软件包都是独立的（pnpm）。请在每个软件包中安装。
```bash
# frontend
cd frontend && pnpm install && pnpm dev
# worker（API + Durable Objects）
cd worker && pnpm install && pnpm dev
# cli / mcp
cd cli && pnpm install && pnpm build
SMAILS_API_URL=http://localhost:8787 node dist/index.js create
```
## 部署
前端构建为静态资产，由Worker提供服务，因此只需一次部署：
```bash
cd frontend && pnpm build # → build/client
cd ../worker && pnpm run deploy # wrangler deploy — 提供资产 + API + DOs
```
接收邮件使用Cloudflare邮件路由（通配符 → Worker的 `email` 处理程序）。通过 `DOMAINS` 变量和 `worker/wrangler.jsonc` 中的路由配置接收域名。
## 许可证
MIT
