Notification delivery internals
How the notification engine resolves channels, the channel provider registry, broadcast payload limits, replay guards, email layout resolution, and the notification and draft APIs.
Overview
This is the engine reference behind Notifications & Comms. The Notification & Communication Engine delivers multi-channel notifications (database, email, broadcast) with a three-layer resolution pipeline: system defaults → tenant settings → account preferences. Customer billing communications persist to communication_log with opt-out and unsubscribe support.
Channel provider registry
Channels register through a provider registry:
| Built-in channel | Purpose |
|---|---|
| Database | In-app notification records |
| Queued SMTP/email driver delivery | |
| Broadcast | Real-time via Reverb |
Reverb enforces a 10 KB limit per broadcast event, so Signals caps and slims every real-time notification payload. Broadcasts are lightweight envelopes; clients fetch authoritative details on demand instead of receiving full models, bodies, HTML, or exception context.
Plugins can register additional channel providers via the Plugin SDK.
Test a provider configuration: POST /api/v1/channel_providers/{channel_provider}/test.
Three-layer resolution
- System default — the seeded available and default channels for each notification type
- Tenant setting — company defaults on
/admin/settings/notifications(Company defaults tab) - Account override — each person's preferences on
/settings/notificationsor via the API
Company settings may explicitly opt into an installed plugin channel in addition to narrowing core defaults. Personal preferences only remove channels from the company selection. Installation alone never enables a plugin channel. A channel whose delivery driver is not registered (for example, a disabled plugin) is dropped.
Event→notification wiring includes a replay guard so projection replays do not duplicate sends.
In-app notification bodies
The header notification bell loads database notifications and refreshes on open. Real-time updates arrive via Reverb on the user's private channel. Event-specific bodies replace generic placeholders.
Email layout resolution
Every outbound email is wrapped in a branded layout — the document shell, styles, header, body slot, and footer — resolved at send time by EmailLayoutRenderer:
- the layout picked on the email template, when it is still active;
- the active default layout row;
- the shipped master layout (
EmailLayoutSeeder::masterBodyHtml()), branded from settings or, when the database or settings can't be read, from static defaults (the app name and default palette).
Notifications that fall back to a plain message use App\Notifications\Messages\BrandedMailMessage, which renders through the same layout chain instead of Laravel's stock mail template. An architecture test rejects plain MailMessage in app/.
Layouts themselves are edited at Email Layouts.
Communication draft endpoints
The draft lifecycle and permissions are described in Notifications & Comms → Communication drafts.
| Endpoint | Purpose |
|---|---|
GET /api/v1/communication_drafts |
List drafts (filter[field][operator] filtering) |
GET /api/v1/communication_drafts/{id} |
Show a draft |
POST /api/v1/communication_drafts |
Compose a draft |
POST /api/v1/communication_drafts/{id}/approve |
Approve, optionally editing first |
POST /api/v1/communication_drafts/{id}/discard |
Reject permanently |
POST /api/v1/communication_drafts/{id}/send |
Deliver an approved draft |
Communication log API
Administrators with appropriate permissions can browse dispatched communications — channel, template, recipient, status, and timestamps. Read-only API: Communication Log.
Notification preferences API
| Endpoint | Purpose |
|---|---|
GET/PUT /api/v1/notification_preferences |
Authenticated user's preferences |
GET/PUT /api/v1/accounts/{id}/notification_preferences |
Account-level preferences (admin) |
GET/PUT /api/v1/notification_settings |
System-wide notification settings |
See Notification Preferences API.
Built-in notification catalogue
The following built-in keys identify notification types, not delivery endpoints. A channel driver receives the same ChannelSendData contract for each eligible type. Plugin-defined notification keys extend this catalogue when their packages are installed.
database persists an in-app notification, broadcast delivers its real-time envelope, and mail sends email. The resolver normalizes these to the logical in_app and email channels. The table records original core metadata and defaults. Installing a driver leaves those defaults unchanged. Company administrators can explicitly select an installed plugin channel through notification settings; personal preferences only narrow the company selection. Notification settings responses include installed plugin channels in available_channels. This applies to the common dispatch pipeline, not dedicated authentication, digest or customer-communication mail paths. See Plugin Channel Providers for API examples.
| Type key | Name | Audience | Available channels | Default channels | Native plugin route |
|---|---|---|---|---|---|
user.invited |
User Invited | internal | database, mail | database, mail | Dedicated invitation email |
update.failed |
Update Failed | internal | database, mail | database, mail | Common account delivery |
search.index_lag |
Search indexing delayed | internal | database, mail | database | Common account delivery |
queue.job_failed |
Queued Job Failed | internal | database, mail | database | Common account delivery |
password.reset |
Password Reset | internal | Dedicated authentication email | ||
auth.magic_link |
Magic-Link Sign-In | internal | Dedicated authentication email | ||
auth.new_sign_in |
New Sign-In Notice | internal | Dedicated authentication email | ||
notification.digest |
Notification Digest | internal | Dedicated digest email | ||
workflow.internal |
Workflow Internal Notification | internal | database, mail | database, mail | Common account delivery |
approval_request |
Approval Request | internal | database, mail, broadcast | database, mail | Common account delivery |
approval_outcome |
Approval Outcome | internal | database, mail, broadcast | database, mail | Common account delivery |
approval_external_link |
External Approval Link | external | Email-only external approval link | ||
rental.created |
Rental Created | internal | database, mail | database | Common account delivery |
rental.confirmed |
Rental Confirmed | both | database, mail | database, mail | Common account delivery |
rental.cancelled |
Rental Cancelled | both | database, mail | database, mail | Common account delivery |
rental.on_hold |
Rental On Hold | internal | database, mail | database | Common account delivery |
rental.checked_out |
Rental Checked Out | both | database, mail | database, mail | Common account delivery |
rental.checked_in |
Rental Checked In | internal | database, mail | database | Common account delivery |
rental.late_return |
Late Return | internal | database, mail | database, mail | Common account delivery |
rental.quote_expiring |
Quote Expiring | both | database, mail | database, mail | Common account delivery |
conversation.mentioned |
Conversation Mention | internal | database, mail | database, mail | Common account delivery |
shortage.escalated |
Shortage Escalated | internal | database, mail | database, mail | Common account delivery |
shortage.acknowledged |
Shortage Acknowledged | internal | database, mail | database | Common account delivery |
shortage.resolution.confirmed |
Shortage Resolution Confirmed | internal | database, mail | database | Common account delivery |
shortage.waitlist.created |
Waitlist Monitor Created | internal | database, mail | database | Common account delivery |
shortage.waitlist.matched |
Waitlist Match | internal | database, mail | database | Common account delivery |
shortage.waitlist.expired |
Waitlist Expired | internal | database, mail | database | Common account delivery |
virtual_stock.overrun |
Virtual Stock Overrun | internal | database, mail | database, mail | Common account delivery |
invoice.created |
Invoice Created | external | Dedicated customer communication | ||
invoice.overdue |
Invoice Overdue | both | database, mail | database, mail | Common account delivery |
invoice.payment_received |
Payment Received | both | database, mail | database, mail | Dedicated customer communication |
invoice.credit_note |
Credit Note Issued | external | Dedicated customer communication | ||
statement.emailed |
Account Statement Emailed | external | Dedicated customer communication | ||
document.finalised |
Document Finalised | internal | database, mail | database | Common account delivery |
document.emailed |
Document Emailed | external | Common account delivery | ||
document.public_link_created |
Document Public Link Created | both | database, mail | database, mail | Common account delivery |
document.portal_question |
Document Portal Question | internal | database, mail | database, mail | Common account delivery |
document.approved |
Document Approved | internal | database, mail | database, mail | Common account delivery |
document.declined |
Document Declined | internal | database, mail | database, mail | Common account delivery |
invoice.portal_payment_received |
Portal Payment Received | internal | database, mail | database, mail | Common account delivery |
repair.created |
Repair Created | internal | database, mail | database | Common account delivery |
repair.updated |
Repair Updated | internal | database, mail | database | Common account delivery |
repair.released |
Repair Released | internal | database, mail | database | Common account delivery |
equipment_test.completed |
Equipment Test Completed | internal | database | database | Common account delivery |
equipment_test.failed |
Equipment Test Failed | internal | database, mail | database, mail | Common account delivery |
equipment_test.due |
Equipment Test Due Soon | internal | database, mail | database, mail | Common account delivery |
equipment_test.overdue |
Equipment Test Overdue | internal | database, mail | database, mail | Common account delivery |
certification.expiring |
Certification Expiring | internal | database, mail | database, mail | Common account delivery |
stock_check.closed |
Stock Check Closed | internal | database, mail | database, mail | Common account delivery |
flightcase.contents_overrun |
Flightcase Contents Overrun | internal | database, mail | database, mail | Common account delivery |
import_batch.committed |
Import Batch Completed | internal | database, mail | database, mail | Common account delivery |
import_batch.failed |
Import Batch Failed | internal | database, mail | database, mail | Common account delivery |
import_plan.completed |
Import Plan Completed | internal | database, mail | database, mail | Common account delivery |
import_plan.undone |
Import Plan Undone | internal | database, mail | database, mail | Common account delivery |
export.completed |
Export Completed | internal | database, mail | database, mail | Common account delivery |
export.failed |
Export Failed | internal | database, mail | database, mail | Common account delivery |
report.scheduled_delivery |
Scheduled Report Delivered | internal | database, mail | database, mail | Common account delivery |
report.threshold_alert |
Report Threshold Reached | internal | database, mail | database, mail | Common account delivery |
scheduling.conflict_detected |
Scheduling Conflict Detected | internal | database, mail | database | Common account delivery |
scheduling.conflict_resolved |
Scheduling Conflict Resolved | internal | database, mail | database | Common account delivery |
scheduling.demand_unmet |
Scheduling Demand Unmet | internal | database, mail | database, mail | Common account delivery |
scheduling.assignment_confirmed |
Assignment Confirmed | internal | database, mail | database | Common account delivery |
scheduling.assignment_cancelled |
Assignment Cancelled | internal | database, mail | database | Common account delivery |
scheduling.assignment_rescheduled |
Assignment Rescheduled | internal | database, mail | database | Common account delivery |
activity.due_soon |
Activity due soon | internal | database, mail | database, mail | Common account delivery |
activity.overdue |
Activity overdue | internal | database, mail | database, mail | Common account delivery |
The native-route column distinguishes 56 keys with common account delivery from 10 keys whose listed native delivery remains dedicated. “Common account delivery” means the host can pass account-recipient notifications to an explicitly enabled plugin channel; it does not promise delivery to arbitrary external email addresses. Mixed-audience customer mail and report emails to external addresses retain their email paths. A generic synthetic envelope can be rendered for all 66 keys, including the ten dedicated keys, without establishing native routing for those ten.
Fixed-path notifications
These additional notifications have fixed channels and no selectable notification-type key:
| Notification | Delivery | Purpose |
|---|---|---|
| Email verification | Verify the sign-in address. | |
| Email change requested / confirmation | Notify the current address and confirm the replacement. | |
| Two-factor authentication reset | Notify the person when an operator resets their authenticator. | |
| AI embedding budget exceeded | In-app and email | Alert administrators when monthly usage reaches the configured budget. |
| Workflow export ready | In-app | Notify that a workflow export can be downloaded; distinct from the export.completed event. |
Customer billing communications use the communication/template path and their corresponding type keys. Digest mail uses notification.digest. Generic domain-event, approval and plugin envelopes reuse existing or plugin-defined type keys. Database/broadcast wrappers and pipeline test notifications are transport or test mechanisms, not additional business types.
For channel contracts, provider configuration, address resolution, and testing, see Plugin Channel Providers.