Notifications & Comms
Notification channels, communication templates, customer emails, preferences, and the communication log.
Overview
Signals tells people about work in three places: the notification bell in the header, the email and real-time channels each person chooses under My Notifications, and customer emails such as invoices and statements. Administrators set company defaults for each notification type, edit the templates and layouts, review drafts before they go to customers, and browse the communication log.
Delivery starts with system defaults, then applies company settings and each person's preferences. Administrators may explicitly opt into installed plugin channels; personal preferences only narrow the company selection. Installing a plugin never enables delivery automatically. How channels, resolution and the delivery APIs work internally is described in Notification delivery internals.
Header notification bell
The header hosts <livewire:notifications.bell /> for every authenticated user with a linked account.
| Element | Behaviour |
|---|---|
| Bell icon | Unread count badge (caps at 99+) |
| Slide-out pane | Title "Notifications", paginated list, relative timestamps |
| Mark all read / per-item Read | Clears database notifications |
| Footer link | Notification preferences → /settings/notifications |
Real-time updates arrive via Reverb on the user's private channel; the bell also polls every 60 seconds.
My Notifications (user settings)
Route: /settings/notifications (Settings sidebar → Notifications)
Per notification type (grouped by category):
- Mute checkbox
- Channel toggles — only channels your company has enabled (In-app, Email, SMS, Slack, Teams)
Click Save to persist preferences. Users cannot enable channels the tenant has disabled.
Admin notification settings
Route: /admin/settings/notifications (Admin → Preferences → Notifications)
Permission: notifications.manage on mount and all actions
Header action Communication Log links to /admin/settings/communication-log. The same destination appears as a card on the admin landing page.
Delivery resolves from the type's defaults through company settings and each person's own settings. Company settings may opt into installed plugin channels; each person's settings can only narrow that selection.
Tabs
| Tab | Contents |
|---|---|
| Company defaults | Categories, the notification list or matrix, and the notification editor |
| Preview a person | Read-only grid of what one person gets after company and personal settings |
| Delivery channels | Delivery drivers (configure / send test) and how to add a channel with a plugin |
| Recent communication log | Latest outbound rows with a link to the full log |
| Retention | Log retention, prune safety window, unsubscribe link lifetime |
Delivery channels
One row per registered driver (In-App, Real-Time, Email) showing a status (Tested / Failing / Untested). Below the list, Add a channel with a plugin shows the three steps (create a plugin, implement a channel provider registered in the manifest, install and turn it on) with a link to the channel provider guide (hidden on cloud installs).
Outbound mail has a single home: Admin → Preferences → Email. The email card does not duplicate that form.
| Action | Purpose |
|---|---|
| Configure | Slide-over with provider fields for non-email drivers (credentials masked on save) |
| Configure in Email settings | Link on the email card to /admin/settings/email (admin.settings.email) |
| Send test | Fires test delivery against the shared settings; email uses the current Email settings (falls back to the signed-in user's address when no recipient is entered) |
Company defaults
List view. A rail of categories shows how many notifications in each send in-app alerts and email. Search finds notifications by name, description or key across categories. Each row shows the channels it sends on (on, off, or not used) and chips for Off, Always on, Everyone gets it (locked) and the audience.
Editor. Opening a notification shows one card per question, with a sticky In plain words summary ("When a rental is confirmed, the record's owner gets an in-app alert and an email…") and a save bar. Changes are a draft until Save Changes; leaving with unsaved changes asks first.
| Card | Purpose |
|---|---|
| How it is sent | One switch per channel (In-app covers in-app and real-time together). Notifications that go to your team and customers have a switch set for each. Choose from the type’s core defaults and installed plugin channels. Dedicated authentication, digest and customer-communication mail retain their dedicated delivery paths. |
| Who gets it | Recipient rules in plain words, with Edit Recipients (record owner, person who did it, role, roles chosen in settings, named person, assigned people, customer contact) |
| Can people turn it off? | Let people turn this off — off locks the notification: personal settings no longer mute or narrow it. Sign-in emails are always sent; customer-only notifications have nothing to lock. |
| The email | The email template(s) per warehouse with Edit Template, and a preview of the email with sample details in the default email layout |
Bulk changes. Tick notifications (or a whole group, or everything shown; Shift-click ticks a range), then Change Selected: turn on or off, turn a channel on or off, stop or let people turn them off, add or replace recipient roles, or reset to defaults. The dialog says how many will change and how many are skipped because the setting doesn't apply.
Matrix view. Notifications as rows and On, each channel and each role as columns. Click a cell, a column heading (sets the whole column) or a row heading (sets every channel in the row); arrow keys move between cells. Unsaved changes are counted in a floating save bar and saved together.
Every save — editor, bulk or matrix — goes through one audited action and records notification_setting.updated per changed notification.
Communication template editor
Route: /admin/settings/communication-templates/{template}/edit
Same unified editor as Templates. Type and warehouse chrome stay visible on communication rows.
| Panel | Contents |
|---|---|
| Title + Body | HTML body with merge-field browser (search + insert) |
| Email layout | Picker for email_layout_id on email-channel rows |
| SMS stats | Segment counter when SMS channel applies |
| Version history | Snapshots with change notes; Restore |
| Live preview | Sample vs real entity; optional rental picker; rendered title/body/HTML |
| Send test | Email-channel rows |
System communication templates are read-only — Duplicate to customise creates an editable copy. System email templates stay editable and use Reset to Default instead.
Communication drafts
A draft is a customer communication that has been composed but not sent. It is a separate record from the communication log — the log says what went out, and a draft that is discarded was never a communication at all.
Drafts appear on the Communications tab of a rental, invoice, or account, above the log, showing who composed each one (including whether it was an AI agent).
Lifecycle — approving and sending are separate steps. The UI may chain them, but the model never collapses them.
| Status | Meaning | Next |
|---|---|---|
draft |
Composed, awaiting review. The only editable state. | approve / discard |
approved |
A person signed the content off. Frozen. | send |
discarded |
Rejected. Terminal — it can never be sent. | — |
sent |
Handed to the delivery pipeline; communication_log_id is populated. |
— |
Free-text drafts. template_id and merge_data are optional. A draft composed as
prose has no template at all; the approved artefact is always the rendered snapshot in
subject_line / rendered_body.
What is delivered. Sending delivers the approved snapshot verbatim rather than
re-rendering the template — a re-render at send time could produce something no human
ever read. Everything else (opt-out checks, retries, delivery tracking, logging) is the
same pipeline every other customer email uses. template_id is still recorded on the
log for provenance.
A privacy-restricted recipient cannot receive a newly sent approved draft. The send
action returns a validation error on notifiable_id before creating a communication
log, changing the draft, or queuing delivery. The draft stays approved. Jobs queued
before restriction still check the current restriction at delivery and suppress the
message. Restriction retains communication preferences under the privacy policy;
erasure removes them. Unrelated recipients retain their preferences and deliveries.
Permissions. communications.draft composes; communications.approve approves,
discards, and sends. Approving, discarding and sending are all human-only by
construction: holding the permission is not enough, the acting context must resolve to a
person (or that person's API token). An AI agent may draft, never dispose of a draft —
the MCP surface exposes create-communication-draft and deliberately nothing else.
Sending shares communications.approve rather than taking a permission of its own, on
purpose: whoever may sign off the content is trusted to release it.
Every step also requires view on the record the draft is about, so a caller only ever
sees or acts on drafts for records they could read anyway; the draft index is scoped to
the record types the caller may view.
The draft endpoints are listed in Notification delivery internals.
Communication templates
Index: /admin/settings/email-templates (Admin → Preferences → Templates)
Edit: /admin/settings/communication-templates/{template}/edit
Per-warehouse communication templates are the single source of truth for transactional and auth email copy (magic-link sign-in, password reset, invitation, new-sign-in notice, daily digest) as well as billing and customer communications. TransactionalEmailResolver resolves warehouse template → hardcoded fallback; there is no parallel email_templates row for those type-keyed sends.
Type-less keys (test_email, embedding_budget_exceeded) and custom.* templates live on the same Templates index as a separate EmailTemplate model. The two tables are not merged.
Templates support version snapshots and restore, parallel to document templates. Communication versions use version; email versions use version_number. Compiled-segment cache is keyed off the communication version.
API: Communication Templates — CRUD plus version restore. The admin UI offers create, delete, duplicate, and send-test on the unified index.
Email layouts
Every outbound email is wrapped in a branded layout — the document shell, styles, header, body slot, and footer. The order in which a layout is chosen at send time is described in Notification delivery internals.
Layouts are database records edited at Admin → Preferences → Email Layouts, with a slot dialect ({{{ body }}} and friends), conditional blocks, escaped branding merge fields, version snapshots, and a live preview. Styles are inlined onto each element after rendering. The default layout is cached for an hour and busted by every layout write.
See Email Layouts.
Customer communications
Billing actions dispatch customer emails through DispatchBillingCustomerCommunication:
- Invoice issued / emailed
- Payment receipt
- Account statement
Each send is logged in communication_log. Customers can opt out via signed unsubscribe links.
| Setting | Type | Default |
|---|---|---|
notifications.communication_log_retention_days | integer | 365 |
notifications.communication_log_prune_safety_days | integer | 7 |
notifications.unsubscribe_url_ttl_days | integer | 365 |
notifications.inbound_signature_header | string | X-Signature |
notifications.inbound_timestamp_header | string | X-Timestamp |
notifications.inbound_tolerance_seconds | integer | 300 |
Communication log (admin)
Route: /admin/settings/communication-log
Permission: notifications.manage + warehouse scoping on rental subjects
Navigation: Admin landing → Preferences → Log; Notifications page header Open communication log
Filters: Status, Channel, Type, Recipient, From, To — Clear filters
Table: When, Type, Recipient, Channel, Status, Subject, and a row action to view the entry
Detail modal: rendered body, status timeline (Queued / Sent / Delivered / Opened), Pin / Unpin, failure reason callout
The same log table partial appears on invoice Communications, rental Communications, and account Communications tabs — scoped to that record.
Rental and account Communications tabs
| Tab | Route | Gate |
|---|---|---|
| Rental | /rentals/{rental}/communications |
rentals.view |
| Account | /accounts/{account}/communications |
Account view policy |
Both render paginated communication log entries for that record. The rental tab also carries the Conversations panel above the drafts and the log — one destination for everything said about the rental (see Conversations & Mentions).
Public unsubscribe
Signed URLs at GET /communications/unsubscribe/{account}?type={notification_type_key}.
The page shows masked email, explains the opt-out, and offers an Unsubscribe button (POST with CSRF). Success state confirms removal. Link lifetime follows Unsubscribe link lifetime (days) on the notifications admin page.
Permissions summary
| Permission | UI effect |
|---|---|
notifications.manage |
Admin notifications, communication log, template editor |
| Authenticated user | Bell, pane, /settings/notifications |
accounts.view |
Account communications tab (via account access) |
At a glance
Configure system-wide notification channels for each registered notification type. Requires notifications.manage.
The page is one sidebar item with five tabs: Company defaults, Preview a person, Delivery channels, Recent communication log, and Retention. Notifications are grouped by category, with a list view and editor, bulk changes, and a matrix view.
The communication log is that Recent communication log tab — not a nested Preferences sidebar item. The full-page log at /admin/settings/communication-log remains available from the tab and the Notifications header action.
Each notification type defines which channels are available and which are enabled by default. System-level overrides apply to all users unless individual users set their own preferences via profile settings or the Notification Preferences API.
| Setting | Key | Description |
|---|---|---|
| Unsubscribe URL TTL | notifications.unsubscribe_url_ttl_days |
Days until signed unsubscribe links expire (default 90) |
Related documentation
- Notification delivery internals — channel registry, resolution pipeline, payload limits and notification APIs
- Invoicing — billing email triggers
- Documents & Templates — PDF attachments in emails
- Email Layouts — the branded chrome around every email
- Admin Panel — notification and communication template settings