Key Takeaways
- A delivery report is the operator’s verdict when the device and the SMSC provide one. “Pending” can stick. Your app must timeout, not wait forever.
- HTTP 200 on enqueue is not delivered. Drive resend policy from DLR or a measured SLA, not from the send call.
- Message history retention is a plan limit: Free 30 days, Starter 90 days, Professional 1 year, Business 2 years, Developer 90 days. Export what compliance needs before it ages out.
- Webhooks are not on Free. Polling GET /messages/{id} still needs backoff so you do not DDoS your own DLR lookup.
- Priced by devices and SMS send volume. You use your own phone and operator SMS credit. Failed sends and retries still use operator credit even when DLR never resolves.
What a DLR can and cannot promise
On a SIM gateway, a delivery report is whatever the Android stack and the operator SMSC bother to tell you. It is not a Twilio-style fabric guarantee. The product walkthrough is the delivery reports guide. This page is the ceiling: pending that never ends, history that ages out, webhooks that are not on Free.
Design OTP as if DLR might never arrive. Then enjoy it when it does. The opposite order creates lockouts.
Carrier silence is a limit
Some destinations never return a final status. Some prepaid SIMs swallow reports. International hops are worse. “We did not get DLR” is not automatically “the app is broken.” Check pairing and airtime first, then treat residual pending as unknown.
Lookup shape (live fields in Developer Center): GET https://app.sms-gateway.app/api/v1/messages/{id}. Do not revive old /dlr/?apikey= samples.
History retention by plan
Published message history: Free 30 days, Starter 90 days, Professional 1 year, Business 2 years, Developer 90 days. If a bank asks for nine months of OTP evidence, Free will not hold it. Export. Retention is not “unused credits rolling over.”
Limit table
| Limit | What you get | Design response |
|---|---|---|
| Finality | Sometimes never | Timeout → unknown |
| Free webhooks | Dash in the comparison table | Do not build webhook-only OTP on Free |
| History | 30 days to 2 years by plan | Export for audit |
| Poll rate | Your courtesy, then our rate limits | Backoff; prefer webhooks |
| Meaning of 200 | Accepted by control plane | Not delivered |
| International | Weaker reports | Do not promise SMSC-grade DLR |
Webhook limits
Paid plans get SMS webhooks. Verify signatures. Retry your consumer idempotently — the control plane may redeliver. A webhook that 500s forever is how you “lose” DLR you actually received.
Live event names: SMS API documentation.
How to design around DLR limits
- Define pending timeout in your app. Example: 10 minutes for OTP, 2 hours for bulk. After that, status = unknown, not delivered.
- Subscribe to webhooks on a paid plan. message.delivered and message.failed. Verify X-SmsGateway-Signature. Idempotent consumers.
- Back off polling. If you GET /messages/{id}, exponential backoff. Do not poll every 200ms per OTP.
- Export before retention lapses. Free’s 30-day history is not an audit archive. Pull what finance or support needs.
- Map failures to action. Permanent vs transient. Permanent leaves the list. Transient may retry with a budget.
- Canary on cold phones. Measure time-to-DLR after reboot. That number sets OTP expiry, not a blog you copied.
OTP and pending forever
If you resend because pending lasted 20 seconds, you will double-text and burn airtime. Align expiry with measured P95 on a cold OTP phone. See OTP and 2FA SMS on Android and the app OTP in-depth guide.
Cost of not knowing
Service pricing is based on device count and total SMS sent through the gateway. You need a working Android phone with a SIM and SMS credit from your mobile operator. Operator message costs are yours—we do not sell carrier SMS balance. Blind retries are a tax you pay the operator. Free is 300 SMS lifetime — easy to spend on DLR experiments. Paid from $19/month. Device and SMS volume pricing.
Next steps
Read delivery reports, wire webhooks, and keep send keys on the server per the API guide.
Related product pages
Jump to the live product docs for this topic—not another long-form article.
- SMS delivery reports (DLR)Delivery status tracking
- SMS API documentationLive endpoint reference
- device and SMS volume pricingPlans and allowances
- Android SMS gateway product guideDefinition, product, and how to buy
