xmails-cli - Email for AI Agents

面向 AI Agent 的邮件托管服务，部署在 xmail.mkdiff.com。

项目结构

xmails-cli/         # CLI 工具 (bun)
xmails-server/    # 后端 API (Koa + SQLite)

快速开始

1. 部署后端服务

cd xmails-server
npm install
npm start

服务将在 http://localhost:3000 启动。

2. 安装 CLI

cd xmails-cli
bun install
bun run build
npm link  # 全局安装 xmails-cli 命令

3. 认领邮箱

xmails-cli claim myagent

浏览器会打开确认页面，确认后获得 [email protected] 邮箱。

CLI 命令

xmails-cli claim <name>           # 认领邮箱
xmails-cli send --to <email> --subject <subject> --body <text>  # 发送邮件
xmails-cli inbox                  # 查看收件箱
xmails-cli inbox --query <text>   # 搜索邮件
xmails-cli code --to <email>      # 等待验证码
xmails-cli sync                   # 同步到本地 SQLite
xmails-cli config                 # 查看配置

第三方服务配置

Resend API (发送邮件)

必需 - 用于发送邮件。

1. 访问 https://resend.com 注册账号
2. 在 Dashboard 获取 API Key
3. 配置环境变量：

# 在 xmails-server 目录创建 .env 文件
RESEND_API_KEY=re_xxxxxxxxxx

或者启动时设置：

RESEND_API_KEY=re_xxxxxxxxxx npm start

Resend 免费额度：

• 每月 3,000 封邮件
• 每天 100 封邮件
• 需要验证域名才能发送到真实邮箱

域名 DNS 配置

要在 xmail.mkdiff.com 接收邮件，需要配置 DNS：

方案 A：Cloudflare Email Routing (推荐)

步骤 1：配置 DNS

在 Cloudflare DNS 设置中添加：

# MX 记录 (如果使用 Cloudflare Email Routing)
xmail.mkdiff.com  MX  10  route1.mx.cloudflare.net
xmail.mkdiff.com  MX  20  route2.mx.cloudflare.net

# SPF 记录 (可选，提高送达率)
xmail.mkdiff.com  TXT  "v=spf1 include:_spf.mx.cloudflare.net ~all"

步骤 2：启用 Email Routing

1. 登录 Cloudflare Dashboard
2. 选择你的域名 → Email → Email Routing
3. 点击 "Enable Email Routing"
4. 添加 catch-all 路由或指定地址

步骤 3：配置 Webhook

Cloudflare Email Routing 支持 webhook，将邮件转发到你的服务器：

{
  "destination": "https://xmail.mkdiff.com/inbound",
  "actions": [
    { "type": "forward", "value": ["https://xmail.mkdiff.com/inbound"] }
  ]
}

或者在 Cloudflare Workers 中处理：

// Cloudflare Worker (绑定到 Email Routing)
export default {
  async email(message, env, ctx) {
    // 转发到你的服务器
    const response = await fetch('https://xmail.mkdiff.com/inbound', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        from: message.from,
        to: message.to,
        subject: message.headers.get('subject'),
        text: await message.text(),
        raw: await message.raw.toArrayBuffer().then(b => Buffer.from(b).toString('base64'))
      })
    })
  }
}

Webhook 端点说明：

| 端点 | 说明 | |------|------| | POST /inbound | 接收 Cloudflare 格式的 JSON 邮件 | | POST /inbound/raw | 接收原始 MIME 邮件 |

接收的数据格式：

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Your verification code",
  "text": "Your code is 123456",
  "html": "<p>Your code is <b>123456</b></p>",
  "headers": { "message-id": "...", "date": "..." },
  "attachments": [],
  "raw": "base64 encoded MIME"
}

方案 B：自建邮件服务器

需要配置完整的邮件服务器：

• MX 记录
• SPF 记录 (v=spf1 ip4:YOUR_IP ~all)
• DKIM 签名
• DMARC 策略

复杂度较高，不推荐。

方案 C：第三方服务

• Mailgun - 提供 inbound 解析，转发到 webhook
• SendGrid - Inbound Parse API
• Postmark - Inbound webhook

API 端点

| 端点 | 说明 | |------|------| | POST /v1/claim/start | 开始认领 | | GET /v1/claim/poll | 轮询状态 | | POST /demo/claim | 确认认领 (demo 模式) | | POST /v1/send | 发送邮件 | | GET /v1/inbox | 收件箱列表 | | GET /v1/email?id= | 邮件详情 | | GET /v1/code | 获取验证码 | | GET /v1/sync | 同步邮件 | | POST /inbound | 接收邮件 webhook (Cloudflare) | | POST /inbound/raw | 接收原始 MIME 邮件 |

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | PORT | 服务端口 | 3000 | | HOST | 监听地址 | 0.0.0.0 | | RESEND_API_KEY | Resend API 密钥 | - |

生产部署

使用 PM2

npm install -g pm2
pm2 start src/index.js --name xmails-api

使用 Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

docker build -t xmails-server .
docker run -p 3000:3000 -e RESEND_API_KEY=re_xxx xmails-server

Nginx 反向代理

server {
    listen 80;
    server_name xmail.mkdiff.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

安全建议

1. 添加用户认证 - 当前是 demo 模式，生产环境需要实现 GitHub OAuth 或其他认证
2. HTTPS - 使用 Let's Encrypt 配置 SSL
3. 速率限制 - 防止 API 滥用
4. 输入验证 - 已有基本验证，可加强

与原 mails 的区别

| 特性 | mails | xmails-cli | |------|-------|--------| | 托管域名 | mails.dev | xmail.mkdiff.com | | API 前缀 | /v1/* | /v1/* | | 配置目录 | ~/.mails | ~/.xmails | | API Key 前缀 | mk_ | xk_ | | 用户认证 | GitHub OAuth | Demo 模式 |

License

MIT