123eworld Knowledge Hub → SMS API → Page 304
SMS API Bulk Sending: Batch APIs, Queueing, Throughput and Safe Campaign Processing
A practical developer reference designed to solve real implementation and production problems around sms api bulk sending: batch apis, queueing, throughput and safe campaign processing.
Bulk sending is different from single-message sending
A bulk API must protect the platform from enormous request bodies while giving customers efficient submission. It should create a batch identity and process individual logical messages asynchronously.
Batch size
Set a documented maximum number of items per request. Very large campaigns should be split into manageable batches or uploaded as jobs.
Item-level status
Each item needs its own logical message ID and result. A batch-level success cannot mean every item was accepted.
Queue admission
Validate authentication, authorization, basic request structure and quota before accepting a large batch. Otherwise invalid campaigns can consume queue capacity.
Throughput control
Workers should respect tenant limits and provider capacity. Bulk traffic should not overwhelm transactional traffic.
Idempotency
Support batch and item-level idempotency. Retrying a failed HTTP request must not duplicate already accepted items.
Scheduling
Scheduled campaigns should enter normal queue processing when due, with expiry and cancellation policies.
Partial failures
Return or expose per-item validation failures without forcing customers to resend successful items.
Reporting
Batch dashboards should show total items, accepted, rejected, queued, delivered, failed and retried.
Testing
Test large batches, duplicate requests, worker failures, provider throttling and partial validation errors.
Reference architecture
Authenticate → validate batch → create batch ID → persist items → queue → throttle → route → submit → reconcile → report.
Operational safety
Provide pause, cancel and controlled resume functions for authorized operators.
Security and privacy
Treat phone numbers, message content, credentials and delivery data as sensitive operational information. Avoid unnecessary logging and ensure tenant authorization is applied before data access.
Production reliability
Design for timeouts, duplicates, retries, provider failures and delayed events. A messaging platform is asynchronous infrastructure, so success-path testing alone is insufficient.
Developer-first principle
The public API should hide unnecessary telecom complexity while exposing enough structured information for developers to build correct integrations.
Related 123eworld guides
Explore the 123eworld SMS & WhatsApp Knowledge Hub for related developer, API, routing and production guides.
Batch request contract
A batch API should return a batch ID quickly after validation and durable acceptance. The response should not pretend that every message has already been submitted to a provider. Each item should receive its own logical message ID once it is accepted.
Validation before admission
Validate the structure, authentication, tenant quota and basic recipient/sender requirements before consuming large queue capacity. For huge jobs, consider a staged validation process so invalid campaigns can be rejected before millions of items are created.
Partial acceptance
Bulk processing should support partial outcomes. Some items can be valid while others fail validation or destination eligibility. The customer should be able to retrieve item-level results and retry only failed or eligible items.
Throughput controls
Use tenant-specific queues, provider capacity limits and message priorities. Bulk traffic should not monopolize worker concurrency. If a provider is throttling, reduce the batch worker rate rather than creating a retry storm.
Pause and cancellation
Authorized users may need to pause a campaign before more items are submitted. Cancellation should have a defined boundary: queued messages can often be cancelled, while provider-submitted messages may no longer be recallable.
Campaign reporting
A useful batch report separates total items, accepted, queued, submitted, delivered, failed, retried and cancelled. Segment count and provider attempt count can be included for cost and operational analysis.
Streaming large jobs
For very large campaigns, accept a job manifest or controlled file-based import rather than forcing a massive JSON request through the API. Validate the job, assign a batch ID and process records through the same message lifecycle used by ordinary sends.
Duplicate protection
A bulk system should preserve item-level client references or idempotency keys. If the upload is retried, already accepted items must be recognized. This is essential when a network connection fails after the server accepted only part of a large request.
Campaign throttling
Campaign traffic should be scheduled against available capacity. A campaign can be valid but still exceed the customer's contracted throughput. The platform should queue it rather than creating uncontrolled provider throttling.
Safe cancellation
Cancellation should stop new submissions while allowing already submitted messages to reach their natural terminal state. Reports should distinguish cancelled queued items from provider failures.
Batch status API
Expose batch-level progress separately from item-level results. Customers need to know whether a job is still processing without downloading every item on every poll. Counters such as total, queued, submitted, delivered and failed provide useful progress information.
Campaign segmentation
Very large campaigns can be partitioned into controlled internal chunks. The customer still sees one batch identity while the platform manages smaller queue units. This allows worker scaling and safer pause/resume behaviour.
Compliance and suppression
Bulk sending should apply the same sender, destination and content controls as individual messages. A batch API must not become a route around validation, quotas or suppression rules.
Admission control
The platform should estimate the physical workload of a batch before accepting it when possible. A million logical messages containing long Unicode text can represent far more provider segments than a million short GSM-7 messages. Admission should therefore consider segment volume, not only item count.
Worker recovery
If a bulk worker crashes after submitting an item but before recording the result, the queue must reconcile the uncertain attempt before resubmitting. This is the same distributed-systems problem seen in single-message sending, just at greater scale.
Customer-facing progress
Progress counters should be monotonic where possible and should not jump backward because late provider events arrive. Define what each counter means so customers can trust the dashboard.
Batch APIs and billing
Billing should normally distinguish one logical batch, individual logical messages and physical SMS segments. A batch request is not a single billable message. Clear reporting prevents customers from misunderstanding why a large campaign contains more billable units than its item count.
Operational safeguards
Large jobs should have configurable maximum rates, pause controls and expiry policies. These safeguards allow operators to stop an accidental campaign without deleting historical evidence or corrupting message state.
Batch completion semantics
Define when a batch is complete. It should normally mean that every item has reached a terminal processing state, not merely that the batch was accepted. Customers can then build reliable campaign reporting and reconciliation.
Final bulk principle
Bulk APIs should increase efficiency without bypassing the same validation, idempotency, routing, compliance and delivery controls used for individual messages.
Production implementation detail
Bulk APIs should expose a clear relationship between batch ID, item message ID and provider attempt. This lets an enterprise system reconcile one campaign without downloading or resubmitting the entire batch. When a provider is slow, the batch can remain accepted while item-level progress advances gradually. This separation between acceptance and delivery is fundamental to reliable asynchronous campaign processing.
Final developer checklist
Bulk processing should also protect against accidental duplicate campaigns. Provide a human-readable campaign name or client reference and show batch creation time, owner and item count. An authorized pause or cancellation action can then be performed against the correct job. This small operational feature can prevent a large accidental send from becoming a telecom incident.
Closing reference note
A bulk campaign should have explicit expiry semantics. If messages remain queued after their business relevance has passed, the platform should be able to stop them rather than delivering obsolete notifications. Expiry should be evaluated before provider submission, while already submitted messages remain subject to their normal delivery lifecycle. This distinction protects both customers and recipients.
Reference implementation reminder
Bulk processing should use the same message state machine as individual messages. This keeps reporting, delivery receipts, retries and billing consistent instead of creating a separate campaign-specific lifecycle.
Release and maintenance note
Bulk APIs should expose an explicit item state for validation failure before provider submission. This allows customers to correct bad records without confusing them with messages that were submitted and later failed at the carrier level.