用临时邮箱 API 时你会遇到调用限制——每天能调多少次、每秒能发多少请求。这不是刁难，而是 API 设计的必要机制。本文讲清楚为什么限速、YYDS Mail 的限速策略、开发者如何优化。
为什么 API 要限速
不限速的 API 会面临三个问题：
- 资源滥用：个别用户大量调用，拖慢所有人
- 成本失控：每次 API 调用消耗服务器资源，无限调用 = 无限成本
- 安全风险：无限制的 API 容易被 DDoS 或暴力攻击
限速的本质是公平分配资源——让所有用户都能用，而不是少数人占用全部资源。
YYDS Mail 的限速策略
配额制（每日总量）
每个套餐有每日 API 调用配额：
| 套餐 | 每日配额 | 适合 | |------|---------|------| | 免费 | 基础额度 | 个人尝鲜 | | Plus | 更高额度 | 小团队 | | Max | 高额度 | 中型项目 | | Neo | 最高额度 | 大规模应用 |
具体数字见定价页。配额每日重置。
速率限制（每秒并发）
除了每日总量，还有每秒/每分钟的并发限制，防止单一用户瞬间打满服务器。
超限时会返回 429 Too Many Requests：
{
"success": false,
"error": "Rate limit exceeded. Retry after 60s."
}
开发者最佳实践
实践一：用 Webhook 替代轮询
轮询是最大的配额浪费。每次查询收件箱都消耗一次配额，但大多数查询是"空"的（没新邮件）。
用 Webhook 替代：邮件到达时主动通知，不消耗查询配额。
实践二：缓存结果
获取到的邮件内容缓存到本地，不要重复请求同一封邮件：
const messageCache = new Map();
async function getMessage(id) {
if (messageCache.has(id)) return messageCache.get(id);
const res = await fetch(`/v1/messages/${id}`, { headers });
const msg = await res.json();
messageCache.set(id, msg);
return msg;
}
实践三：指数退避重试
遇到 429 时不要立即重试，用指数退避：
async function apiCallWithRetry(url, maxRetries = 5) {
for (let i = 0; i < maxRetries; i++) {
const res = await fetch(url, { headers });
if (res.status === 429) {
const wait = Math.pow(2, i) * 1000; // 1s, 2s, 4s, 8s, 16s
await new Promise((r) => setTimeout(r, wait));
continue;
}
return res.json();
}
throw new Error("Max retries exceeded");
}
实践四：批量操作合并
需要批量创建邮箱时，合理控制并发，不要一次性发 100 个请求：
async function batchCreate(count, batchSize = 10) {
const results = [];
for (let i = 0; i < count; i += batchSize) {
const batch = Array.from({ length: batchSize }, (_, j) => createOne(i + j));
results.push(...await Promise.all(batch));
await new Promise((r) => setTimeout(r, 500)); // 批次间隔
}
return results;
}
监控配额使用
YYDS Mail API 响应头包含配额信息：
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 2026-07-16T00:00:00Z
建议在应用中监控这些头部，配额快用完时降级或提醒用户。
常见问题
配额用完了怎么办？ 等每日重置，或升级套餐获取更高配额。
429 错误怎么处理？
停止调用，等待 Retry-After 头指定的秒数后重试。实现指数退避。
免费套餐够用吗？ 个人测试够用。生产环境或 CI 大量测试建议付费套餐。
想用 API 集成临时邮箱？查看完整文档，或阅读临时邮箱 API 入门。