SMS Delivery Reports, Retries and Duplicate-Message Prevention

Store event and message identities

Give the original machine event a durable ID and keep a separate record for each recipient delivery. Save the provider message identifier when available. This relationship lets the application distinguish a new fault from a retry and investigate whether one event was intentionally sent to several people.

Process status updates defensively

Providers may return asynchronous callbacks after the original request. Authenticate these requests using the provider’s documented method and retain their timestamps. Handle repeated or delayed callbacks without generating a second message. Do not assume every carrier supplies the same delivery detail, and keep unknown outcomes visible in reports.

Retry according to the failure

An invalid number needs correction, while a temporary service error may justify a bounded retry. Use backoff, a maximum age and an attempt limit. After a timeout, the provider may already have accepted the message; reconcile its status where possible before resubmission. Expired alarms should not emerge hours later as apparently current events.

Test recovery and auditability

Test a lost API response, duplicate callback, gateway restart and unavailable handset. Check event IDs and recipient histories after recovery. Define when a failed delivery escalates to another route. Dashboard totals should separate submitted, delivered, failed and unknown messages from acknowledgements, so a delivery report cannot be mistaken for operator action.

FAQ

Technical References

• Twilio: Message Resource and Delivery Status