Statamic Notifications Laravel Package

Product Decisions This Supports

• Build vs. buy on delivery reliability. v1.11.0 ships a transactional outbox pattern (notification + one notification_deliveries row per channel written atomically). This is the decision point where "notifications occasionally vanish when the mail provider hiccups" becomes a solved problem instead of a backlog item. It is the strongest argument yet for keeping notifications in this package rather than hand-rolling a queue-plus-audit-table layer.
• Roadmap sequencing for delivery guarantees. Deferred delivery is now the foundation for anything that needs at-least-once semantics: digests, scheduled reminders, drip campaigns, retry-on-provider-outage. Feature requests can be scoped against a real primitive instead of a bespoke build. The explicitly limited channel surface (in-app and mail only) gives a clean, defensible next milestone: extend DeferredChannel to push/SMS/chat.
• Use cases unlocked now: notifications that must survive a provider outage, sends that must not block a request (checkout, webhook handler, bulk import), mail-adjacent compliance/audit requirements ("prove what was sent, to whom, and how many attempts it took"), and recipient re-resolution at send time — i.e. send to whatever address/route the user has now, not the one captured at trigger time.
• Operational scoping decision. The addon deliberately schedules nothing; the host runs notifications:dispatch-pending. This is a product decision we must make explicitly: who owns the cron/supervisor entry, who gets paged when the pending backlog grows, and what the retry budget (max_attempts, backoff_seconds) should be per environment. It also drives whether we expose these as deployment defaults or leave them per-app.
• Trade-off we are accepting: a new notification_deliveries table, a migration, and per-channel rows per notification. That is real storage growth and a schema dependency in every consuming app — worth pricing before we commit broadly.
• De-risking expectations: claim-under-lock gives us "a row is claimed once," but that is not exactly-once delivery. Product must not promise duplicate-free sends. We should decide what duplicates are tolerable for mail vs. in-app and document it.

When to Consider This Package

Adopt when:

• Notifications are business-critical and silent loss is unacceptable — order confirmations, password/security events, transactional mail with audit exposure.
• Sends are triggered from request paths that must stay fast, or from unreliable external callbacks.
• Provider flakiness is a known, recurring support burden and you want bounded retries with backoff instead of ad-hoc re-send scripts.
• Recipient routing legitimately changes between trigger and send (profile email updated, account merged), making send-time resolution a feature rather than a bug.
• You need a queryable record of delivery outcomes (accepted, skipped, retry, cancelled, failed) for support tooling or compliance.
• Traffic is modest-to-moderate and an app-level cron running one artisan command fits your infrastructure. In-app and mail cover the channels you actually use.

Look elsewhere / delay when:

• You need push, SMS, or chat deferred today — those channels cannot carry a deferred row yet.
• You cannot guarantee a scheduler in every environment (multi-tenant, customer-hosted, serverless/ephemeral). An unscheduled dispatcher means notifications sit in the table indefinitely — the failure mode is worse than synchronous sending because it is silent.
• You need exactly-once semantics or strict ordering per recipient.
• Your notifications are already well-served by Laravel's native queued notifications plus Horizon — a queue worker with retries may be sufficient, and adding a second delivery mechanism increases concept count for the team.
• Volume is very high and you'd need retention/pruning and partitioning policy for notification_deliveries that the package does not provide.
• Low-stakes fire-and-forget notifications where the extra table, migration, and scheduled command are unjustified overhead.

Decision gate before rollout: confirm scheduler ownership, set max_attempts/backoff_seconds defaults, add a backlog-size alert, and define a retention policy for delivery rows.

How to Pitch It (Stakeholders)

To executives: This release closes a reliability gap that today shows up as customer-facing support tickets — missed confirmations and security emails. Sends are now written durably in the same transaction as the notification itself and retried with exponential backoff, so a mail provider outage delays messages instead of losing them, and we get a per-message record of what happened for support and audit. No new infrastructure: it is a config change, one migration, and one scheduled command.

To engineering: We now have a transactional outbox: Notifications::notifyDeferred() commits the notification and one delivery row per channel atomically; notifications:dispatch-pending drains them under a lock with configurable retries. Scope is intentionally narrow — only DeferredChannel implementations (in-app, mail) qualify, and recipients are resolved at send time via DeferredRecipientResolver. Two things to own on our side: the scheduler entry (the package schedules nothing) and monitoring the pending backlog plus terminal failed/cancelled outcomes. Claim-under-lock gives single-claim, not exactly-once — treat duplicates as possible and make handlers tolerant. Migration adds notification_deliveries; plan retention before volume ramps.