​

Delivery lifecycle

​

DLR: two planes

• The carrier-leg plane. A receipt crosses from the carrier into Orbit — a submission acknowledgement on the wire (an SMPP submit ACK, a provider message id, a Meta hand-off id), or a genuine carrier delivery report. This plane answers “what did the carrier say about my message.”
• The platform-internal plane. Orbit’s own send-side receipt path: for traffic Orbit terminated itself, or for an SMPP client receipt in general, Orbit encodes the resolved canonical state back out — onto your SMPP bind as a deliver_sm, or to your endpoint as a webhook POST. This plane answers “what does Orbit report to me, and in what encoded form.”

​

The happy path

• The no-DLR scheduler. When a carrier never returns a delivery receipt, a scheduler promotes sent to submitted_no_receipt after a per-channel grace window — see Carrier-confirmed vs. wire-intermediate.
• You (the operator). Cancelling a still-unsent scheduled message moves it to cancelled, a terminal state no provider call and no DLR ever touches. Sandbox sends resolve to test_sent, a terminal state reached before any provider dispatch. Deleting a row moves any terminal state to deleted, after which nothing can touch it.

​

Which plane advances which edge

​

Carrier-confirmed vs. wire-intermediate

• delivered and read are carrier-confirmed. A real DLR arrived; the carrier itself asserted the outcome.
• submitted_no_receipt is wire-intermediate. It means “the submission was accepted, and no receipt came back inside the grace window.” It is tagged intermediate (state_class: "intermediate", is_terminal: false) on every webhook, because a genuine delivered, read, or failure DLR can still land afterward and overwrite it.

​

Debugging a stuck message

• submitted_no_receipt renders on the timeline as its own event when the grace-window scheduler closes the no-receipt window.
• submitted_no_receipt rows stall because of your subscriber, not the carrier, when the trace shows webhook_fanout hops with a failing http_code.

​

Per-channel caveats

• Meta DM channels (Instagram, Messenger). Meta’s Send API never emits delivery receipts. The send leaves Orbit as sent, is flagged no_dlr_channel on the message metadata, and flips to submitted_no_receipt after 5 minutes. For an opted-in recipient, Meta guarantees delivery on accept — so on these channels submitted_no_receipt behaves like a functional delivery signal, and the message metadata carries no_dlr_channel: true so you can tell that case apart.
• SMPP-backed channels (SMS, MMS, voice, fax, RCS). The grace window is 30 minutes. Here submitted_no_receipt is genuinely ambiguous: the handset may have received the message with no receipt reported, the carrier may never send receipts on that route, or the receipt may have been dropped in transit. Track this rate separately from your delivered rate — a rising submitted_no_receipt share on one destination points at a non-cooperating route or a broken receipt path, and is worth investigating either way.
• Email. Adds one failure outcome other channels lack: bounced, when the receiving mail server rejects the message. Bounced counts against your terminal-failure rate like failed, but it is a distinct status so you can separate recipient-side rejects from provider-side ones.
• Operator cancel. cancelled is reachable only by you — via POST /messages/:id/cancel on an unsent message. No carrier ever writes it, and as a consequence it fires no webhook event; nothing notifies a subscriber of a cancel. Poll GET /messages/:id if you expose cancel in your own UI and need to observe it.
• Sandbox / test mode. Test sends resolve to test_sent before any provider dispatch. They fire message.sent with status: "test_sent" and metadata.test_mode: true, so a subscriber must branch on metadata.test_mode to keep sandbox traffic out of production handling.

​

What to branch on

• status — the message’s current state. This is the primary branch point. Handle the full set: besides the happy-path and common failure states, do not forget cancelled, test_sent, submitted_no_receipt, and bounced.
• metadata.classified_error_code — present on terminal failures; the normalized, machine-readable failure category. Combine it with raw error_code / error_message on message.failed webhooks when you want the carrier’s own wording.
• metadata.no_dlr_channel — present on Meta DM rows; tells you a submitted_no_receipt is the delivery-guaranteed Meta case, not the ambiguous SMPP case.
• state_class / is_terminal — on lifecycle webhooks. is_terminal: true (equivalently state_class: "terminal") means the outcome is final; submitted_no_receipt reports is_terminal: false specifically so you do not close the book on it.

​

Common pitfalls

1. Treating message.created as acceptance. message.created fires the moment the row is queued, before any provider call. A synchronous rejection (a 4xx on the send, or an immediate rejected/failed) still leaves that event delivered. Pair it with message.sent before concluding the message went out.
2. Assuming delivered is unchangeable. Carriers on some routes emit a delivery receipt, then a correction minutes later — some Indian and Brazilian carriers do this. Orbit honors it: the row can move delivered → undelivered or delivered → failed. If you mirror statuses into your own datastore, apply updates idempotently by message id rather than ignoring transitions for a message you already marked delivered.
3. Waiting for a webhook on cancelled. It will never come — cancel originates from your own API call, not a carrier callback, so the platform emits no event for it. The row simply sits at cancelled until you delete it.
4. Dropping submitted_no_receipt into the failed bucket. It arrives on the message.failed event type for transport reasons (there is no dedicated event), but its payload status is submitted_no_receipt with is_terminal: false. Branch on data.status, not the event type, and keep it out of your hard-failure metrics.
5. Expecting one terminal event per message. A message can emit message.failed with status: "submitted_no_receipt" and later message.delivered, when a slow carrier receipt finally lands inside the late-arrival window. Dedupe and reconcile by message_id, letting the later event supersede.

​

Worked example: polling a message’s current state

curl "https://api.orbit.devotel.io/api/v1/messages/msg_9e8d7c6b5a4f3021e5d6c7b8a1b2c3d4" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "msg_9e8d7c6b5a4f3021e5d6c7b8a1b2c3d4",
    "channel": "sms",
    "to": "+14155552671",
    "from": "+12125550100",
    "status": "delivered",
    "created_at": "2026-09-20T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_msg_get",
    "timestamp": "2026-09-20T12:00:04.000Z"
  }
}