从 0 到 1：用 YYDS Mail API 搭建邮件通知系统

很多应用需要邮件通知功能——订单确认、告警通知、注册验证。本文教你用 YYDS Mail API 从零搭建一个完整的邮件接收通知系统。

系统架构

一个邮件通知系统的核心流程：

1. 系统生成专用邮箱地址
2. 外部服务发邮件到该地址
3. YYDS Mail 接收邮件
4. Webhook 通知你的服务器
5. 你的服务器处理邮件内容
6. 触发后续业务逻辑

第一步：创建专用邮箱

为你的通知系统创建一个固定邮箱：

const res = await fetch("https://maliapi.215.im/v1/accounts", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.YYDS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "notification-inbox",
  }),
});
const { data: account } = await res.json();
console.log("通知邮箱:", account.address);

用付费套餐保留这个邮箱地址长期可用。

第二步：配置 Webhook

设置 Webhook，邮件到达时通知你的服务器：

await fetch("https://maliapi.215.im/v1/webhooks", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.YYDS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-app.com/api/mail-webhook",
    events: ["message.received"],
  }),
});

第三步：接收和处理邮件

你的服务器接收 Webhook 并处理：

const express = require("express");
const app = express();
app.use(express.json());

app.post("/api/mail-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "message.received") {
    const { from, subject, text } = data;

    // 根据发件人路由处理
    if (from.includes("alert@monitoring.com")) {
      await handleAlert(subject, text);
    } else if (from.includes("orders@shop.com")) {
      await handleOrder(subject, text);
    } else {
      await handleGeneralMail(subject, text);
    }
  }

  res.json({ ok: true });
});

async function handleAlert(subject, text) {
  // 解析告警级别
  const severity = subject.includes("CRITICAL") ? "critical" : "warning";
  // 发送到 Slack
  await sendSlackNotification(`[${severity}] ${subject}`);
}

async function handleOrder(subject, text) {
  // 提取订单号
  const orderMatch = text.match(/订单号[：:]\s*(\w+)/);
  if (orderMatch) {
    const orderId = orderMatch[1];
    await updateOrderStatus(orderId, "confirmed");
  }
}

app.listen(3000);

第四步：添加持久化和重试

生产环境需要持久化和重试机制：

app.post("/api/mail-webhook", async (req, res) => {
  const { data } = req.body;

  // 1. 持久化到数据库
  await db.notifications.create({
    from: data.from,
    subject: data.subject,
    text: data.text,
    receivedAt: new Date(),
    processed: false,
  });

  // 2. 立即返回 200（避免 Webhook 超时）
  res.json({ ok: true });

  // 3. 后台异步处理
  processNotification(data).catch(console.error);
});

使用场景

场景一：监控告警

配置监控系统把告警邮件发到你的 YYDS Mail 邮箱，Webhook 接收后转发到 Slack/钉钉。

场景二：订单确认

电商系统把订单确认邮件发到通知邮箱，自动解析订单号并更新数据库。

场景三：注册验证

用户注册时，系统自动提取验证码完成验证流程。

场景四：邮件触发自动化

收到特定关键词的邮件时触发 IFTTT/Zapier 工作流。

最佳实践

• 邮箱专用：为每种通知类型创建独立邮箱，便于路由
• 异步处理：Webhook 接收后立即返回 200，耗时处理放后台
• 持久化：邮件内容存数据库，防止处理失败丢数据
• 重试机制：处理失败的任务加入重试队列
• 监控：监控 Webhook 接收率和处理成功率

常见问题

一个邮箱能接收多少邮件？ 取决于套餐配额。高频通知场景用高配额套餐。

Webhook 丢消息怎么办？ 实现轮询兜底：定期查收件箱，处理 Webhook 漏掉的消息。

能过滤发件人吗？ 在服务端代码里根据 from 字段过滤，只处理预期的发件人。

想搭建邮件通知系统？查看完整 API 文档，或阅读Webhook 配置指南。