Agent-readable summary

How does TextTree track SMS delivery?

TextTree persists an outbound message before provider execution, runs the external send in background work, stores normalized provider events, and reconciles those events into message status. The message timeline and webhook-attempt records let operators inspect what happened without treating a synchronous API response as final delivery.

Best for

Developers evaluating SMS delivery receipts, debugging, and webhook reliability.

Key points

Durable queue before provider execution; Normalized provider events and explicit message state; Inspectable webhook attempts with controlled replay.

Pricing or setup

Delivery visibility applies to messages that pass eligibility and spend checks; provider acceptance is not a guarantee of handset delivery.

Next step

Read the webhook contract orReview outbound SMS

An SMS API response cannot prove that a handset received a message. At most, it can confirm that the application accepted a request or that a provider accepted an attempt. TextTree therefore treats delivery as a durable sequence of state changes rather than one synchronous result.

Persist before external execution

TextTree validates the request, checks suppressions and spending eligibility, reserves the expected cost, and persists the message before external provider work begins. The provider call runs in an Oban background job instead of the HTTP controller or LiveView.

This boundary gives the application an internal message identifier and a recoverable record before an external side effect occurs. It also keeps a slow provider response from defining the durability of the API request.

Separate queued, provider, and delivery state

A newly accepted message begins in a queued state. Background execution can then record provider acceptance or failure. Later provider events may move the message through additional states such as sent, delivered, or failed.

Those states answer different questions:

• Queued means TextTree accepted durable work.
• Provider acceptance means the upstream provider accepted an attempt.
• Delivered means TextTree received and reconciled a delivery event that reports delivery.
• Failed means the attempt or a later delivery stage reported a failure.

Provider acceptance is not a promise of handset delivery. Networks, destinations, carrier policies, and downstream devices can still affect the outcome.

Normalize provider events

Provider webhooks enter through a signed transport boundary. TextTree verifies the signature, stores a normalized provider event, detects duplicates, and queues reconciliation work. Provider-specific payload handling stays in adapters rather than leaking into message-domain code.

Persisting the event before reconciliation makes retries safer. Duplicate deliveries can be recognized, and a temporary processing failure does not require the provider to remain the sole copy of the event.

Make the timeline inspectable

The message view and API expose status, failure information, cost, and timeline events. That record helps distinguish an invalid request, an eligibility block, a provider failure, and a later delivery failure.

Applications can also receive signed webhook events. TextTree stores webhook delivery attempts with response information so operators can debug a failing consumer. Eligible attempts can be replayed without asking the SMS provider to resend the original message.

What this design does not claim

Durable tracking improves observability and recovery; it does not guarantee delivery speed or universal deliverability. The authoritative result remains the recorded state and the provider events TextTree has actually received.

For implementation details, see the outbound SMS documentation, webhook contract, and API reference.