Idempotency

Safe retries with idempotencyKey — duplicate sends return the same response.

Network failures and retries can accidentally send the same email twice. Use idempotencyKey to make sends safe to retry.

How it works

Generate a unique key per logical send (e.g. welcome-user-123-v1).
Pass it in MailingCore.send() or POST /emails/send.
If you retry with the same key within the retention window, the API returns the original response — no duplicate email.

import { MailingCore } from 'mailingcore-js'

const idempotencyKey = `order-confirm-${orderId}`

const result = await MailingCore.send({
  to: customer.email,
  subject: 'Order confirmed',
  htmlBody: '<p>Thank you for your order.</p>',
  idempotencyKey,
})

// Safe to retry on timeout — same key, same result
const retry = await MailingCore.send({
  to: customer.email,
  subject: 'Order confirmed',
  htmlBody: '<p>Thank you for your order.</p>',
  idempotencyKey,
})
// retry.id === result.id

Key design tips

Practice	Reason
Include business ID in the key	`invoice-${invoiceId}-sent`
Use `crypto.randomUUID()` for one-off sends	Guaranteed uniqueness
Do not reuse keys across different recipients	Each recipient needs its own key
Store the key in your DB	Correlate with your domain event

Batch sends and campaigns use their own idempotency strategies (campaignId:contactId for fan-out). See Batch send.