Chapter 26: Notification Systems (Email, SMS, Push)

Why This Exists

E-commerce transactions are inherently asynchronous. A customer gives you their money immediately, but they do not receive the physical product for several days. This gap creates massive anxiety. Notification systems exist to bridge this silent void, providing reassurance (receipts), updates (tracking numbers), and marketing (abandoned cart reminders). A well-architected notification system dramatically reduces customer support volume; without it, every customer will call to ask, "Did my order go through?"

Real World Problem

A customer buys a $1,500 laptop. The payment succeeds, but the code that sends the "Order Confirmation" email crashes because the external email provider (like SendGrid) is down. The customer checks their inbox: nothing. They check their bank account: $1,500 is gone. They instantly assume they have been scammed by a fake website, call their credit card company, issue a chargeback, and leave a furious 1-star review. The real-world problem is that a silent failure in notifications is interpreted by the user as fraud.

Everyday Analogy

Imagine ordering food at a busy diner.

Email (The Postcard): The waiter writes down your order and gives you a receipt. It's a permanent record you can look at later.
SMS (The Pager): The restaurant gives you a buzzer that vibrates aggressively when your food is ready. It demands immediate attention.
Push Notification (The Tap on the Shoulder): The waiter walks by and says, "Your food is plating now." It's quick, contextual, and only works if you are physically in the restaurant (or have the app installed).

Beginner Explanation

A notification system is a robot that tells the user what is happening. When an order is placed, the robot automatically generates an email with a receipt and sends it. When the warehouse puts a shipping label on the box, the robot automatically sends a text message with the tracking number.

Intermediate Explanation

Architecturally, you must decouple the core transaction from the notification. If sending an email is a synchronous step inside the checkout() function, and the email server is slow (taking 5 seconds), your checkout takes 5 seconds. If the email server is down, your checkout fails.

Instead, use an Event-Driven Architecture. The checkout() function finishes, saves to the database, and publishes an event: Order_Created. The checkout is done instantly. A completely separate Notification Service listens for Order_Created events. It generates the HTML receipt and talks to SendGrid. If SendGrid is down, the Notification Service just waits and tries again 10 minutes later. The checkout is never impacted.

Advanced Explanation

At an enterprise scale, you build an Omnichannel Routing Engine. You don't want to spam a user on all three channels (Email, SMS, Push) for every minor update. The Router evaluates user preferences and message urgency:

Urgency: HIGH (e.g., Fraud Alert, Delivery Arriving Now): Route to SMS. If SMS fails, route to Push.
Urgency: MEDIUM (e.g., Shipped): Route to Push (if app installed & permissions granted). Fallback to Email.
Urgency: LOW / LEGAL (e.g., Receipt, Privacy Policy Update): Route exclusively to Email.

The Router also handles Templating. It fetches the raw data (JSON), fetches the localized template (e.g., Spanish or English), injects the variables, and dispatches it to the specific third-party provider APIs (Twilio, Firebase, SendGrid).

Real World Example

Uber's Notification Fallback: When your driver arrives, Uber tries to send a Push Notification. If your phone has a bad data connection and the Push acknowledgment fails to return within 5 seconds, Uber's routing engine automatically falls back and sends an SMS text message ("Your driver is here") because SMS uses cellular control channels, which often penetrate deep inside buildings better than 4G/5G data.

Architecture Design

Here is an Event-Driven Omnichannel Notification Architecture:

graph TD
    OMS[Order Management System] -->|Event: Order_Shipped| EventBus[Message Bus - Kafka/SQS]
    
    EventBus --> Router[Notification Routing Service]
    
    Router -->|1. Check Prefs| DB[(User Preferences DB)]
    Router -->|2. Fetch Template| Temp[(Template Engine)]
    
    Router -->|If High Priority| SMS[SMS API - Twilio]
    Router -->|If App Installed| Push[Push API - APNs/FCM]
    Router -->|Default / Fallback| Email[Email API - SendGrid]

Database Design

1. Notification Preferences:

CREATE TABLE notification_preferences (
    user_id UUID PRIMARY KEY,
    email_enabled BOOLEAN DEFAULT TRUE,
    sms_enabled BOOLEAN DEFAULT FALSE,
    push_enabled BOOLEAN DEFAULT TRUE,
    promotional_emails BOOLEAN DEFAULT FALSE -- Legally required opt-out
);

2. Notification Logs (For Support & Debugging):

CREATE TABLE notification_logs (
    id UUID PRIMARY KEY,
    user_id UUID,
    event_type VARCHAR(50), -- 'ORDER_SHIPPED'
    channel VARCHAR(20), -- 'EMAIL', 'SMS'
    status VARCHAR(20), -- 'QUEUED', 'DELIVERED', 'BOUNCED'
    dispatched_at TIMESTAMP
);

API Design

Internal Dispatch API (Used by other microservices): POST /internal/notifications/send Payload:

{
  "user_id": "123",
  "event": "ORDER_SHIPPED",
  "data": { "order_id": "999", "tracking_url": "http..." }
}

(The Router decides which channel to use based on this payload).

Production Considerations

Deliverability and Bounces: If you send emails to thousands of fake addresses, ISPs (like Gmail) will mark your entire IP address as spam, and your legitimate receipts will start going to junk folders. Your Notification Service MUST process "Bounce Webhooks" from SendGrid, immediately marking bad emails in your database so you never attempt to email them again.
Idempotency: If the Message Bus accidentally sends the Order_Created event twice, you do not want to send the customer two identical receipts. The Notification Router must use the Event_ID as an idempotency key.

Security Considerations

PII in Push Notifications: Push notifications wake up the phone and appear on the lock screen. Anyone staring at the phone can read them. Never put sensitive PII (like passwords, full names, or credit card digits) in the text payload of a Push Notification or SMS.
TCPA Compliance (SMS): In the US, the Telephone Consumer Protection Act carries massive fines ($500+ per text) if you send promotional SMS messages without explicit, documented user consent.

Common Mistakes

Synchronous Sending: Waiting for the SMTP server to reply before finishing a web request.
Hardcoding Text: Writing the actual email text inside the application code ("Hello " + user.name + ", your order shipped!"). If marketing wants to change a comma, you have to redeploy the whole backend. Always use external Template Engines (like SendGrid Dynamic Templates).

Tradeoffs and Alternatives

SMS vs. Push Notifications:
- SMS has a 98% open rate and doesn't require an app, but costs money per message (approx. $0.01 - $0.05).
- Push is entirely free to send, but requires the user to download your app and explicitly grant permission (which many decline).

Interview Questions

Why should sending an email receipt never be a synchronous step in the checkout API endpoint?
Explain how an Omnichannel Routing Engine decides whether to send an Email, an SMS, or a Push Notification.
How do you protect your domain's email reputation from being blacklisted by Gmail as spam?

Hands-On Exercise

Go to your email inbox and find a receipt from a recent online purchase.
Click "View Original" or "Show Headers" (in Gmail, click the three dots on the right).
Look for headers like Received: from, DKIM-Signature, and Return-Path. These are the cryptographic signatures and routing paths the Notification architecture uses to prove to Gmail that it isn't spam.

Key Takeaways

Notifications are the primary communication channel in asynchronous e-commerce.
Never send notifications synchronously; use an Event Bus and background workers.
Omnichannel routing optimizes the channel based on user preferences and message urgency.
Managing bounces and compliance (like SMS opt-ins) is just as important as sending the message.