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

Description and use

By injecting a deterministic Message‑ID into the raw MIME, the mailbox becomes a lookup table that confirms whether a send occurred, allowing safe retry without provider‑side idempotency support.

Problem

When sending email via Gmail API, lack of idempotency key causes uncertainty: blind retry can double‑send, no retry can silently drop a notification.

Outcome

By injecting a deterministic Message‑ID into the raw MIME, the mailbox becomes a lookup table that confirms whether a send occurred, allowing safe retry without provider‑side idempotency support.

Workflow

• 1. Generate deterministic Message‑ID from stable job key (customer_id:event_type:order_id) using SHA‑256 hash.
• 2. Build raw MIME message including custom Message‑ID header and send via Gmail API raw field.
• 3. After send, record Message‑ID in acceptance log.
• 4. Periodically run sweeper: GET /gmail/v1/users/me/messages?q=rfc822msgid:<Message‑ID>. - If hit count == 1, mark job done. - If no hit, retry send with same Message‑ID. - If hit count > 1, flag for review.
• 5. Handle caveats: delay sweeper to allow search index, count hits for uniqueness, log effect at provider side.

Evidence

The Gmail API's messages.send has no idempotency-key parameter.

Source

Derive the Message-ID deterministically from the job, never from the clock.

Source

If you set the Message-ID yourself - instead of letting Gmail generate a random one - you have turned the mailbox into a lookup table that can answer "did I already send this?".

Source

GET /gmail/v1/users/me/messages?q=rfc822msgid:<[email protected]>

Source

Search indexing is not instant.

Source

A hit proves existence, not uniqueness.

Source