Idempotency Keys (SMTP)

Network glitches, timeouts, and connection drops during DATA can leave your sender unsure whether a message was actually accepted. Adding an X-Idempotency-Key MIME header lets you retry safely: a repeat with the same key and body is recognized as a duplicate, the original 250 reply is replayed, and no second message is queued or relayed.

Idempotency is currently scoped per region. A retry that lands on a different region than the original submission will not see the prior key and may produce a duplicate send. We are working on a global key store that will apply idempotency across all regions at once.

How it works

Pick a unique key per logical send (a UUID v4 is a safe default).
Add it as an X-Idempotency-Key MIME header inside the DATA payload.
If the connection breaks before you read the reply, retry the SMTP transaction with the same key and same body. The server replays the original 250 response without sending a second email.
If the same key is reused with a different body, the submission is rejected.

The X-Idempotency-Key header is stripped before delivery, so it never reaches recipients or appears on the relay leg.

Header reference

Header	Required	Notes
`X-Idempotency-Key`	No	Opaque string, 1 to 256 characters.

Keys are scoped per user. Pick something globally unique per logical send.

Example SMTP transaction

MAIL FROM:<alice@example.com>
RCPT TO:<bob@example.org>
DATA
From: alice@example.com
To: bob@example.org
Subject: Hi
X-Idempotency-Key: 4f8a5d-customer-order-12345
Message-ID: <abc123@example.com>

(body)
.

SMTP reply codes

Outcome	Reply	Notes
First time, accepted	`250 OK Message queued as <id>`	Cached for 24 hours.
Retry, same body	`250 OK Message already queued as <id> (idempotent replay)`	Same `<id>` as the original. No new message is queued or relayed.
Retry, different body	`554 5.5.0 X-Idempotency-Key reused with different body`	Use a new key.
Concurrent duplicate	`451 4.5.0 Idempotency in flight; retry`	The original is still processing. Retry shortly.
Key longer than 256 chars	`554 5.5.0 Invalid X-Idempotency-Key (length)`	Permanent.
Empty or missing header	Runs normally	No caching applied.

A replay keeps the 250 status code so standard SMTP clients still treat the response as success, with the original queue id in the same position as on the first reply.

Retry over the same transport

JetEmail also accepts an Idempotency-Key header on the HTTP API. Always retry over the same transport you originally submitted on. A cross-transport retry (HTTP after SMTP, or vice versa) will not match and will produce a new send.

Best practices

Generate the key before the first attempt, not on retry, so retries can reuse it.
Persist the key alongside the work item that triggered the send (e.g. an order or job row) so the same retry path always reuses the same key.
One key per logical send. Do not reuse a key for unrelated emails.
Pair with scheduled sends when the SMTP submission that schedules a message may itself be retried.

​Idempotency Keys (SMTP)

​How it works

​Header reference

​Example SMTP transaction

​SMTP reply codes

​Retry over the same transport

​Best practices

Idempotency Keys (SMTP)

How it works

Header reference

Example SMTP transaction

SMTP reply codes

Retry over the same transport

Best practices