​

Message status transition rules

​

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

• Delivery lifecycle — what each status means and who writes it
• Message status lifecycle reference — per-status semantics and webhook-event map
• 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