MoeMail Webhook 接入指南

Webhook 是 MoeMail 为高级用户提供的实时邮件通知能力。通过配置 Webhook，你可以在收到新邮件时自动触发自定义业务逻辑，例如发送消息提醒、同步到 CRM 或触发自动化流程。本文详细介绍 MoeMail Webhook 的使用方式、API 请求格式和最佳实践，帮助你快速完成集成并优化搜索引擎曝光。

功能概览

• 实时推送：新邮件到达后秒级推送，无需轮询。
• 标准 JSON 负载：携带发件人、主题、正文等关键信息，便于解析。
• 自定义回调地址：可指向自有服务或 SaaS 平台，灵活拓展业务场景。
• 可视化管理：在 MoeMail 个人中心启用、禁用和测试 Webhook 配置。

前置准备

在开始之前，请确保你已经：

1. 拥有 MoeMail 账号，并被授予 骑士 或 公爵 角色（皇帝可直接配置）。
2. 可以访问 MoeMail 的个人中心页面（登录后点击头像）。
3. 准备了一个可接收 POST 请求的回调地址，例如自建服务或第三方自动化平台。

配置步骤

1. 登录 MoeMail，点击右上角头像进入 个人中心。
2. 在“Webhook 通知”区域启用开关。
3. 输入目标回调地址（例如 https://example.com/webhook/moemail）。
4. 点击 测试 按钮，确认服务能够收到并正确处理示例请求。
5. 测试成功后保存配置，Webhook 即刻生效。

配置完成后，每当 MoeMail 收到新邮件，就会向你指定的 URL 发送一次 POST 请求。

请求示例

Webhook 使用 application/json 内容类型，并携带事件标识头部。

POST /webhook/moemail HTTP/1.1
Content-Type: application/json
X-Webhook-Event: new_message

请求体示例：

{
  "emailId": "email-uuid",
  "messageId": "message-uuid",
  "fromAddress": "sender@example.com",
  "subject": "邮件主题",
  "content": "邮件文本内容",
  "html": "邮件HTML内容",
  "receivedAt": "2024-01-01T12:00:00.000Z",
  "toAddress": "your-email@moemail.app"
}

字段说明：

• emailId: MoeMail 邮箱的唯一标识符。
• messageId: 邮件消息的唯一标识符。
• fromAddress: 发件人邮箱地址。
• subject: 邮件主题。
• content: 邮件纯文本正文。
• html: 邮件 HTML 内容（如存在）。
• receivedAt: 邮件接收时间（ISO8601 格式）。
• toAddress: 目标临时邮箱地址。

响应要求

• Webhook 端点应在 10 秒内返回 2xx 状态码。
• 推荐返回 200 OK 并附带业务处理结果，便于排查。

本地调试方案

MoeMail 提供简易的测试服务器帮助你在本地验证 Webhook：

pnpm webhook-test-server

• 服务默认监听 http://localhost:3001 并打印接收到的 payload。
• 结合 pnpx cloudflared tunnel --url http://localhost:3001 可临时暴露公网地址进行在线测试。

安全与稳定性建议

• 校验来源：如果业务需要，可在回调地址上增加 Token 验证或 IP 白名单。
• 幂等处理：根据 messageId 做幂等判断，避免重复执行逻辑。
• 错误监控：记录失败请求并告警，便于及时处理。
• 快速响应：把耗时逻辑放入消息队列或异步任务，确保 Webhook 快速完成。
• 控制通知长度：飞书、钉钉等 IM 机器人的消息正文存在长度限制（会导致推送失败），建议在推送前对邮件正文内容进行截断或摘要处理，并附上原文链接，避免发送失败。

常见问题（FAQ）

Q: 收不到 Webhook 请求怎么办？
A: 检查回调地址是否可公网访问，确认个人中心中 Webhook 已启用并重新测试。

Q: 能否同时推送多个地址？
A: 当前版本支持配置一个 URL。若需要 fan-out，可在回调服务中自行分发。

Q: 如何与其他系统联动？
A: 可以把 Webhook 连接到自动化平台（如 MoePush.app）或自建服务，实现短信提醒、钉钉/飞书机器人消息等。

相关链接

• API 文档：Webhook 集成
• 快速开始：部署与配置
• 权限系统说明

通过上述步骤，你已经完成 MoeMail Webhook 的接入和优化，快把临时邮箱与业务流程无缝串联起来吧！