没有幂等键也能安全重试：用Message-ID让Gmail发送可对账

每篇讲幂等性的文章结尾都一样："加一个幂等键就行了。"这个建议在你真正开始发邮件之前都成立。Gmail API 的 messages.send 根本没有幂等键参数——你 POST 一条原始消息，拿回一个 message id，或者连接中断、你什么都拿不到。此时你只能从外部判断：这封邮件到底发出去了没有。

盲目重试会导致重复发送，不重试又可能悄无声息地丢掉一条真实通知。这是最糟糕的那种分叉，因为客户两边都能看到。

本文整理自一位 n8n 工作流作者的 build-in-public 实践，核心思路是：让消息自己携带对账句柄（reconciliation handle），在零 provider 幂等支持的前提下，让 Gmail 发送变得可以安全重试。

rss source: No Idempotency Key? How I Make Gmail Sends Safe to Retry Anyway

核心洞察：Message-ID 就是你已经掌控的键

每封邮件都有一个 Message-ID 头。RFC 5322 要求它全局唯一，而 Gmail 会存储它、保持可搜索，并在它保存的副本上保留 SENT 标签。所以如果你自己设定 Message-ID，而不是让 Gmail 随机生成，你就把邮箱变成了一张查询表，可以回答"我是不是已经发过这封了？"。

关键在于：Message-ID 必须从任务本身确定性地派生，绝不能来自时钟。

// n8n Code node - 从稳定的 job key 确定性生成 Message-ID
const crypto = require('crypto');
const jobKey = $json.customer_id + ':' + $json.event_type + ':' + $json.order_id;
const hash = crypto.createHash('sha256').update(jobKey).digest('hex').slice(0, 32);
const messageId = '<job-' + hash + '@inbound.yourdomain.com>';

const raw = [
  'From: "Support" <support@yourdomain.com>',
  'To: ' + $json.to,
  'Subject: ' + $json.subject,
  'Message-ID: ' + messageId,
  'MIME-Version: 1.0',
  'Content-Type: text/plain; charset="UTF-8"',
  '',
  $json.body,
].join('\r\n');

return { json: { raw: Buffer.from(raw).toString('base64url'), messageId } };

有两个属性至关重要：键派生自源事件（customer id + event type + order id），因此同一个逻辑发送永远产生相同的 Message-ID；并且它不含 $now、不含 $execution.id、不含新生成的 uuid。

还有一个硬性要求：你必须自己发送原始 MIME——用 Gmail users.messages.send 的 raw 字段。如果让 Gmail 节点替你构造消息，Gmail 会分配它自己的 Message-ID，你就丢失了这个句柄。在 n8n 里，这意味着要用 HTTP Request 节点（或 Gmail 节点的 raw 字段），而不是友好的"Send"输入。

RFC 5322 对 Message-ID 的规范要求其格式为 <local-part@domain>，其中 local-part 应具备全局唯一性。这个头字段最初的设计目的是邮件线程追踪和去重，而非分布式系统对账——但它的存储与可搜索性恰好满足了后者的需求。Gmail 的 rfc822msgid: 搜索操作符直接命中该字段，支持精确匹配，而非全文模糊搜索，这使它具备了作为查找键的精度保证。

值得注意的是，RFC 5322 并不禁止发送方自行设定 Message-ID，Gmail 也不会拒绝携带自定义 Message-ID 的原始 MIME 消息。但如果你使用 Gmail 的高层 API（如 n8n 的 Gmail 节点"Send"模式），Gmail 服务端会在接收时覆盖你设定的值，这正是必须使用 raw 字段直接提交完整 MIME 的根本原因。

恢复步骤：去问邮箱，而不是靠猜

有了可控的键，清扫器（sweeper）就能做对账，而不是盲目重发：

GET /gmail/v1/users/me/messages?q=rfc822msgid:<job-abc123@inbound.yourdomain.com>

命中（且消息带有 SENT 标签）：发送已经发生。把任务标记为 done，不要重发。
未命中：发送没有发生。用同一个确定性 Message-ID 重试。

整个机制就这么简单。不需要 provider 支持，不需要额外服务，不需要具备 exactly-once 能力的依赖。只是一个你注入的键，加上一个你能运行的查询。

这种以「查询外部状态」替代「依赖本地记录」的思路，在分布式系统中被称为**幂等消费者模式（Idempotent Consumer Pattern）**的一个变体。传统方案通常依赖数据库中的去重表（deduplication table），以幂等键为主键，写入时用 INSERT OR IGNORE 或 ON CONFLICT DO NOTHING 来防止重复处理。本文的做法不同：它把 Gmail 的 SENT 邮箱直接作为这张去重表——既不需要额外的存储基础设施，也不存在去重表与实际发送之间的一致性问题（因为「记录」和「效应」是同一个对象）。代价是依赖了 Gmail 搜索索引的最终一致性，这正是下文「搜索索引不是即时的」一节所要处理的核心问题。

三个决定成败的关键注意事项

这不是免费午餐。跳过下面三点，你交付的 bug 会比你修复的那个更糟。

搜索索引不是即时的

Gmail 的搜索索引会滞后数秒到几分钟。崩溃后立即查到的"未找到"是不确定的，而非"确实没发"的证据。所以不要把第一次的否定结果当成"立刻重试"。应当延迟清扫器，等索引追上后再扫一次，只有在那个窗口之后仍然缺失才重试。如果某个渠道无法容忍这种延迟，那它应该进入 review，而不是自动重试。

Gmail 的搜索功能基于异步索引管道，消息在被 users.messages.send 接受后，并不立即对 q=rfc822msgid:... 查询可见。在生产环境中，这个延迟通常在数秒到数分钟之间，但没有官方的 SLA 上限保证。这意味着「查询不到」（HTTP 200 + 空列表）与「确实未发送」在崩溃后的短时间窗口内是不可区分的两种状态，正是分布式系统中经典的「模糊失败（ambiguous failure）」场景。

实践上，清扫器的等待窗口可设为保守值（如 3–5 分钟），并在第一次否定结果后再等待、再查一次，而非立即触发重试。对于对延迟零容忍的渠道，这个窗口本身就是一个信号：该操作不适合走自动化重试路径，应当路由到人工 review 队列。

命中证明存在，但不证明唯一

在你自己的邮箱里找到一份副本，是你发过它的证据，而不是服务端保证不存在第二份的担保。要断言唯一性，你必须计数：如果同一个 Message-ID 落地过两次，查询就会返回两条命中。所以应断言 hits == 1，而不是 hits >= 1。计数为二意味着重复效应，应该进入 review——那正是你一开始想检测的信号。

在效应发生的地方记录效应

在 provider 处计数副作用，或者在你的中继（relay）的接受日志里记录带有 Message-ID 的实际效应行——绝不要在 n8n 里计数。n8n 的执行次数完全不能告诉你邮件有没有真正离开。

不是每个渠道都值得同样的保证

一旦这招生效，要克制别到处滥用。先问清楚：每个渠道里一次重复到底代价多大？

客户邮件（收据、状态更新）：重复稍微烦人，但漏发更糟。at-least-once 加上一个去重提示才是正确的权衡，而这个 Message-ID 技巧让这种权衡也变得安全。
任何涉及金钱或不可逆操作：强制让 Unknown → review，交给人来决定。机制依然给了那个人一个可查的句柄，但绝不能自动恢复。

要把这个决策按 provider 逐个写下来，因为 exactly-once 是接收系统的属性——调用方无法强加。你的工作流的职责是诚实地说明它正在跟哪一类系统对话。

怎么测试

和任何崩溃边界测试一样：在 provider 前面放一个中继，支持三种模式。

fail-before-forward——Gmail 从未收到。重试必须安全，重发必须恰好产生一个效应（查询找不到，重试，第二次尝试是唯一的那次）。
forward-then-drop-response——Gmail 接受了，中继丢掉了响应。这是模糊类别。清扫器必须凭 Message-ID 找到消息并标记 done，而不重发。
forward-and-respond——正常路径。以 done 结束，清扫器不得触碰它。

断言三件事，全部放在接受日志里而不是 n8n 里：同一个键重试 → 恰好一个效应；丢响应 → 无重复；模糊任务 → 落入 review 且永不自动重发。并且要把 mock 结果当作 mock 结果报告——在你亲眼看到一次真实的模糊发送完成对账之前，一个绿色的 mock 测试并不等于 Gmail 的担保。

结语

你不需要 provider 递给你一个幂等键，才能让发送可以安全重试。你需要的是：一个你控制的键、一个记住它的地方，以及"去问而不是靠猜"的纪律。对 Gmail 而言，那个地方就是邮箱本身，而那个键就是你在发出时设定的 Message-ID。

n8n 是执行者，邮箱是真相之源。让它们各司其职，重复邮件就不会再发生。