临时邮箱 API 让你用代码自动创建一次性邮箱、接收邮件、配置 Webhook 通知。本文教你从零开始调用 YYDS Mail API，适合需要在应用里集成临时邮箱功能的开发者。
YYDS Mail API 概览
YYDS Mail 提供完整的 RESTful API，覆盖临时邮箱的全生命周期：
| 功能 | 端点 | 方法 | |------|------|------| | 创建临时邮箱 | /v1/accounts | POST | | 获取邮箱列表 | /v1/accounts | GET | | 获取收件箱邮件 | /v1/accounts/{id}/messages | GET | | 查看邮件详情 | /v1/messages/{id} | GET | | 配置 Webhook | /v1/webhooks | POST |
完整端点列表见 API 文档。所有响应均为 JSON 格式，遵循 { success, data, error } 统一结构。
认证：获取 API Key
调用 API 需要一个 API Key。获取方式：
- 注册并登录 YYDS Mail
- 进入控制台 → API Keys 页面
- 创建新 Key，设置权限（创建邮箱、读取邮件等）
- 复制 Key（格式为
AC-xxxxxxxxxxxx）
API Key 通过请求头 X-API-Key 传递：
curl https://maliapi.215.im/v1/accounts \
-H "X-API-Key: AC-your-key-here"
安全提示：API Key 等同于账户凭证，不要提交到 git 仓库或暴露在前端代码里。生产环境用环境变量管理。
创建临时邮箱
用 POST /v1/accounts 创建一个新的临时邮箱：
curl https://maliapi.215.im/v1/accounts \
-X POST \
-H "X-API-Key: AC-your-key-here" \
-H "Content-Type: application/json"
响应示例：
{
"success": true,
"data": {
"id": "acc_abc123",
"address": "random@215.im",
"createdAt": "2026-07-15T10:00:00Z"
}
}
JavaScript 示例：
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",
},
});
const { data } = await res.json();
console.log("临时邮箱地址:", data.address);
接收邮件
创建邮箱后，用 GET /v1/accounts/{id}/messages 查询收件箱：
curl https://maliapi.215.im/v1/accounts/acc_abc123/messages \
-H "X-API-Key: AC-your-key-here"
但对于实时场景，轮询效率低且浪费配额。推荐用 Webhook 替代。
Webhook 实时通知
配置 Webhook 后，每当临时邮箱收到新邮件，YYDS Mail 会主动向你指定的 URL 发送 POST 请求：
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-app.com/webhooks/mail",
"events": ["message.received"]
}'
你的服务端接收 Webhook：
app.post("/webhooks/mail", (req, res) => {
const { message } = req.body;
console.log("收到邮件:", message.subject);
console.log("发件人:", message.from);
// 提取验证码、触发业务逻辑...
res.json({ ok: true });
});
Webhook 适合这些场景：
- 自动提取验证码完成注册流程
- 监控特定发件人的邮件
- 邮件到达时触发自动化工作流
API 调用配额与速率限制
免费套餐每天有一定的 API 调用额度。超出后需要等待重置或升级套餐。具体限额见定价页或 API 文档。
建议的最佳实践：
- 用 Webhook 替代轮询，减少 API 消耗
- 缓存邮箱地址和邮件内容，避免重复请求
- 实现指数退避重试机制
常见问题
API Key 有调用次数限制吗？ 有。免费套餐有每日额度，付费套餐额度更高。详见定价页。
API 支持哪些编程语言？ 所有能发 HTTP 请求的语言都支持：Python、JavaScript、Go、PHP、Java、curl 等。文档示例用 curl 和 JS，完整文档有更多语言示例。
邮件能保留多久？ 取决于套餐。免费邮箱会在一段时间后清除，付费邮箱可长期保留。
可以用 API 发送邮件吗？ 不能。YYDS Mail 是 receive-only 平台，API 只支持接收和管理邮件，不支持发信。这是产品定位决定的安全策略。
想用代码集成临时邮箱？查看完整 API 文档，或注册获取 API Key开始使用。更多基础概念见什么是临时邮箱。