Transactional SMS API Capacity Planning: TPS, Queue Depth, Provider Limits and Peak Traffic

Capacity is end-to-end

API request capacity is only one part of messaging capacity. The platform must also persist messages, enqueue work, process provider requests, receive delivery callbacks and update state.

TPS versus messages per second

Requests per second and messages per second are not always identical. A batch request may contain many recipients, while one API request may create one message. Capacity models should use the actual unit being processed at each layer.

Peak traffic

Use realistic peaks rather than daily averages. Banking transaction periods, e-commerce flash sales, exam results and OTP-heavy events can create sudden bursts.

Queue absorption

A queue can absorb short bursts when messages have sufficient lifetime. Estimate how quickly backlog grows and how long it takes to drain after the peak.

Provider limits

Provider throughput is often the hard external ceiling. Internal workers should be sized and throttled so they do not continuously exceed provider capacity.

Database capacity

Message inserts, delivery updates, idempotency checks and reporting queries all consume database resources. Capacity planning should include write IOPS, connections, CPU, storage and index growth.

Callback capacity

A successful outbound burst can create a later inbound callback burst. Callback infrastructure must be able to process delivery events without becoming the next bottleneck.

Headroom

Operating permanently at maximum capacity leaves no room for provider variability, deployments or traffic spikes. Define an operational headroom target based on business requirements.

Load testing

Load tests should simulate realistic message sizes, tenant distribution, provider latency, callback rates and failure conditions rather than sending empty requests at maximum speed.

Scaling dimensions

API servers, queue workers, callback consumers and databases may need independent scaling. Adding API servers does not help if the provider or database is saturated.

Capacity model

A useful model estimates arrival rate, service rate, concurrency, backlog growth and recovery time. For a simple queue, if arrivals exceed sustainable processing rate for a period, backlog grows by approximately the difference between those rates.

Implementation checklist

Measure TPS, message rate, provider throughput, queue age, database capacity, callback volume, peak bursts, headroom, scaling dimensions and recovery time.

Capacity formula

For a simplified queue, if messages arrive at rate λ and sustainable processing is μ, backlog grows whenever λ exceeds μ. If a burst adds B messages and processing has spare capacity of S messages per second after the burst, approximate drain time is B divided by S.

Real systems also need to account for concurrency, retries, provider variability and callback processing.

Concurrency limits

Worker concurrency should be calculated from provider throughput and average request duration rather than selected arbitrarily. If provider capacity is 500 requests per second, creating thousands of simultaneous provider connections will not create 2,000 messages per second of useful throughput.

Peak-event modelling

Model business events explicitly: sale launches, payment cycles, exam results, OTP spikes, disaster notifications and campaign releases. Use historical traffic where available and include plausible growth.

Queue drain target

Define how quickly the platform must recover after a peak. A queue that takes six hours to drain after a ten-minute event may technically survive but fail the business requirement for time-sensitive notifications.

Database write model

Estimate message creation writes, status updates, DLR inserts and index maintenance separately. A provider outage can increase retries and therefore multiply database writes even while outbound throughput falls.

Callback surge model

For each outbound message, estimate the number and timing of expected provider events. Duplicate callbacks and intermediate statuses can increase inbound volume beyond one event per message.

Load-test acceptance

Define pass criteria before testing: API latency, acceptance rate, queue age, provider throughput, database utilization, callback processing lag and recovery time. A load test without acceptance criteria produces numbers but not an engineering decision.

Production scenario

A retailer expects 20,000 messages per second for ten minutes. Capacity planning calculates API, queue, worker, provider and database requirements, reserves headroom, tests the expected burst and verifies that the backlog drains within the required window after traffic returns to normal.

Capacity by tenant

Model the largest tenants separately from the average tenant. A platform can meet aggregate capacity while one enterprise customer creates a local bottleneck through a sudden burst.

Capacity by provider

Calculate capacity per provider and route, including sender and country restrictions. Aggregate provider capacity is not necessarily interchangeable if different routes serve different destinations.

Capacity during failure

Plan for degraded capacity. If one provider disappears, the remaining provider may not have enough throughput for all traffic. The platform needs a documented prioritization and admission strategy.

Capacity runbook

The runbook should specify when to scale workers, increase database capacity, reduce bulk traffic, activate an additional provider route or temporarily reject low-priority work.

Developer rule

Capacity planning is successful when the system remains predictable during both normal peaks and dependency failures.

Capacity security

Rate limits and admission controls are part of capacity security. Without them, a compromised credential can create a traffic spike that consumes provider quota and harms other tenants.

Capacity metrics

Track utilization and headroom for API nodes, database connections, queue workers, provider throughput and callback consumers. Monitor the slowest constrained layer rather than only infrastructure averages.

Capacity acceptance test

Run a realistic peak load with provider throttling and callback surges, then verify API latency, queue age, provider utilization and recovery time against predefined targets.

Reference rule

Capacity plans should include both the happy-path peak and the degraded-capacity case.

Capacity and cost

Capacity decisions should include infrastructure and provider cost. Overprovisioning every component for the largest theoretical peak may be inefficient, while underprovisioning can cause customer-impacting delays. Queueing and autoscaling can absorb predictable bursts when message expiry permits it.

Capacity and deployment

Deployments consume capacity. During a high-volume event, rolling restarts can temporarily reduce worker or API capacity. Capacity plans should include deployment headroom and maintenance windows.

Capacity and growth

Review the capacity model as traffic grows. New tenants, additional countries, larger templates and new providers can change the bottleneck even when the API request rate remains similar.

Failure-mode walkthrough

A flash sale creates a ten-minute burst that exceeds normal provider throughput. The queue absorbs the difference, but capacity planning also checks message expiry and drain time. When one provider becomes throttled, the platform calculates remaining capacity rather than simply doubling workers. Critical traffic is protected and low-priority work is delayed safely.

Architecture checklist

Confirm peak arrival rate, sustainable service rate, provider ceilings, database write capacity, callback surge, headroom, degraded-capacity behaviour, scaling limits, load-test criteria and backlog recovery time.

Capacity scenario planning

Build at least three models: normal peak, extreme business event and degraded dependency. For each, calculate expected arrival rate, sustainable processing rate, backlog growth, queue drain time and critical-traffic protection. Include growth assumptions so the model does not become obsolete immediately.

Practical implementation

Keep capacity assumptions in a versioned document or configuration repository. When provider limits, database architecture or traffic forecasts change, update the model and rerun the relevant load tests.

Final capacity scenario

A high-volume customer event creates a burst three times larger than normal. Capacity controls protect the provider ceiling, the queue absorbs work that remains within its business lifetime and reserved capacity protects critical notifications. After the event, workers process the backlog at a measured rate until queue age returns to normal.

Final implementation note

Repeat capacity tests whenever traffic forecasts or provider limits materially change.

Operational acceptance

During acceptance testing, simulate normal peak traffic, an extreme burst and the loss of one provider route. Measure API latency, queue age, worker utilization, provider throughput, database load, callback lag and drain time. The platform should meet predefined objectives while preserving critical traffic and avoiding uncontrolled retry amplification.

Final engineering note

Document capacity assumptions, bottlenecks and recovery targets beside the architecture.

Reference summary

Capacity planning must connect business traffic forecasts to every technical bottleneck. Model arrival rates, sustainable processing, provider ceilings, database writes, callbacks, headroom and degraded scenarios, then validate the model with realistic load tests.