Chapter 8.1 — Notifications

1. Purpose

travoBooks notifies customers, partner staff, and external systems of meaningful events through email, SMS, in-app push, in-platform inbox, and webhooks. This chapter defines the notification subsystem: the event-to-template mapping, channel routing, throttling, personalisation, retry semantics, and the per-partner customisation model that lets partners brand and localise their notifications.

2. Why it matters

• Customer notifications (e-tickets, vouchers, payment receipts) are the product as far as travellers see it.
• Operational notifications (approval requests, dispute alerts) drive partner workflow.
• Compliance notifications (privacy notices, statutory disclosures) carry legal weight.
• Unreliable notifications turn into "where's my ticket?" support load.

3. Channels

4. Notification taxonomy

Categorised by purpose:

4.1 Transactional (always sent)

• E-ticket on issuance
• Hotel voucher on confirmation
• Receipt on payment received
• Invoice on generation
• Refund confirmation
• Cancellation confirmation
• Schedule-change advisory
• Statement of account

4.2 Operational (to partner staff)

• Booking pending approval (to approvers)
• Customer credit hold placed
• ADM received (to BSP ops)
• Period-close gate failure (to controller)
• BSP file not yet imported on day X (to BSP ops)
• Failed payment alert
• Recon exception requires attention

4.3 Marketing (consent-based)

• Promotional offers (per partner)
• Loyalty / rewards updates

4.4 Compliance / informational

• Privacy policy updates
• Terms of service changes
• Statutory notices (jurisdiction-specific)

4.5 Security

• New device sign-in
• Password change
• MFA enrollment / disable
• API token issuance

5. Template system

5.1 Template structure

Each notification has a template per (notification_type, channel, language):

notification_type: booking.issued
channel: email
language: en
subject: "Your ticket {primary_ticket_number} is confirmed — {booking_ref}"
body_html: |
  <p>Dear {customer.first_name},</p>
  <p>Your booking <strong>{booking_ref}</strong> is confirmed...</p>
  ...
body_text: |
  Dear {customer.first_name},
  Your booking {booking_ref} is confirmed...
attachments:
  - type: pdf
    template: e_ticket_pdf

Tokens use safe interpolation: only allow-listed entity fields can be referenced; arbitrary expressions are not permitted.

5.2 Per-partner customisation

Partners can override platform default templates: - Branded letterhead (logo, colours). - Custom copy. - Custom signature. - Localised content per language.

Stored in partner_notification_templates; falls through to platform default when no override.

5.3 Localisation

Per-partner default_language; per-customer preferred_language overrides. Templates fall back: customer lang → partner default → English.

6. Routing

Channel routing follows the recipient's notification_preferences: - transactional — always sent (cannot opt out for legal/operational reasons). - operational — sent unless explicitly muted by user. - marketing — opt-in only.

7. Delivery contracts

8. Throttling & deduplication

• Per-recipient throttling: at most N notifications per minute (prevents inadvertent spam).
• Per-event deduplication: same event delivered once per channel per recipient.
• Bounce handling: persistent-bounce email addresses auto-marked invalid; alerts surfaced; partner-side fix required.
• Suppression lists: opt-outs, spam reports, hard bounces.

9. Compliance & consent

• CAN-SPAM / CASL / GDPR alignment: marketing emails always include unsubscribe link; preference centre per recipient.
• TCPA / local equivalents for SMS: explicit consent for non-transactional SMS.
• Audit trail — every notification's send-attempt logged with template version, channel, status; preserved per retention policy.

10. PDF generation

Many notifications carry PDF attachments (e-tickets, invoices, vouchers, statements). PDFs are generated by a worker pool: - Template engine renders HTML. - Headless Chromium converts to PDF. - PDF stored in S3 with retention. - Notification job references S3 object key.

Failure to generate the PDF does not drop the notification — the email is sent with a "your document will follow" copy and re-tried. For ticketing-critical PDFs (e-tickets), the email is held briefly (up to 30s) for PDF readiness; beyond that, fall-through sends and a re-send job re-attaches.

11. Operational visibility

• Email outbox view — per partner, see queued / sent / failed / bounced emails.
• SMS outbox view — similar.
• Notification trace — for any business event, see all notifications dispatched, their status, and the templates used.
• Per-recipient view — for a customer, see all notifications sent and their state.

Partner admins can resend a failed notification or trigger an ad-hoc one (e.g., "resend e-ticket"). Re-sends are throttled to prevent abuse.

12. Notification policies

Per partner / per notification type: - Send (default). - Suppress (e.g., partner sends own e-ticket from their own system). - Send + BCC partner ops. - Send only to partner ops (customer-facing not sent — for white-label partners).

This makes the platform usable for partners who want to keep all customer-facing comms in their own brand voice.

13. Database tables touched

14. Security & PII

• 🔒 Notification payloads may contain PII (passport copies, payment refs). Stored encrypted; access logged.
• 🔒 Email content with PII delivered to verified recipient addresses only; secondary CC restricted.
• 🔒 Templates audited for unintended PII exposure (e.g., not including full ticket data in templates that go to ops).

15. Common pitfalls

• ⚠️ Sending sensitive PII over SMS. SMS is unencrypted in transit on telco networks.
• ⚠️ Treating notification failures as silent. Always re-try and surface.
• ⚠️ Hard-coding sender email. Use partner-config + DKIM/SPF/DMARC for deliverability.
• ⚠️ Long retry tails for stale events. A schedule-change notification 24h late is no longer useful; have a TTL.
• ⚠️ Bypassing throttle for ops urgency. Maintain throttle; escalate via separate priority channel.
• 🔒 Templates with injection risk. Strict allow-list interpolation only.