Application request
Your application validates a recipient and message, submits a request and records the response. A rejected HTTP request belongs to client or platform request handling, not to the downstream delivery rate.
SMS delivery operations
Turn SMS status updates into operational decisions
A successful API submission confirms that a messaging platform accepted a request; it does not prove that the destination handset received the message. Delivery reports connect the message ID to later network outcomes so operations, product and support teams can distinguish submission success from delivery success.
Report meaning
Separate transport evidence from business outcome
Delivery evidence exists at several layers. Keeping those layers separate prevents an accepted API request from being reported as a delivered SMS, and prevents a delivered SMS from being mistaken for a completed login, payment or customer action.
Platform acceptance
An accepted request normally produces a message identifier that can join later status events to the originating workflow. Acceptance means processing can continue; it is not handset confirmation.
Network disposition
Carrier and route events may indicate progress, delivery, rejection, expiry or another final condition. Exact names and reason codes vary, so retain the raw value while mapping it to an internal category.
Customer outcome
For OTP, the meaningful outcome is successful verification. For notifications, it may be an acknowledged order, resolved support case or completed action. Join delivery evidence to that product event without assuming causation.
Lifecycle model
Normalize statuses without erasing the original receipt
Use a small internal state model for reporting, but keep the raw provider status, reason code and event time for investigation. The names below are operational categories, not a promise that the current API uses these exact labels.
| Operational category | What it means | How to use it |
|---|---|---|
| Request rejected | The send request did not enter message processing. | Track separately from carrier delivery and correct authentication, validation, balance or request-shape problems. |
| Accepted | A message ID exists and processing has begun. | Persist the identifier, recipient context, sender, template, segment count and UTC submission time. |
| In progress | A non-final transport event has been observed. | Measure age and finalization lag; do not count it as delivered or permanently failed. |
| Delivered | A final receipt reports delivery according to the route or network. | Count in transport delivery metrics and then compare with the application outcome. |
| Permanent failure | The current message cannot complete without correcting an underlying condition. | Suppress blind retries, classify the reason and decide whether number, sender, content or route remediation is needed. |
| Potentially retryable failure | A temporary condition may clear, subject to the documented policy. | Apply a bounded retry rule only when the current API documentation and business use case permit it. |
| Expired or unresolved | No delivery confirmation arrived within the relevant lifetime or observation window. | Keep it visible as its own category; do not silently convert unknown outcomes into failures or successes. |
Operational metrics
Measure a complete funnel, not one percentage
A single delivery-rate number can hide request rejection, pending receipts, slow OTP traffic or a poor verification experience. Define the denominator and time window for every chart, then preserve enough dimensions to explain a change.
Submission acceptance
Accepted requests divided by valid send attempts. This exposes client errors, authentication problems, balance conditions and request validation before carrier delivery begins.
Finalization coverage
Messages with a terminal delivery state divided by accepted messages after an appropriate observation window. A fall can indicate callback loss, delayed receipts or route uncertainty.
Transport delivery
Delivered messages divided by messages eligible for a final transport result. Publish the handling of pending and unknown states so comparisons use the same denominator.
Time to final state
Measure percentiles from acceptance to final receipt. OTP traffic needs a much tighter latency view than a non-urgent notification, even when eventual delivery is similar.
Failure composition
Group final failures by normalized reason family while retaining the raw code. A stable overall rate can conceal a growing invalid-number or content-rejection problem.
Business completion
Join message state to verification, login, transaction or customer-service completion. Delivery is an input to the workflow, not the complete product result.
Comparable cohorts
Segment performance before drawing a route conclusion
Country, carrier, sender type, template, encoding, time of day and recipient quality all influence observed results. Compare like with like, state sample size and use the same finalization window.
| Dimension | Question to ask | Common comparison error |
|---|---|---|
| Destination | Which country and network actually received the traffic? | Combining countries with different sender and registration rules. |
| Sender | Was the same approved origin used in both periods? | Comparing an alphanumeric sender with a different number type or approval state. |
| Content | Did template, URL, language, encoding or segment count change? | Attributing a content-filtering change to route quality. |
| Recipient quality | Are new, recycled, malformed or inactive numbers concentrated in one cohort? | Blaming delivery infrastructure for list-quality deterioration. |
| Timing | Are local quiet hours, traffic peaks or carrier maintenance relevant? | Comparing different local time windows using only server time. |
| Sample size | Is volume large enough to distinguish a pattern from noise? | Ranking routes from a handful of messages or one unusual incident. |
Workflow design
Use delivery evidence differently by message purpose
The same final status can require a different product response depending on urgency, consent, duplicate risk and whether another channel exists.
OTP and authentication
Observe submission acceptance, seconds to delivery, resend rate and verification completion. Do not create uncontrolled duplicate codes while an earlier message is still pending; keep one verification transaction as the product truth.
Verification SMS guideTransactional notifications
Associate delivery with the order, payment, security or service event. Define whether a permanent failure triggers an in-app notice, support task, data correction prompt or approved fallback channel.
SMS API overviewBulk and engagement traffic
Aggregate by campaign, destination and consent source while retaining message-level traceability for complaints. Stop repeated sending to invalid or opted-out recipients and investigate sudden reason-code changes.
Bulk SMS planningIncident investigation
Build an evidence packet before escalating
One traceable example with a message ID and UTC timeline is more useful than screenshots without identifiers. Redact secrets and minimize recipient information before sharing evidence.
1. ScopeCountry, carrier, sender and start time
2. TraceRequest, response and message ID
3. TimelineStatus events in UTC order
4. CompareWorking and failing cohorts
5. ClassifyReason family and impact
6. EscalateSanitized evidence and expected result
Include
- Account or project identifier
- Message ID and UTC submission time
- Masked recipient and destination network when known
- Sender type and sanitized template
- HTTP result, raw status and reason code
- First unexpected event and business impact
Do not include
- API keys or authorization headers
- Active OTP values or recovery secrets
- Unnecessary message content
- Full recipient lists
- Payment credentials
- Unrelated customer or account records
Data governance
Keep delivery telemetry useful and proportionate
Delivery records can contain phone numbers, message content, routing references, timestamps and account context. Store only what the operating purpose requires, define access by role and apply a documented retention period.
Minimize
Mask phone numbers in dashboards and tickets, avoid logging full message bodies by default and never record plaintext OTP values. Keep message IDs as the primary diagnostic join key.
Control access
Separate broad aggregate reporting from message-level investigation. Grant detailed access only to roles that need it and review exports, support attachments and long-lived analytics copies.
Retain deliberately
Choose retention by legal, billing, fraud, support and operational need. Apply deletion to derived datasets and exports, not only to the primary message table.
Document definitions
Version status mappings, metric formulas and exclusion rules. When a provider code or internal classification changes, preserve enough history to explain a reporting discontinuity.
Operational readiness
Define ownership before production traffic
A delivery report is only useful when someone owns the status mapping, alert, investigation and customer response. Record the decision boundary between application engineering, messaging operations, support, compliance and commercial teams.
Engineering owner
Owns message-ID persistence, event ingestion, state transitions, replay safety, dashboards and deployment changes.
Messaging owner
Owns sender, route, destination, template and carrier-level analysis, including comparisons against current commercial records.
Support owner
Owns case quality, redaction, customer communication, escalation evidence and confirmation that the business impact is resolved.
FAQ
SMS delivery report questions
Does an HTTP 2xx send response mean the SMS was delivered?
No. It usually means the request was accepted at that API layer. Persist the returned message identifier and wait for the documented status mechanism before classifying a handset or network outcome.
Which delivery status names should my dashboard use?
Use a small internal model such as accepted, in progress, delivered, permanently failed and unresolved, while retaining each raw status and reason. Confirm the exact TextPulse values in the current API reference rather than copying conceptual labels from this page.
Should every failed message be retried?
No. Invalid recipients, prohibited content, sender problems and other permanent conditions should not be retried blindly. Apply bounded retries only to documented temporary conditions and consider duplicate-message risk and business expiry.
Why can delivery rate look healthy while OTP completion falls?
Messages may arrive too late, users may request multiple codes, the application may invalidate the wrong transaction or the verification interface may be confusing. Join transport latency and state to resend, attempt and completion events.
Where are the technical implementation details?
Use the delivery report implementation guide for ingestion architecture, event storage, idempotency, state transitions, reconciliation, testing and monitoring. Use the current authenticated API documentation for exact fields and security requirements.
Make every message traceable
Define the message identity, final-state model, observation window, business outcome and investigation owner before production volume grows.