Notifications
Status: Accepted Owner: @bilal Last Updated: 2026-02-15
When, what, and how notifications are sent across the platform.
Notification Matrix
| Event | Landlord | Tenant | Vendor |
|---|---|---|---|
| Issue created | SMS + Email | SMS (confirmation) | — |
| Vendor assigned | — | — | SMS + Email |
| Vendor accepts | SMS | SMS | — |
| Vendor declines | SMS | — | — |
| Issue completed | SMS + Email | — | |
| Rating requested | — | SMS | — |
| SLA breach | SMS | — | — |
Channels
| Channel | Provider | Best For |
|---|---|---|
| SMS | Twilio | Urgent notifications, tenant confirmations |
| SendGrid | Detailed info, landlord summaries | |
| Twilio / Meta API | Tenant conversations (future) |
Channel Selection
| Urgency | Landlord | Tenant | Vendor |
|---|---|---|---|
| Emergency | SMS immediately | SMS | SMS |
| High | SMS + Email | SMS | SMS + Email |
| Medium | SMS | SMS + Email | |
| Low | Email (batched) | SMS |
Processing
All notifications routed through n8n workflows:
Database trigger → n8n webhook → Route by event type → Send via channel
Error Handling
| Scenario | Handling |
|---|---|
| SMS fails | Retry 3x, fallback to email |
| Email fails | Retry 3x, log error |
| Invalid phone | Skip SMS, log warning |
| Rate limit | Queue and retry with backoff |
Logging
All notifications logged to events table with: issue_id, type (notification_sent), channel, recipient, template.
Templates
Templates managed in SendGrid (email) and code (SMS). Key variables:
{{organisation_name}}, {{property_address}}, {{room_number}}, {{issue_description}}, {{issue_category}}, {{issue_urgency}}, {{vendor_name}}, {{accept_link}}, {{dashboard_link}}
Future: Notification Preferences
See ADR-005 Notification Preferences.
Planned: per-user channel preference, quiet hours, digest mode, per-event opt-out.