How Should Infrastructure Teams Design Reliable Email and SMS Communication?
Short answer: for a small SaaS, use an email API for a transactional password reset only when the message contract, retry state, and delivery reporting are explicit. Treat email and SMS as two delivery channels with different failure modes, not as interchangeable notification switches. Define the reset event once, make delivery state observable, keep retries bounded, and give recipients a clear next action even when a network or downstream mailbox is unavailable.
This is a communication system, not just an API call. A useful design has four explicit boundaries: event creation, policy selection, channel delivery, and delivery reporting. Those boundaries let an infrastructure team change a template or transport without changing the business event that caused the message.
Should a small SaaS use an email API for transactional password reset?
The first question is not “Which email API is fastest?” It is “What must the recipient know, and what must they do next?” A transactional password reset, an account-security event, an operational incident, and a marketing reminder should not share the same urgency, retry policy, or content rules.
I start with a small message contract. It names the event, the intended recipient, the urgency, the allowed channels, and an idempotency key. The contract is deliberately boring. Boring contracts are easier to inspect at 02:00.
{
"event": "access_change",
"recipient": {
"email": "person@example.test",
"phone": "+15550001234"
},
"urgency": "high",
"channels": ["email", "sms"],
"idempotency_key": "access-change-8f41"
}
The event producer should not need to know whether an email was accepted, whether an SMS was delayed, or whether a recipient has opted out of a non-essential message. Those are delivery concerns. Keeping them separate also prevents an accidental retry from creating a second business action.
This pattern is not a universal answer. A very small SaaS with one low-volume transactional email may reasonably begin with a simpler queue and a single channel. A regulated workflow, a high-volume product, or a service that needs carrier-grade SMS controls will need stronger policy, audit, and reconciliation boundaries than this compact design describes. The trade-off is operational clarity versus implementation surface area.
Sometimes the right answer is simply one email, one reset link, and one recorded attempt.
Email is well suited to messages that need context, links, a durable record, or more than a few lines of explanation. SMS is useful when the recipient needs a short prompt and the timing matters. Neither channel is automatically “more reliable.” Reliability depends on the purpose, the recipient data, and what the system can observe after submission.
For each event, write down the channel decision in a policy table. A simple policy can be more precise than a large collection of implicit conditionals:
| Event class | Primary channel | Secondary channel | Content rule | Retry posture |
|---|---|---|---|---|
| Security-sensitive | SMS when explicitly allowed | Minimal detail; link to the authenticated surface | Bounded, observable | |
| Operational update | SMS for urgent states | Include status and next action | Retry transient failures | |
| Routine reminder | None by default | Include timing and preference controls | Avoid repeated sends |
The important detail is the word “allowed.” A phone number in a profile is not, by itself, consent for every category of SMS. The policy should carry recipient preference and regional constraints as inputs, and it should record the decision that was made.
How do you make retries safe?
Retries are necessary because delivery systems have transient failures. They are also where duplicate messages are born. The infrastructure needs two different identities: the identity of the business event and the identity of each channel attempt.
The event key answers, “Have we already handled this event?” The attempt key answers, “What happened when we tried this channel at this time?” A durable record can then distinguish a retry from a new notification. In practice, the awkward case is not a clean rejection. It is the timeout after the email API has accepted a transactional password reset but before the worker receives the response. The worker cannot safely conclude that nothing happened. It should retain the attempt as uncertain, use the idempotency key when the API supports one, and reconcile the provider reference or delivery report before creating another attempt. If no reconciliation signal exists, the runbook should define whether to wait, notify an operator, or retry under the existing policy. That decision belongs in the workflow design because a duplicate reset message can confuse a user even when both messages contain valid links.
CREATE TABLE communication_attempts (
event_key TEXT NOT NULL,
attempt_key TEXT PRIMARY KEY,
channel TEXT NOT NULL,
status TEXT NOT NULL,
provider_reference TEXT,
created_at TIMESTAMP NOT NULL,
updated_at TIMESTAMP NOT NULL,
UNIQUE (event_key, channel)
);
The unique constraint is not a complete delivery guarantee. It is a useful guard at one boundary. The sender still needs to handle a timeout after a remote system accepted the message but before the response arrived. In that case, the safest next step is to reconcile using the provider reference or delivery report, when available, instead of blindly sending again.
I also make retry classes explicit. A malformed address is not transient. A temporary connection failure may be. An accepted submission is not the same as delivery to the recipient. Those states should never collapse into one boolean called sent.
That distinction matters more than a green API response.
What should observability and message content show?
A dashboard that only counts API responses is too optimistic. For every event, I want to answer four questions:
- Was the message accepted by the communication service?
- Was it handed to the selected channel?
- Did a delivery report arrive, and what did it say?
- Did the system suppress, retry, or escalate the message?
Useful dimensions include event type, channel, outcome, latency bucket, retry count, and suppression reason. Avoid putting message bodies, full addresses, or phone numbers into ordinary logs. A stable redacted recipient identifier is generally enough to trace a workflow without turning the log store into a second contact database.
Metrics should preserve the distinction between submission and delivery. A high acceptance rate with no delivery reports is not healthy communication; it is incomplete knowledge. Alerts should focus on changes in those relationships, such as a rising gap between accepted and confirmed outcomes or an unusual increase in policy suppressions.
Templates belong outside the event producer. They should be versioned, reviewed, and rendered with escaping appropriate to the output format. Email HTML and SMS text have different constraints, so sharing a single unprocessed body usually creates confusing compromises.
Keep credentials in the runtime secret store and inject only the specific secret needed by the delivery worker. Do not write credentials, authorization headers, or complete rendered messages to debug logs. For local testing, use test recipients and deterministic fixtures rather than real contact data.
The message should also identify itself consistently. A stable subject convention for email and a concise prefix for SMS make support and incident review easier. That convention is an operational tool, not branding: it should help a recipient recognize the event and find the authoritative next step.
What changes for email and SMS during an incident?
Incident traffic is where the normal design gets tested. The system should have a way to classify events as urgent, pause non-essential categories, and keep the queue bounded. That control must be visible to operators and recorded with the event decision.
Do not solve an overloaded queue by increasing concurrency without a limit. First identify whether the bottleneck is local work, a downstream response, rate limiting, or delivery confirmation. Then apply a bounded queue, backoff, and a clear expiration policy. A notification that arrives after its action is no longer relevant may be worse than a missed notification.
For high-urgency messages, define the fallback before the incident. It may be a second channel, a human escalation, or a status page update. The fallback should not be an unbounded chain of automatic sends. Each additional channel increases recipient fatigue and makes reconciliation harder.
A practical review checklist
Before shipping a new email or SMS workflow, I review it with the following questions:
- What event creates the message, and is it idempotent?
- Which recipient preferences and constraints are evaluated?
- What does “accepted,” “delivered,” “failed,” and “suppressed” mean here?
- Which failures are retryable, and how many attempts are allowed?
- Can an operator trace one event without exposing message content?
- What happens if the submission response times out?
- Which content is safe to put in a notification, and where is the authoritative detail?
- How is the workflow paused or degraded during an incident?
The answers should live near the workflow configuration and in the runbook. If an operator has to infer them from scattered code during an outage, the system is carrying too much hidden policy.
Reliable email and SMS communication comes from explicit contracts and honest state transitions. Start with the event and recipient intent, choose channels through policy, record attempts separately from business events, and measure delivery as a process rather than a single API response.
The design does not need to be elaborate. It needs to make duplicates, suppression, retries, and uncertainty visible. That gives infrastructure teams room to change templates, providers, and operational controls while preserving the behavior that recipients depend on.
References
- RFC 5322, Internet Message Format: https://www.rfc-editor.org/rfc/rfc5322
- RFC 9110, HTTP Semantics: https://www.rfc-editor.org/rfc/rfc9110
- NIST, Digital Identity Guidelines: https://pages.nist.gov/800-63-3/
- OWASP, Logging Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
Top comments (1)
Treating email and SMS as distinct delivery channels with bounded retries and explicit message contracts prevents the common mistake of building fragile notification systems. Exposing delivery state early keeps password reset flows predictable under transient provider outages. When webhooks report delivery drops, what fallback mechanism or secondary route do you prioritize to prevent users getting locked out?