Idempotency

Mailgrid deduplicates retried requests automatically. Send the same email twice — get one delivery.

How it works

Before each send, Mailgrid computes an idempotency key from a stable hash of the request payload:

key = sha256(tenant_id ⊕ scope ⊕ client_key? ⊕ sorted(payload))

If a row with that key already exists in the idempotency table:

• status = 'completed' → return the cached result with status: "replayed"
• status = 'in_progress' → reject with 409 CONFLICT

Otherwise we claim the key, perform the send, and write the final result back.

Custom idempotency keys

For cases where the payload is identical but you want distinct sends (or vice versa), pass your own idempotencyKey:

{
  "from": "hello@yourdomain.com",
  "to":   "user@example.com",
  "subject": "Welcome",
  "html": "<p>Hi</p>",
  "idempotencyKey": "order-12345"
}

TTL

Idempotency rows live for 24 hours. After that, the same payload sent again will be treated as a new send. A cron job (17 * * * *) purges expired rows.

Response shapes