​

Message status transition rules

​

The status ladder, end to end

1. queued — platform-side hold. The row has not been handed to a sender or provider yet, and the hold is on your side of the handoff, not carrier-side. It stays fully visible: the dashboard Delivery Log filters it with direction=outbound&status=queued, and GET /api/v1/messages?status=queued lists the same rows over the API. Diagnose the hold with the enqueued-empty-states checklist — a filter artifact, a queue with no worker draining it, or a gate you can clear.
2. undelivered — carrier tried, handset not reached. The send escaped the queue, the carrier attempted delivery, and the handset could not take the message. On a cascaded send this terminal state (along with failed and rejected) is exactly what triggers the legitimate fallback hop — a brand-new send on the next chain channel, which re-enters the queue rather than corrupting the failed row (Cascade failover policy). Without a chain, undelivered closes the row. The cause-to-fix decoder is on Message undelivered or failed.
3. failed — retries exhausted, row closed. A dispatch-time or classified carrier failure: the row ran through its retry allowance, the failure fields (metadata.classified_error_code, plus the carrier’s raw error_code/error_message) recorded what stopped it, and the settle rules in this page are what close it rather than leave it retrying forever. Map the class before retrying with the same Message undelivered or failed decoder — a permanent-cause class retries uselessly.
4. The fallback leg. If a cascade chain armed the send, a terminal failure is not the end: the fallback hop is a fresh message under the same message_group_id, fully backed by sender re-resolution, consent re-checks, and its own queue entry. Distinguish that designed reroute from an undesigned stall — the ladder (queue visibility → cascade fallback → exhaustion) tells you which of the two you are looking at.

​

Order-preserving vs. recoverable transitions

• Allowed (order-preserving). The row moves forward — queued → sending → sent → delivered → read, the scheduled lifecycle scheduled → queued, and the carrier-rejection fan-out sent → failed | rejected | undelivered. These apply and fire the matching webhook event.
• Recoverable (allowed backward corrections). A small set of backward moves is explicitly legal because carriers contradict themselves: delivered → undelivered and delivered → failed are the carrier-correction allowance (some carriers — notably Indian and Brazilian routes — emit DELIVERED, then re-emit UNDELIV minutes later when a longer-tail failure surfaces). The platform accepts the correction and lets the later truth win. submitted_no_receipt → delivered | read | failed | undelivered | rejected is the same idea: the no-DLR sentinel is provisional, so a genuine receipt that lands afterward still overwrites it.
• Forbidden (ignored). Any transition the DAG does not list is dropped without touching the row. Self-loops never apply — a duplicate delivered for a row already at delivered is filtered as a duplicate, not applied as a no-op write. Regressions like delivered → sent or delivered → queued (stale duplicate receipts arriving after the row advanced) are rejected the same way.

1. Never move a row backward except through the named recoverable transitions. A webhook that reports sent for a message you already recorded as delivered is a duplicate, not new information.
2. Never resurrect a row off a floor. deleted and cancelled have no path back to a carrier-driven state — floor rule number two below.
3. Dedupe before you merge, not after. The same event redelivered (at-least-once delivery — see webhook delivery semantics) must not re-apply a transition you already recorded.

​

Precedence when updates compete

• Pending vs. terminal. submitted_no_receipt sits between sent and delivered on purpose: the no-DLR sentinel parks the row at “accepted, outcome unknown,” and it reports is_terminal: false on webhooks precisely because a later genuine delivered, read, or failure still supersedes it. If your integration freezes on the first terminal-looking event, you will mis-record these rows — merge only when the incoming event outranks what you hold, and treat submitted_no_receipt as pending, never as final.
• Higher weight wins, later events included. A delivered that arrives after you recorded failed (weight 4 over 3) or submitted_no_receipt (4 over 2.5) is forward progression and must overwrite — that is how slow carrier receipts correct the record. The reverse (failed over a recorded delivered) is not forward by weight; it applies only because it is one of the named carrier-correction transitions. Without the transition-table check beside the weight check, a weight-only merge lets any stale high-weight duplicate rewrite history and any stale low-weight duplicate regress it — you need both.
• Two absolute floors. deleted and cancelled outrank everything and accept nothing except the operator-driven → deleted (for cancelled). Once a row is on either floor, no provider callback — however fresh or high-weight — moves it. If you expose cancel or delete in your own UI, close the row locally at that moment and drop any later events for that message id.

​

Late terminal events

​

Compute from failure fields, not from status alone

• metadata.classified_error_code — the normalized, machine-readable failure category, stable across providers. Branch on this to drive policy: route permanent-cause classes (invalid recipient, opt-out, content blocks) to suppression or recipient-cleanup flows, and let only transient-cause classes retry. Provider-specific codes belong in logs, not in branching logic.
• error_code / error_message — the carrier’s own raw code and human-readable text, mirrored from the provider payload and present only when the provider supplied a reason. Use them for support tickets and carrier escalations, where the original wording matters; never as your programmatic switch.

​

Worked examples

{"type":"message.created","data":{"message_id":"msg_9f2","status":"queued"}}
{"type":"message.sent","data":{"message_id":"msg_9f2","status":"sent","state_class":"intermediate","is_terminal":false}}
{"type":"message.failed","data":{"message_id":"msg_9f2","status":"submitted_no_receipt","state_class":"intermediate","is_terminal":false}}
{"type":"message.delivered","data":{"message_id":"msg_9f2","status":"delivered","state_class":"terminal","is_terminal":true}}

const WEIGHT = {
  queued: 0, sending: 1, sent: 2, submitted_no_receipt: 2.5,
  failed: 3, rejected: 3, undelivered: 3, expired: 3,
  delivered: 4, read: 5, deleted: 99, cancelled: 99,
};

// The only backward moves the platform accepts.
const RECOVERABLE = new Set([
  "delivered>undelivered", "delivered>failed",
  "submitted_no_receipt>delivered", "submitted_no_receipt>read",
  "submitted_no_receipt>failed", "submitted_no_receipt>undelivered",
  "submitted_no_receipt>rejected",
]);

const seen = new Set(); // event ids — at-least-once delivery
const rows = new Map(); // message_id -> current status

function apply(evt) {
  if (seen.has(evt.id)) return;            // dedupe before merging
  seen.add(evt.id);

  const { message_id, status } = evt.data;
  const current = rows.get(message_id);
  if (!current) { rows.set(message_id, status); return; }
  if (current === "deleted" || current === "cancelled") return; // floors
  if (RECOVERABLE.has(`${current}>${status}`)) {
    rows.set(message_id, status);          // carrier correction
    return;
  }
  const newW = WEIGHT[status];
  const curW = WEIGHT[current];
  if (newW !== undefined && (curW === undefined || newW > curW)) {
    rows.set(message_id, status);          // forward progression
  }
  // everything else — regressions, self-loops, unknown statuses — ignored
}

​

See also

• The scheduled-sending model — the unified schedule-park-gate-fire-bill anchor these transitions fit into
• Delivery lifecycle — what each status means and who writes it
• Message status lifecycle reference — per-status semantics and webhook-event map
• Message status map — the four owners in one index, with a worked reconciliation walkthrough
• Webhook event types — payload shapes for every message event
• Webhook delivery semantics — at-least-once delivery, retries, and dedupe windows
• Operational sentinels — the settled-but-non-outcome statuses beside this DAG