幂等与防重复发送

agent 会重试,网络会超时。simail 的设计保证重试永远不会发出第二封信。

Idempotency-Key

每个 POST 都接受 Idempotency-Key 请求头。所有发信都必须带它:messages/send、reply、reply-all、forward 和 drafts/{draft_id}/send。不带会返回 400 validation_error。在 MCP 里,发信工具改用参数 idempotency_key。

情况	结果
新键	请求正常执行
同一个键,同样的正文	返回原来的响应;什么都不会再执行
同一个键,不同的正文	409 idempotency_conflict
来自别的 key 或组织的键	视为新键(键的作用域是你的组织和调用它的 key)

普通请求的键保留 24 小时,发信的键永久保留。

键要描述意图,而不是某一次尝试。好的键来自你自己的数据:reply-msg_01JZX…-v1、order-1042-shipped、digest-2026-10-18。不要每次尝试都用一个随机值,那样就失去了意义。

client_id

创建邮箱和 pod 时也接受 client_id。同一组织里同样的 client_id 总是返回同一个对象,所以 agent 启动时可以”有就取、没有就建”自己的邮箱,不必自己记状态。

重复内容

与幂等键无关,发布服务会拒绝与同一邮箱在去重时间窗(默认 24 小时)内已发出的信完全相同的邮件:同样的发件人、收件人,同样规范化后的主题和正文。发信返回 409 duplicate_send。不要换个键再发;之前那封已经发出去了。

防循环

两个 agent,或一个 agent 和一个自动回复程序,可能永远互相发信。发布服务会拦下(422 send_blocked):

reasons	何时
loop_auto_reply	回复自动回复、退信,或另一个 simail agent 发来的信
loop_thread	24 小时内在同一线程里与同一对端往来超过 20 次
loop_peer	24 小时内跨线程与同一对端往来超过 40 次

外发邮件带 Auto-Submitted 信头和 simail 的防循环标记,守规矩的系统(包括其他 simail 邮箱)不会自动回复它。

结果未知时

如果邮件网络没有确认某次发信,发信状态会变成 outcome_unknown。simail 绝不自动重发。等到它的投递或退信事件到达,状态会被更正。人可以在控制台查看;你的 agent 不应换个新键再试。

安全重试

响应	要不要重试?
网络错误、超时、500、503	要,退避后用同一个 Idempotency-Key(有 Retry-After 就按它等)
429 rate_limited、429 daily_limit_exceeded	要,等过 Retry-After,同一个键
409 idempotency_conflict	不要;你改了正文。只有你确实想发一封新信时才换新键
409 duplicate_send	不要;已经发出去了
422 send_blocked、423 thread_locked、任何 403	不要;看 reasons,或告诉你的主人

每个错误都会写明 retryable: true 或 false;照它做。见错误码。