123eworld Knowledge Hub → SMS API → Page 306
SMS API Delivery Reports: Designing Accurate Delivery Analytics
A practical developer reference designed to solve real implementation and production problems around sms api delivery reports: designing accurate delivery analytics.
Why delivery reports matter
A send API tells an application that a request was accepted; delivery reporting tells the application what happened later. A useful delivery-reporting system turns asynchronous provider evidence into understandable business information. This guide explains how to design reporting that remains accurate when messages are retried, routed through different providers or updated after delayed delivery receipts.
Logical message versus provider attempt
One logical SMS can have multiple provider attempts. Reports should distinguish the customer-facing message ID from internal attempt IDs. Otherwise a failover can appear as two separate customer messages even though the platform considers it one logical notification.
Report dimensions
Useful dimensions include tenant, application, sender, destination country, message status, provider, route, encoding, segment count, created time, submission time and delivery time. Not every dimension needs to be exposed publicly, but the internal model should support operational analysis.
Current status versus event history
A current-status table is efficient for dashboards, while an immutable event history is essential for reconciliation. Do not make one table serve both purposes if doing so compromises either query performance or historical accuracy.
Aggregation
Daily and monthly delivery rates should be calculated from well-defined populations. Define whether cancelled, expired, undeliverable and pending messages are included in the denominator. Otherwise two reports can show different delivery percentages for the same traffic.
Late receipts
Delivery receipts can arrive long after submission. The reporting system should update the logical state when valid late evidence arrives while preserving the original event timestamp and provider evidence.
Provider normalization
Different providers use different receipt codes. Normalize them into a stable status taxonomy and retain the raw provider code for diagnostics.
Data freshness
Dashboards should communicate whether data is real-time, near-real-time or delayed. A delivery rate based on incomplete pending traffic can change as receipts arrive.
Privacy
Phone numbers and message content are sensitive. Reports should minimize exposed data, use tenant-scoped authorization and provide masked views where full values are unnecessary.
Exports
Large report exports should be asynchronous. Generate them from an analytical or read-optimized data path so reporting cannot slow message processing.
Reconciliation
Compare provider submission records, delivery receipts and customer-facing states regularly. Reconciliation detects missing callbacks, duplicate events and mapping errors.
Developer checklist
Define message and attempt IDs, canonical statuses, event timestamps, aggregation rules, retention, access control, export behaviour and reconciliation procedures.
Practical implementation guidance
Design the public API around a stable logical message ID and keep provider-specific complexity behind internal adapters. Every asynchronous step should be durable, observable and safe to retry.
Security and privacy
Treat phone numbers, message content, credentials and delivery evidence as sensitive. Apply tenant authorization before data access and avoid unnecessary values in logs, traces and reports.
Developer-first principle
A useful reference page should tell developers not only what a feature is, but how to implement it safely, how to troubleshoot it and what failure cases to expect.
Related 123eworld guides
Explore the 123eworld SMS & WhatsApp Knowledge Hub for related API, routing, reliability and developer guides.
Delivery funnel
Build reporting from a clearly defined funnel: created, accepted, queued, submitted, delivered and terminal failure. Each stage should have a precise population and timestamp. This lets an operations team answer questions such as 'Were messages accepted by the API?' separately from 'Did the provider report delivery?' Mixing these populations is a common cause of misleading dashboards.
Delivery-rate formula
A delivery percentage should specify its denominator. For example, delivered divided by messages with a terminal delivery outcome is different from delivered divided by all messages created during the same hour. During a recent campaign, a large pending population can make the second calculation appear artificially low. Publish the formula with every KPI.
Segment-aware analytics
One logical message can contain multiple physical SMS segments. Operational volume reports should therefore show both logical message count and segment count. Cost analysis often depends on segments, while application-level delivery analysis normally depends on logical messages.
Time windows
Use event time for delivery-latency analysis and creation time for campaign-volume analysis. If a receipt arrives late, it should be counted according to the documented reporting model rather than silently moving historical traffic into the current hour.
Provider comparison
Compare providers using equivalent populations. A provider that receives a different mix of countries, message lengths or traffic priorities cannot be judged fairly from raw delivery percentage alone. Include route and destination dimensions in deeper analysis.
Reconciliation dashboard
A useful dashboard can show messages with no provider outcome after the expected window, duplicate receipts, unknown provider codes and state conflicts. These are data-quality indicators as much as delivery metrics.
Export architecture
Generate large reports asynchronously and store the report definition with the export job. The user should be able to see filters, date range, creation time, expiry and completion status. Export access must be tenant-scoped.
Historical corrections
If a provider later sends a delayed receipt, the analytical system may need to revise historical metrics. Preserve raw events so the correction is explainable. Avoid overwriting historical evidence.
Data quality tests
Automate checks such as delivered count not exceeding submitted count unless the documented model permits it, no cross-tenant records, and no impossible timestamp sequences.
Executive versus developer reports
Executives need trend and KPI summaries. Developers need message IDs, status reasons, timestamps and provider diagnostics. One report should not try to satisfy both audiences with excessive detail.
Delivery-latency distribution
Do not rely only on average delivery time. Use percentiles such as p50, p95 and p99 to reveal slow-tail behaviour. A route can have an excellent average while a small but important population waits many minutes or hours. Segment latency by destination and provider before changing routing policy.
Reconciliation jobs
Run scheduled reconciliation against provider reports where available. Compare submitted attempts with receipts and identify records that have remained pending beyond the expected window. Reconciliation should create investigation evidence rather than arbitrarily marking everything as failed.
Report versioning
When a KPI formula changes, record the report definition or version. Historical dashboards can otherwise appear to change simply because the calculation changed. Enterprise customers need stable definitions for operational and commercial reconciliation.
Data pipeline isolation
Move heavy aggregation work away from the transactional database when volume requires it. A reporting query that scans millions of message records should not compete with inserts required for live delivery processing.
Actionable analytics
Every major delivery metric should have an associated operational question. If failure rate rises, the dashboard should allow drill-down by provider, country, sender and reason. Analytics becomes useful when it leads to a specific investigation.
Drill-down workflow
Start at the overall delivery KPI, identify the largest deviation, then drill into provider, destination, sender and failure reason. Compare the affected population with a healthy baseline. This prevents teams from changing routing simply because a headline percentage moved.
Customer-facing reports
Customer reports should distinguish current pending traffic from terminal outcomes. Include report generation time and filters so exported numbers can be reconciled later. Where data can change after generation, state that clearly.
Delivery SLA analytics
If customers have contractual delivery objectives, calculate compliance from documented message classes and eligible destinations. Exclude known test traffic and invalid requests according to the contract rather than changing the denominator informally.
Reprocessing protection
If an analytical event is replayed, aggregation jobs should be idempotent. Use event IDs or partition checkpoints so rebuilding a reporting window does not double-count delivery receipts.
Reference implementation
A strong architecture is operational state store → immutable event stream → normalized analytics events → aggregate tables → dashboards and exports. This keeps real-time message processing independent from heavy reporting.
Report reconciliation checklist
Before publishing a delivery report, verify that all records belong to the requested tenant and time range, that duplicate receipts have been removed from event counts, that terminal-state definitions are applied consistently and that late receipts follow the documented reporting rule. For high-value reports, record the data snapshot or query version used to generate the result.
Practical outcome
A delivery report becomes a reliable reference when an engineer can take one message ID, follow its attempt history and receipt events, and reproduce the status shown in the dashboard. That reproducibility should be a design goal from the beginning.