Webhook 是临时邮箱 API 的进阶玩法——邮件到达时服务器主动通知你，不用轮询。本文教你配置 YYDS Mail Webhook，实现验证码自动提取、工作流触发等自动化场景。
Webhook 是什么
Webhook 是一种"反向 API"：传统 API 是你主动去查（轮询），Webhook 是事件发生时服务方主动 POST 到你的 URL。
临时邮箱场景下，Webhook 的价值是：邮件到达时自动通知你的服务器，不需要你反复调用 API 检查收件箱。
Webhook vs 轮询
| 方式 | 原理 | 优点 | 缺点 | |------|------|------|------| | 轮询 | 每隔 N 秒调 API 查收件箱 | 实现简单 | 浪费 API 配额、延迟高 | | Webhook | 邮件到达时服务方主动 POST | 实时、省配额 | 需要公网接收端点 |
对于实时性要求高的场景（如验证码自动提取），Webhook 是更好的选择。
配置 Webhook
第一步：准备接收端点
你的服务器需要一个公网可访问的 URL 来接收 Webhook POST 请求：
const express = require("express");
const app = express();
app.use(express.json());
app.post("/webhooks/mail", (req, res) => {
const event = req.body;
if (event.type === "message.received") {
const message = event.data;
console.log("收到邮件:", message.subject);
console.log("发件人:", message.from);
console.log("正文:", message.text);
// 在这里处理邮件...
}
res.json({ ok: true });
});
app.listen(3000);
第二步：注册 Webhook
调用 API 注册你的 Webhook URL：
curl https://maliapi.215.im/v1/webhooks \
-X POST \
-H "X-API-Key: AC-your-key-here" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/webhooks/mail",
"events": ["message.received"]
}'
第三步：验证和测试
注册后，YYDS Mail 会发送一个验证请求到你的 URL。确认你的服务器正确响应后，Webhook 激活。之后每当邮箱收到新邮件，你的服务器就会收到通知。
Webhook 消息格式
收到的 POST 请求 body 结构：
{
"type": "message.received",
"data": {
"id": "msg_xxx",
"accountId": "acc_xxx",
"from": "noreply@example.com",
"to": "random@215.im",
"subject": "你的验证码",
"text": "验证码是 123456",
"html": "<p>验证码是 123456</p>",
"receivedAt": "2026-07-15T10:00:00Z"
}
}
实用场景
场景一：自动提取验证码
收到邮件后用正则提取验证码，自动填回注册流程：
app.post("/webhooks/mail", (req, res) => {
const { text } = req.body.data;
const codeMatch = text.match(/验证码[：:]\s*(\d{4,6})/);
if (codeMatch) {
const code = codeMatch[1];
// 自动填入注册表单或存入数据库
saveVerificationCode(req.body.data.accountId, code);
}
res.json({ ok: true });
});
场景二：邮件触发自动化
收到特定发件人的邮件时触发工作流（如发 Slack 通知、更新数据库）。
场景三：监控告警
监控特定关键词的邮件，到达时发送告警。
安全建议
- 验证签名：YYDS Mail 会在请求头带签名，验证签名确保请求来自官方
- HTTPS 必须：Webhook URL 必须是 HTTPS
- 超时响应：收到请求后尽快返回 200，耗时处理放到后台
- 重试机制：如果你的服务器返回非 200，YYDS Mail 会自动重试
常见问题
Webhook 免费吗？ Webhook 功能包含在 API 调用配额内，不额外收费。详见定价页。
Webhook 会丢消息吗？ 如果你的服务器不可用，YYDS Mail 会重试。但建议同时实现轮询作为兜底。
可以配置多个 Webhook URL 吗？ 可以。为不同事件配置不同的 URL。
想配置 Webhook 自动化？查看完整 API 文档，或阅读临时邮箱 API 入门了解基础。