Designing a Resilient Email Notification System with Provider Abstraction
This article outlines architectural decisions for building a robust email notification system in a SaaS application, particularly for healthtech. It emphasizes delivery reliability, provider neutrality, and a clear failure boundary. Key aspects include using a notification adapter, an outbox pattern, and a delivery-event poller to ensure reliable message delivery and state tracking independent of the email service provider.
Read original on Dev.to #architectureBuilding a reliable email notification system, especially in critical domains like healthtech, requires careful architectural planning beyond simply calling an email API. The core challenge is ensuring that messages are not just sent, but reliably delivered and their delivery status tracked, even if the underlying provider changes or fails. This article presents a robust architecture for achieving this goal.
Key Architectural Components and Invariants
The recommended architecture focuses on provider neutrality and a clear separation of concerns. It includes a provider-neutral notification adapter to abstract the email service provider (ESP) specifics, an outbox pattern for durable storage of notifications before sending, and a delivery-event poller to track the status of sent emails. This ensures that the application's internal state reflects actual delivery outcomes rather than just send attempts.
- Provider-Neutral Notification Adapter: Insulates the application logic from specific ESP APIs (e.g., Infrai, Postmark, SendGrid, Amazon SES), allowing for easier migration or multi-provider strategies.
- Outbox Pattern: Notifications are first stored durably within the application's database (assigned a local `notification_id`) before being picked up by a worker for sending. This guarantees that notifications are not lost if the sending process fails immediately.
- Delivery-Event Poller: Periodically fetches delivery and bounce events from the ESP to update the local state of each notification, providing crucial feedback on actual message delivery.
Critical Invariants for Reliability
- Production senders must use a verified domain with proper DKIM/SPF setup, treated as a deployment prerequisite.
- Each logical notification has one stable local identity, even across transport retries.
- Bounced or opted-out addresses must enter a suppression state to prevent future sends.
- Provider events are evidence of transport status, not the primary source of truth for the contact form content itself.
Email State Machine
A simplified state machine for email delivery helps manage complexity: `queued` → `submitted` → `delivered`, `bounced`, or `suppressed`. This minimal set of states controls data volume and reduces cardinality, as raw provider payloads can be verbose.