Skip to main content

Communications delivery

What this covers / who it's for. The mechanics of outbound comms: the guaranteed ordering between an action and its notification, the consent model and which notices bypass it, the durable record of every send, and its retention posture. The product-level view of channels and preferences lives in Notifications & comms.

The two delivery legs (and the guarantee between them)​

Every client notification splits into two legs: the inbox row is written inside the action's transaction (rolls back with it), while email is queued and fires only after the action commits — so a failed action never emails anyone, and a mail-transport outage delays email without ever blocking the action. The full channel/timing table lives in Notifications & comms.

Ordinary notifications respect per-channel preferences, re-engagement nudges are opt-in gated, and compliance notices plus security-critical ephemeral messages bypass consent entirely — the authoritative consent/bypass table is in Notifications & comms. One mechanics fact: a consent-suppressed send is a real outcome, not an error — the platform records that nothing was persisted for that recipient.

Operator alerts​

Operator-facing alerts (case escalations, DLP incidents) are routed by role: a configurable map assigns each notification type to the operator roles responsible for it, and every active holder of a mapped role receives it. The map ships empty — populating it is an operational decision, and until then each alerting module falls back to its own configured recipient or a visible audit-log line. A mapped type whose roles have zero active holders logs a loud misconfiguration warning rather than failing silently (notification README).

The durable comms record​

Every send is recorded in the comms log — the durable answer to "what did we tell this customer, when, on which channel", including compliance comms. Two retention facts (Data lifecycle guarantees):

  • The prune mechanism ships inert. A per-message-class retention prune exists and runs daily, but no retention window has been signed off — so it deletes nothing today. Comms history is effectively kept indefinitely until legal/compliance populate the windows.
  • Compliance notices are floor-guarded. Once windows are set, any message classed as a compliance notice is clamped up to the 7-year compliance retention floor, even if mis-configured with a shorter window.

How email physically leaves​

The mail transport is environment-driven: local dev delivers everything to Mailpit (nothing real is ever sent from a dev stack); production picks its transport per deployment — SMTP, SES, Postmark, and Resend are wired and available (config/mail.php). Which one production uses is a deploy decision, not a code fact.

← Product wiki index