123eworld Knowledge Hub → Transactional SMS → Page 164
Transactional SMS API SLA Design: Availability, Queue Latency, Delivery Reporting and Service Objectives
A reference guide to designing honest SMS API SLAs and SLOs across API availability, queue processing, provider submission and delivery-report freshness.
Why SMS SLAs need multiple dimensions
A message API has several independent stages. API availability can be excellent while queue processing is delayed, and provider submission can be healthy while delivery reports are late. One uptime percentage cannot accurately describe the whole service.
API availability
Define availability for the customer-facing API using clear success and excluded conditions. Separate platform failures from invalid customer requests and documented maintenance.
Acceptance latency
For asynchronous submission, define how quickly a valid request should receive an acceptance response. This is a gateway and application objective, not a delivery guarantee.
Queue processing objective
Define how long accepted work should normally wait before a worker begins processing. Queue age is an important operational metric and can reveal capacity problems before API latency changes.
Provider submission
Provider submission objectives should account for route-specific capacity and dependency behaviour. If a provider is degraded, the platform may use failover or controlled backpressure.
Delivery reporting
Do not promise handset delivery timing as if it were fully controlled by the API. Instead define objectives around receipt processing and freshness, while explaining that carrier and handset conditions can affect final delivery.
Measurement windows
Use clear measurement windows and percentiles. A monthly SLA based only on averages can hide short but severe incidents. Tail latency and sustained outage duration should be considered.
Exclusions
Document planned maintenance, invalid requests and events outside the platform's control carefully. Exclusions should not become so broad that the SLA stops being meaningful.
Service credits
If commercial service credits are offered, define the calculation and evidence source. Operational SLOs and contractual SLA terms can be related but should not be assumed to be identical.
Error budgets
An SLO creates an error budget: the amount of failure or delay that can occur before reliability work should take priority. This helps engineering balance new features with operational stability.
Reporting
Publish internal dashboards for API availability, queue age, provider submission and delivery-report freshness. Review trends monthly and after major architecture changes.
Production checklist
Define each SLI, objective, measurement source, exclusions, error budget, alerting and customer reporting process.
Developer takeaway
A useful SLA describes what the platform controls and measures. Honest multi-stage objectives are more valuable than an unrealistic promise of instant SMS delivery.
Implementation architecture
Implement SLIs from observable system events rather than estimates. API availability can come from successful valid requests, queue latency from accepted-to-processing timestamps, provider submission from attempt timestamps and delivery-report freshness from provider event time versus ingestion time. Keep contractual SLA terms separate from engineering SLOs while ensuring the same underlying measurements can support both.
Operational reference
An SLO should be measurable from data that engineering trusts. If a metric depends on manual sampling or an incomplete log stream, it is not a reliable basis for an SLA discussion.
Operational reference
Error budgets should influence engineering priorities. When the service is repeatedly consuming its reliability budget, adding features without addressing the root cause increases operational risk.
Operational reference
Customer communication should distinguish an API outage from a provider or carrier delivery issue. This preserves trust and prevents the platform from making promises it cannot control.
Production checklist
Production check: verify each SLI, alert threshold, error budget, measurement window, exclusion and customer-reporting calculation.
Additional implementation guidance
Availability should be measured from the customer's perspective. A healthy internal server that cannot accept valid API requests is not meaningful availability.
Additional implementation guidance
Queue SLOs should use timestamps recorded at acceptance and processing. This avoids relying on estimates from worker logs that can be missing during the very incidents being measured.
Additional implementation guidance
Provider submission SLOs should be route-aware. A global average can hide a severe problem in one destination country.
Additional implementation guidance
Delivery-report freshness should be measured separately from final delivery. The platform can control how quickly it processes a receipt even though it cannot control how quickly a carrier generates one.
Additional implementation guidance
Error budgets can be split by service stage. If API availability is excellent but queue latency repeatedly consumes its budget, engineering work should focus on queue capacity rather than gateway uptime.
Additional implementation guidance
SLA reporting should use a reproducible calculation. Store the measurement source, window and exclusions so customer-facing reports can be audited.
Additional implementation guidance
Reliability targets should be reviewed as traffic and architecture change. An objective that was realistic at one million messages per day may be inappropriate at ten million.
Reference architecture note
An SLA should not imply that the platform controls carrier behaviour. The most defensible structure is to promise what the platform can measure: API availability, acceptance latency, queue processing and receipt-processing freshness. Delivery to a handset can be reported as an operational outcome with documented dependencies rather than guaranteed as an absolute time. This distinction protects the credibility of the service while still giving customers meaningful performance expectations.
Advanced production guidance
Service objectives should be communicated to developers in practical terms. A queue-latency objective can help customers decide whether they need priority processing or asynchronous workflows, while an API availability objective describes whether requests can be submitted.
Advanced production guidance
Measure objectives from independent telemetry where possible. If the same application component both performs the work and reports its own health, an outage can hide the evidence needed to calculate the objective.
Advanced production guidance
Review SLA assumptions after provider or architecture changes. A new route may improve delivery but alter reporting latency, while a new queue can improve throughput but change acceptance semantics.
Advanced production guidance
Reliability reporting should distinguish isolated customer configuration errors from platform failures. Otherwise the service may appear less reliable than it actually is.
Engineering reference
Define what happens when an SLO is missed. The response should include investigation, customer communication where required and reliability work rather than simply resetting the metric at the end of the period.
Engineering reference
SLAs should be supported by durable evidence. Keep enough measurement history to reproduce a monthly calculation if a customer challenges the result.
Engineering reference
Different service tiers may have different objectives, but the underlying measurement definitions should remain consistent. Otherwise comparisons become difficult and operational dashboards become fragmented.
Final engineering guidance
An SLA should identify the service boundary. If the platform depends on an external carrier network, the customer-facing contract should explain which portions are measured by the platform and which are external dependencies.
Final engineering guidance
Use the same definitions in dashboards, incident reports and customer documentation. Inconsistent terminology is a common source of disputes about reliability.
Final acceptance test
The final acceptance test should reproduce an SLA calculation from raw measurement records. Engineering and customer-facing teams should obtain the same result from the documented definitions.
Additional reference
If service tiers differ, define which objectives differ and why. Avoid creating separate definitions for the same metric simply because customers have different plans.
Additional reference
Incident reports should reference the same SLI definitions used for the SLA. This creates a consistent language for reliability improvement and customer communication.
Closing reference
The most useful reliability objective is one that changes engineering behaviour. If a queue-latency SLO is repeatedly missed, the team should have enough data to identify whether the cause is worker capacity, provider throttling, database contention or traffic bursts.
Final knowledge-base note
SLOs should be reviewed with real customer impact. A technically precise metric that does not correlate with what customers experience may need to be supplemented with another measurement. The objective is reliable service, not simply attractive dashboard numbers.
Final implementation rule
Keep SLA evidence reproducible from durable telemetry rather than manual estimates.
Final reference rule
Publish objective definitions before using them in customer reporting.
Completion rule
Keep the service boundary explicit in every SLA definition.
Final quality assurance
Review objectives after major architecture changes.
Continue through the 123eworld Knowledge Hub
Explore the complete 123eworld Knowledge Hub for practical SMS API, transactional messaging, queue, security and developer architecture guides.
Visit 123eworld.com for messaging and digital communication services.