Delivery Reports (DLR)

When messages are submitted to telecom carriers, their status progresses from submitted to delivered or failed.

Message Status Lifecycle

• queued: Message is sitting in your local outbox (can be paused or purged).
• submitted: Message has been handed to the carrier gateway. Units are deducted.
• delivered: Carrier confirmed successful handset delivery.
• failed: Carrier rejected message (e.g., number out of service, network blacklisted).

Querying Message Logs via SDK

// Query the latest 50 delivered messages
const result = await sms.messages.list({
  status: "delivered",
  limit: 50,
  page: 1,
});

for (const log of result.logs!) {
  console.log(
    `Recipient: ${log.recipient}, Segments: ${log.segments}, Delivered At: ${log.deliveredAt}`,
  );
}

Hybrid Reconciliation Architecture

Nyota uses a Hybrid Push + Pull reconciliation architecture to guarantee 100% accurate delivery reports:

1. Real-Time Push: Carrier gateways emit real-time webhook callbacks to POST /v1/webhooks/textsms-dlr.
2. Background Reconciliation Worker: A cron daemon polls the gateway every 10 minutes for any message stuck in the submitted state for more than 5 minutes.