A DLR (Delivery Receipt) is the receipt a carrier returns stating the final outcome of an SMS. It is asynchronous — arriving seconds or minutes after sending — and it is what separates a message accepted for delivery from one actually delivered to the handset.
A DLR (Delivery Receipt) is the receipt a carrier returns stating the final outcome of an SMS. It is asynchronous — arriving seconds or minutes after sending — and it is what separates a message accepted for delivery from one actually delivered to the handset.
A message moves through states before reaching an outcome. Queued: accepted by the platform, not yet dispatched. Scheduled: will go out on the set date. Sent: accepted by the carrier, awaiting the receipt — this is where most integrations go wrong, because "sent" is not yet "delivered". Delivered: confirmed on the handset, and the only successful outcome.
Between carrier acceptance and arrival on the handset there may be a powered-off phone, no coverage, a non-existent number, a block, or the retry window expiring. If your flow depends on confirmation — an OTP, say — treat only "Delivered" as success and listen to the webhook instead of assuming delivery from the send call response.
Send Error and Delivery Error: the carrier rejected the dispatch or could not complete it. Invalid: the number does not exist or is malformed. Blocked: the destination refuses that message type. Not Delivered and Expired: the carrier tried and gave up inside the window. Blacklist: the recipient opted out and the platform stopped the message before spending credit. No Credit: insufficient balance at dispatch. Recency and Monthly Recency: the number received messages too recently and hit a frequency block. Cancelled: the send failed and the credit was already returned to the balance.
Configure a webhook URL on the account and you receive the sms.status event on every state change, plus sms.reply when the recipient answers. Each request is signed with HMAC-SHA256 in the X-SMSGo-Signature header, so verify the signature before trusting the body. You can also poll GET /v1/sms/{id}/numbers, which returns per-number status, paginated.
Usually seconds. But the DLR is asynchronous and depends on the carrier: a powered-off or out-of-coverage handset can delay it by minutes, and the carrier keeps retrying until the window expires.
A provider failure triggers a refund, and the send ends in the Cancelled status — which is precisely the marker that the credit went back to the balance. A message stopped by the blacklist is never dispatched.
The Invalid status means a non-existent or malformed number. Clean your list from those returns: resending to an invalid number only repeats the cost.
No, and you should not. Configure the webhook and receive the change when it happens. The GET endpoint is for reconciliation, not real-time tracking.
No credit card. No monthly fee. Credits never expire.
Create free account