Agent 邮箱配置

为 Agent 分配独立邮箱地址，用于收发邮件——包括验证码、通知、账号注册以及自主邮箱收件箱监控。

前置条件

• 已在 Resend 上完成域名验证（或具备验证能力）
• 已运行 Express/Node.js 后端服务（用于接收 Webhook）
• 拥有具备完整权限的 Resend API Key（非仅限发送权限）
• 服务器上已安装 curl、jq 和 node

架构设计

外部发件人
      ↓
[Resend 入站邮件]
      ↓ （Webhook 事件：email.received）
[Express /api/inbound-email]
      ↓ （以 JSON 格式保存）
[mail/inbox/]
      ↓ （定时任务：每 5 分钟执行一次）
[Agent 读取并处理]
      ↓
[Agent 响应或执行动作]

步骤 1：在 Resend 上验证域名

若该域名尚未验证，请执行以下操作：

RESEND_KEY="re_xxxxx"

# 添加域名
curl -s -X POST -H "Authorization: Bearer $RESEND_KEY" 
  -H "Content-Type: application/json" 
  https://api.resend.com/domains 
  -d '{"name": "yourdomain.com", "region": "us-east-1"}'

# 获取需配置的 DNS 记录
curl -s -H "Authorization: Bearer $RESEND_KEY" 
  https://api.resend.com/domains/yourdomain.com | jq '.records'

将返回的 DNS 记录（TXT、MX、CNAME）添加至您的 DNS 提供商控制台。等待验证完成（通常需数分钟）。

验证状态：

curl -s -H "Authorization: Bearer $RESEND_KEY" 
  https://api.resend.com/domains/yourdomain.com | jq '{status, capabilities}'

sending 与 receiving 两项能力均须显示为 "enabled"。

步骤 2：创建 Webhook 接收端点

在 Express 后端中创建 routes/inboundEmail.js（完整实现参考 references/inboundEmail.js）。关键要求如下：

• 支持对 /api/inbound-email 的 POST 请求
• 使用 RESEND_WEBHOOK_SECRET 验证 Resend Webhook 签名
• 将接收到的邮件以 JSON 格式保存至 mail/inbox/
• 提供 GET 接口用于列出或读取邮件
• 提供 ACK 接口用于标记邮件为已处理

在服务端挂载该路由：

const inboundEmailRoutes = require('./routes/inboundEmail');
app.use('/api/inbound-email', inboundEmailRoutes);

步骤 3：在 Resend 上注册 Webhook

curl -s -X POST -H "Authorization: Bearer $RESEND_KEY" 
  -H "Content-Type: application/json" 
  https://api.resend.com/webhooks 
  -d '{
    "endpoint": "https://yourdomain.com/api/inbound-email",
    "events": ["email.received"],
    "enabled": true
  }' | jq '{id, signing_secret}'

请妥善保存返回的 signing_secret —— 后续 Webhook 签名验证将用到它。

步骤 4：存储密钥信息

将以下配置项加入您的密钥管理系统：

{
  "RESEND_API_KEY": "re_xxxxx",
  "RESEND_WEBHOOK_SECRET": "whsec_xxxxx",
  "AGENT_EMAIL": "agent@yourdomain.com"
}

步骤 5：创建收件箱目录

mkdir -p mail/inbox
touch mail/inbox/.lastcheck

步骤 6：配置收件箱监控定时任务

设置一个每 5 分钟运行一次的 cron 任务，用于检查新邮件并通知 Agent：

每 5 分钟 → 检查 mail/inbox/ 下是否存在新的 .json 文件  
→ 若发现新邮件：读取、摘要，并向所有者报告  
→ 将已处理邮件重命名为带 .processed 后缀的文件

步骤 7：端到端测试

发送测试邮件：

curl -s -X POST -H "Authorization: Bearer $RESEND_KEY" 
  -H "Content-Type: application/json" 
  https://api.resend.com/emails 
  -d '{
    "from": "Agent ",
    "to": ["owner@theirdomain.com"],
    "subject": "Email system test",
    "text": "This is a test from my new email address."
  }'

验证接收功能：

curl -s https://yourdomain.com/api/inbound-email | jq .

验证收件箱目录：

ls -la mail/inbox/

从 Agent 代码中发送邮件

async function sendEmail(to, subject, text, html) {
  const res = await fetch('https://api.resend.com/emails', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${RESEND_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from: 'Agent ',
      to: [to],
      subject,
      text,
      ...(html && { html }),
    }),
  });
  return res.json();
}

从 Agent 代码中读取收件箱

async function getInbox() {
  const res = await fetch('http://localhost:PORT/api/inbound-email');
  const data = await res.json();
  return data.emails;
}

async function getEmail(id) {
  const res = await fetch(`http://localhost:PORT/api/inbound-email/${id}`);
  return res.json();
}

async function ackEmail(id) {
  await fetch(`http://localhost:PORT/api/inbound-email/${id}/ack`, { method: 'POST' });
}

Webhook 签名验证

Resend 使用 HMAC-SHA256 对 Webhook 进行签名。务必验证签名以防止伪造请求：

const crypto = require('crypto');

function verifySignature(rawBody, signature, secret) {
  try {
    const [timestamp, hash] = signature.split(',').map(s => s.trim());
    if (!timestamp || !hash) return false;
    const signedPayload = `${timestamp}.${rawBody}`;
    const expected = crypto.createHmac('sha256', secret)
      .update(signedPayload).digest('hex');
    return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected));
  } catch {
    return false;
  }
}

安全注意事项

• 切勿在聊天记录或日志中暴露 RESEND_API_KEY 或 RESEND_WEBHOOK_SECRET
• 生产环境中必须始终验证 Webhook 签名
• Webhook 端点必须使用 HTTPS（Resend 强制要求）
• Webhook 密钥应通过密钥管理系统管理，禁止硬编码
• 收件箱文件应存放于服务器文件系统内，不可对外公开访问

故障排查