Email and Notifications

1. 1
   Fact committed

   The order exists, and an outbox row records that a confirmation is owed.

   fails by Sending from the handler instead, so a rollback leaves a confirmation for a nonexistent order (The Dual Write Problem).

2. 2
   Consumer picks it up

   A worker reads the intent.

   fails by Consumer dead; nothing errors and no email is ever sent (Queue Backlog).

3. 3
   Suppression check

   Is this recipient bounced, complained or unsubscribed?

   fails by Checked at enqueue rather than at send, so a fresh unsubscribe is ignored.

4. 4
   Claim the message key

   Atomic conditional insert on (template, recipient, entity).

   fails by Claiming after the send, or a non-atomic check, so a redelivery sends twice.

5. 5
   Render

   Template plus data becomes the final body.

   fails by Null field renders a raw placeholder; a template error fails after the claim, losing the message.

6. 6
   Provider call

   Provider accepts and returns an id.

   fails by Timeout with unknown outcome; 429 treated as a generic error (Retries).

7. 7
   Provider delivers

   SMTP conversation with the recipient's server.

   fails by Bounce, greylisting, spam classification. Reported later, or not at all.

8. 8
   Delivery webhook

   Provider reports delivered / bounced / complained.

   fails by Endpoint not implemented, so acceptance is mistaken for delivery (Inbound Webhooks).

Steps one to six are observable to you. Seven and eight are the ones that decide whether the customer actually got it.

const already = await db.sent.find({ orderId, template })
if (already) return                       // read-then-write: two workers both pass

await mailer.send({ to: user.email, template, data })
await db.sent.insert({ orderId, template })
// crash between send and insert -> the retry sends again
// and the customer has two confirmations

const key = `${tenantId}:${template}:${orderId}`

// atomic: unique constraint decides the winner.
// A concurrent worker or a redelivery loses here.
const claim = await db.notifications.insertIfAbsent({
  key, status: 'claimed', claimedAt: now(),
})
if (!claim) return                        // someone else owns this message

if (await suppression.blocks(user.email)) {   // checked at SEND time
  return db.notifications.update(key, { status: 'suppressed' })
}

try {
  const res = await mailer.send({
    to: user.email, template, data,
    idempotencyKey: key,                  // if the provider supports it, use it
  })
  await db.notifications.update(key, { status: 'accepted', providerId: res.id })
} catch (err) {
  // Deliberate: the claim STAYS. An ambiguous failure may mean it was
  // sent. For a receipt, a missing email support can resend beats a
  // duplicate the customer already read. Record it and surface it.
  await db.notifications.update(key, { status: 'unknown', error: String(err) })
  metrics.increment('notify.ambiguous')
}

The conditional insert makes the claim a single atomic operation, so concurrency and redelivery cannot both pass it — which the read-then-write version permits precisely during the retry storm it needs to survive. Keeping the claim after an ambiguous failure encodes a product decision about which failure the customer would rather have, instead of leaving it to whatever the retry policy happens to do.