Process SMS delivery receipts

Receive delivery status updates for an outbound SMS and apply them safely in your application.

Before you start

Create a publicly reachable HTTPS endpoint that accepts JSON POST requests. Do not put credentials or other secrets in its URL.

When you send an SMS, include the endpoint as dlrUrl and store the returned result.sid:

{
  "to": "+447700900001",
  "from": "+447700900000",
  "content": "Example message",
  "dlrUrl": "https://example.com/cloudnumbering/dlr"
}

Accept a delivery receipt

cloudnumbering sends a JSON POST request with this shape:

{
  "timestamp": "2026-07-09T12:34:56Z",
  "status": "delivered",
  "sid": "00000000-0000-4000-8000-000000000001"
}

Field	Type	Meaning
`timestamp`	string	UTC status timestamp in RFC 3339 format.
`status`	string	Delivery status reported for the message.
`sid`	string	Message identifier returned as `result.sid` by the send request.

Record the update durably, then return a 2xx response. The status code you return is for your own infrastructure's benefit: cloudnumbering does not currently act on it, and a non-2xx response does not trigger redelivery.

Handle status values

The current outbound route requests these final delivery reports:

Status	Meaning
`delivered`	The delivery network reports the message as delivered.
`rejected`	Delivery has been rejected.

cloudnumbering does not promise intermediate queued, submitted, buffered, or failed callbacks on the current outbound path. Do not wait for those statuses before processing a final report.

Design the receiver to accept repeated updates. Store the events you receive and deduplicate an exact repeated sid, timestamp, and status combination. Two different updates can have the same timestamp, so do not invent an order between them.

A successful response from POST /v1.1/sms is only acceptance for sending. Treat delivered as the delivery outcome when your workflow requires handset delivery.

Test your receiver

Send a fake receipt to your development endpoint:

curl --silent --show-error \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "timestamp": "2026-07-09T12:34:56Z",
    "status": "delivered",
    "sid": "00000000-0000-4000-8000-000000000001"
  }' \
  'https://example.com/cloudnumbering/dlr'

Replace example.com with a non-production endpoint that you control.

Secure the receiver

cloudnumbering does not sign delivery-receipt requests. Treat the body as untrusted input and do not use a callback by itself to authorise a sensitive action.

No callback retry schedule or delivery guarantee is published. If your endpoint is unavailable or rejects a callback, do not assume that cloudnumbering will send that update again. Monitor the receiver and respond quickly after storing each update.

Troubleshooting

No receipt arrives

Confirm that the original send request included dlrUrl and that the endpoint is publicly reachable over HTTPS. A receipt is available only after cloudnumbering receives a status update from the delivery network.

The receipt does not match a message

Match the callback's sid to result.sid from the send response. Do not try to match on to, from, or message content; those fields are not included in the callback.

The same receipt arrives more than once

Keep one copy of an exact repeated sid, timestamp, and status combination. Continue to return 2xx after safely recording or ignoring the repeated update.