MoeMail Webhook 接入指南
Webhook 是 MoeMail 为高级用户提供的实时邮件通知能力。通过配置 Webhook，你可以在收到新邮件时自动触发自定义业务逻辑，例如发送消息提醒、同步到 CRM 或触发自动化流程。本文详细介绍 MoeMail Webhook 的使用方式、API 请求格式和最佳实践，帮助你快速完成集成并优化搜索引擎曝光。
功能概览
- 实时推送：新邮件到达后秒级推送，无需轮询。
- 标准 JSON 负载：携带发件人、主题、正文等关键信息，便于解析。
- 自定义回调地址：可指向自有服务或 SaaS 平台，灵活拓展业务场景。
- 可视化管理：在 MoeMail 个人中心启用、禁用和测试 Webhook 配置。
前置准备
在开始之前，请确保你已经：
- 拥有 MoeMail 账号，并被授予 骑士 或 公爵 角色（皇帝可直接配置）。
- 可以访问 MoeMail 的个人中心页面（登录后点击头像）。
- 准备了一个可接收 POST 请求的回调地址，例如自建服务或第三方自动化平台。
配置步骤
- 登录 MoeMail，点击右上角头像进入 个人中心。
- 在“Webhook 通知”区域启用开关。
- 输入目标回调地址（例如
https://example.com/webhook/moemail）。 - 点击 测试 按钮，确认服务能够收到并正确处理示例请求。
- 测试成功后保存配置，Webhook 即刻生效。
配置完成后，每当 MoeMail 收到新邮件，就会向你指定的 URL 发送一次 POST 请求。
请求示例
Webhook 使用 application/json 内容类型，并携带事件标识头部。
http
POST /webhook/moemail HTTP/1.1
Content-Type: application/json
X-Webhook-Event: new_message请求体示例：
json
{
"emailId": "email-uuid",
"messageId": "message-uuid",
"fromAddress": "[email protected]",
"subject": "邮件主题",
"content": "邮件文本内容",
"html": "邮件HTML内容",
"receivedAt": "2024-01-01T12:00:00.000Z",
"toAddress": "[email protected]"
}字段说明：
emailId: MoeMail 邮箱的唯一标识符。messageId: 邮件消息的唯一标识符。fromAddress: 发件人邮箱地址。subject: 邮件主题。content: 邮件纯文本正文。html: 邮件 HTML 内容（如存在）。receivedAt: 邮件接收时间（ISO8601 格式）。toAddress: 目标临时邮箱地址。
响应要求
- Webhook 端点应在 10 秒内返回 2xx 状态码。
- 推荐返回
200 OK并附带业务处理结果，便于排查。
本地调试方案
MoeMail 提供简易的测试服务器帮助你在本地验证 Webhook：
bash
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）或自建服务，实现短信提醒、钉钉/飞书机器人消息等。
相关链接
通过上述步骤，你已经完成 MoeMail Webhook 的接入和优化，快把临时邮箱与业务流程无缝串联起来吧！