SMS Alerts API for SaaS Apps — Template Ownership and Status Polling

When a SaaS application needs to send new-order alerts via SMS in the US and EU, the decision on who owns the SMS templates and delivery status becomes a critical operational constraint. Using a simple send-and-status API is the recommended approach when the application can manage the approved-template registry, retry policy, and polling loop.

If real-time event delivery or a large multichannel roadmap is a priority, a provider offering pushed delivery receipts should be chosen despite a potentially larger integration surface. This decision heavily influences the control-plane of the application and determines what will remain stable as it moves from prototype to production.

A new-order alert contains essential information such as order ID, seller name, item count, and a link to the marketplace. The key challenge lies in determining which system should be authoritative for the message template. If the provider owns the templates, the application must have a reliable method to manage and reconcile the provider's templates.

Conversely, if the application owns the templates, it should store its own stable template key, locale, revision, approval state, and provider-side identifier. Opting for application ownership is preferred as it allows the application to create a registry during the same release process as the order event contract. This registry acts as a stable reference point for testing and ensures a seamless transition when changing SMS providers.

The registry should be kept simple and focused on the message lifecycle, but not dependent on the SMS provider's template collection. The application, rather than the provider, should own the template meaning and revision. The same boundary applies to other types of alerts, such as attendance notifications for an education product, where the wording, locale, and recipient policies require the same level of release discipline.

A crucial aspect of the design is to send the alert quickly and then poll the provider for delivery status until the message has been marked as delivered or the application's deadline expires. This approach prevents false positives from a successful send request and ensures that the notification's urgency, the provider's rate limits, and the number of concurrent messages are considered when determining the polling interval.

The polling strategy should be adjusted based on the nature of the alert, with a different deadline for time-sensitive notifications like perishable order shipping alerts compared to less critical ones.

To manage the polling process, an external worker should be responsible for handling the message ID and the time for the next check. The worker should stop the polling once a terminal state is reached, back off when encountering rate limiting, and expose the provider's error details rather than converting all failures into a generic "pending" status.

This separation of concerns ensures that the main application logic remains focused on processing order events and does not get bogged down with the complexities of SMS provider interactions.

Before making any changes to the alert template or polling cadence, a set of predefined test cases should be executed. These cases include scenarios where the alert is accepted and then delivered, accepted but fails to deliver, the status is unavailable until the deadline expires, rate limiting occurs, and duplicate job executions.

By running these five key test cases, developers can gain valuable insights into the system's robustness and make informed decisions about the alert delivery process. Ultimately, the choice of SMS provider should be based on a fair comparison of the event model, ownership, and delivery features, rather than brand recognition alone.