Receiving DLRs

A DLR (Delivery Receipt) is how carriers tell you what happened to a message after it left Instasent. We aggregate the updates from every hop in the chain and forward each transition to a webhook you control. If two-way messaging is enabled on your account, inbound messages arrive on the same endpoint.

Configuring the webhook

Webhooks are configured per api_sms token in the dashboard. Point it at a public HTTPS endpoint that returns 2xx quickly — we consider any non-2xx a failure and retry with exponential backoff.

Payload shape

Every call is a POST with a JSON body:

{
  "id": "sms-id",
  "clientId": "custom-id",
  "status": "delivered",
  "code": 0,
  "eventAt": "2026-04-21T10:15:00Z"
}

Field	Description
`id`	The Instasent message id. Matches the `id` returned when the SMS was created.
`clientId`	The `clientId` you supplied when creating the message, if any — useful for correlation against your own records.
`status`	Machine-readable status. See the list below.
`code`	Numeric code that narrows down the reason for `error`/`failed` statuses.
`eventAt`	ISO-8601 timestamp of the event.

When two-way is enabled on the account, the payload also carries a message field with the inbound text.

Status list

Status	Meaning
`sent`	Message was sent to the device.
`accepted`	Message was accepted by the carrier.
`buffered`	Message is buffered by the carrier, waiting to be delivered.
`delivered`	Message was delivered to the handset.
`error`	Message could not be sent to the device.
`failed`	Message could not be delivered.
`expired`	Message expired before delivery was possible.
`canceled`	Message was canceled.
`rejected`	Message was rejected by the carrier.
`unknown`	An unknown error occurred.
`stop`	An opt-out inbound message was received from the handset.
`inbound`	An inbound message was received (two-way only).

Code list

Codes narrow down the reason for non-delivery. 0 is the happy path; everything else describes a specific failure class.

Code	Meaning
`0`	OK
`1`	Unknown
`2`	Absent temporarily
`3`	Absent permanently
`4`	Blocked subscriber
`5`	Portability error
`6`	Antispam reject
`7`	Line busy
`8`	Network error
`9`	Illegal number
`10`	Invalid message
`11`	Unroutable
`12`	Unreachable
`13`	Age restriction
`14`	Blocked carrier
`15`	Insufficient funds
`16`	Flooded
`99`	Unknown error
`100`	Reject

Idempotency

The same message may generate multiple DLRs — typically sent → buffered → delivered. Use id as the primary key and treat each DLR as a status transition, not as the final state.

What's next

Errors — for failures that happen before the message even leaves the API.
API Reference — retrieve the current status of a message on demand.