Idempotency

Networks are unreliable: a request times out, a process restarts, a queue retries. Pass an idempotency_key on a send and rootmail guarantees a single message even if the request arrives more than once. A replay returns the original message instead of sending again.

await mail.messages.create({
  to: user.email,
  template: "password-reset",
  variables: { reset_url },
  idempotencyKey: `pwd-reset-${user.id}-${tokenId}`, // stable per logical action
});

Over HTTP, send it as a header or in the body:

Idempotency-Key: pwd-reset-8821-4c1

Choosing a key

• Derive it from the action, not the attempt — e.g. the order id, not a random per-request value.
• Keys are scoped to your workspace and remembered for 24 hours.
• Reusing a key with a different body returns the first result; it does not send the new one.