频率限制

频率限制用来挡住失控的循环和滥用。能收发多少邮件的配额在用量、限额与熔断。

API 与 MCP

项目	限制	计数单位
带 API key 的请求(REST 和 MCP)	每分钟 600 次(突发)	key
不带 key 的请求	每分钟 120 次	IP 地址
每天的 API 调用	按套餐	组织
POST /v0/agent/sign-up	每个网段每小时 10 次。被拒的码还会让注册在本小时剩余时间暂停:按网络运营商(同一 ASN 每小时 50 次被拒)和全局(所有来源每小时 200 次);暂停时回 503 并带 Retry-After。最近一次成功注册在 7 天内、且本小时没有被拒码的网段不受暂停影响	网段 / ASN / 全局
POST /v0/waitlist	每个网段每天 5 次,每个网络运营商每天 50 次,另有全局每日上限	网段 / ASN
MCP OAuth 客户端注册	每天 10 次	网段
WebSocket	每个组织 50 个连接,每个 key 10 个,每分钟 10 次握手,每个连接 1 小时	组织 / key
Webhook 投递	每分钟 60 次(超出的延后,从不丢弃)	端点

网段指 IPv4 /24 或 IPv6 /48。突发限制在离你最近的节点执行,是近似值;按天的配额是精确的。

控制台(人)

项目	限制
发送邮件登录验证码	每个「邮箱 + 网段」组合每 15 分钟 3 次、每天 10 次;同一邮箱不分网段每天合计 30 次;每个网段每小时 20 次
验证码尝试	每个验证码 3 次;每个网段每小时 30 次验证
验证码失败	同一网段每小时失败 10 次,会把这个地址在这个网段的验证码登录锁一小时;来自任何地方的失败每小时累计 50 次,会把这个地址锁一小时。passkey 登录永远不会被锁。
再次验证的验证码	按会话计:每会话每 15 分钟发 3 次、每天 10 次(每个网段每小时 20 次,与登录分开计);每个验证码尝试 3 次;每小时失败 10 次,会把这个会话的再次验证码锁一小时
添加或删除 passkey	每个用户每天 5 次
兑换邀请码	每个用户每小时 5 次,每个 IP 每小时 20 次;连续失败 5 次锁定兑换一小时
控制台请求	已登录会话每会话每分钟 300 次;没有会话时每个网段每分钟 60 次(带会话 cookie 的请求先过每个网段每分钟 600 次的宽松检查)

响应从不透露某个邮箱是否注册过:无论是否注册,限额和提示都一样。

处理 429

每个 429 都带 Retry-After 请求头(秒),以及 retryable: true 的 problem+json 正文:

{
  "type": "https://docs.simail.ai/errors#rate_limited",
  "title": "RateLimitedError",
  "status": 429,
  "code": "rate_limited",
  "message": "Too many requests.",
  "fix": "Wait for Retry-After seconds, then retry.",
  "retryable": true,
  "request_id": "req_…"
}

• 至少等 Retry-After 秒,再重发同一个请求(发信要用同一个 Idempotency-Key)。
• 再次碰到限制时,加随机抖动并指数退避。
• 不要把负载分到更多 key 上来绕过限制;真正起作用的限制是按组织计的。
• 用事件(拉取、webhook、WebSocket)代替对邮件的紧密轮询。

429 daily_limit_exceeded 表示每日配额用完,不是突发限制:Retry-After 指向下一个时间窗。