SMS as a Critical Notification Channel

SMS remains a powerful tool for urgent notifications, especially in scenarios like marketplace order confirmations or critical alerts. However, treating SMS as a simple fire-and-forget communication method is a recipe for disaster. The reality is far more complex, involving nuanced state management, explicit retry logic, and strict adherence to regional compliance guardrails. Relying solely on an SMS provider's capabilities is insufficient; the product itself must own the safety and reliability policy.

A common pitfall is modeling SMS sending as a synchronous operation within a transaction. A 10-second client timeout, for instance, might appear successful even if the SMS never reaches the recipient or the provider fails to acknowledge receipt. This ambiguity makes retries unreliable and error states difficult to diagnose. The chosen design pattern for robust SMS event alerts involves several key components:

  • Alert Record Creation: Before sending any message, an explicit record representing the alert is created in the application's database. This record serves as the single source of truth for the notification's lifecycle.
  • Idempotency Key: Each SMS dispatch is associated with a unique idempotency key. This prevents duplicate messages if the sending process is retried, ensuring that a single event triggers only one message.
  • Status Polling: Instead of relying on a single send attempt, the system actively polls the SMS provider for status updates. This allows for tracking the message through various states: sent, delivered, failed, or undeliverable.

This approach, while requiring more plumbing, transforms SMS delivery into a testable and replayable state machine. The product team maintains control over the notification lifecycle, not the provider.

Implementing Delivery Polling and State Management

The core of reliable SMS alerting lies in robust delivery polling. A simple HTTP POST request to an SMS gateway is merely the first step. The returned status from the gateway is often just an initial acknowledgment, not a guarantee of delivery. True delivery status requires a persistent polling mechanism. This means implementing a background worker or a scheduled job that periodically checks the status of sent messages using their unique IDs or idempotency keys.

The states a message can transition through are critical for user experience and debugging:

  • Queued: The message has been created and is awaiting dispatch to the SMS provider.
  • Sending: The message has been handed off to the SMS provider, but final delivery is not yet confirmed.
  • Sent: The SMS provider confirms the message has been successfully handed off to the mobile carrier network.
  • Delivered: The recipient's device has confirmed receipt of the message. This is the ideal outcome.
  • Failed: The message could not be delivered due to reasons like an invalid phone number, network issues, or carrier rejection.
  • Undeliverable: The message was rejected by the carrier or the recipient's network as permanently undeliverable.

Each of these states must be reflected in the application's UI or internal logs. This provides transparency to users and invaluable debugging information for the engineering team. The polling worker should handle rate limits imposed by the SMS provider and implement exponential backoff for retries to avoid overwhelming the provider's API.

Resends and Cancellation Logic

Ambiguous timeouts and lack of durable attempt IDs can lead to duplicate messages or missed notifications. A well-architected system needs explicit logic for handling resends and cancellations.

Resend Strategy

When a message is initially marked as failed or undeliverable, it doesn't necessarily mean the user will never receive it. Network glitches or temporary carrier issues can occur. A smart resend strategy involves:

  • Configurable Retry Counts: Define a maximum number of times a message should be retried.
  • Backoff Intervals: Implement increasing delays between retries (e.g., 1 minute, 5 minutes, 15 minutes, 1 hour).
  • State Tracking: Ensure that retried messages are clearly marked as such, and that the final state accurately reflects the outcome after all retries.
  • Event-Driven Triggers: Resends can be triggered by specific event types or by user actions, rather than solely by an automated process.

Cancellation Policy

In some cases, an alert might become obsolete before it's delivered. For instance, a marketplace order might be cancelled. The system must support a cancellation mechanism. This could involve:

  • API for Cancellation: An endpoint to mark an alert as cancelled, preventing further sending or retries.
  • Polling for Cancellation Status: If the SMS has already been sent to the provider, a cancellation request might need to be sent to the provider, and its status polled. However, many providers do not support true SMS cancellation once dispatched. The application logic must account for this limitation.
  • Grace Period: Define a short grace period during which a sent message can still be cancelled.

The product team must decide whether cancellation is a critical feature or if simply allowing the message to be delivered and then showing a