Message Lifecycle

Every message in Trackly SMS passes through a series of states from creation to final delivery (or failure). Understanding these states helps you troubleshoot delivery issues and build reliable integrations.

State Diagram

Message States

State	Terminal?	Description
`queued`	No	Message is in the send queue, waiting to be picked up for sending
`sent`	No	Trackly submitted the message to the SMS provider
`delivered`	Yes	Provider confirmed delivery to the recipient’s handset
`undelivered`	Yes	Provider attempted delivery but the carrier reported failure
`failed`	Yes	Hard failure — provider rejected the message or a system error occurred
`dropped`	Yes	Message was removed from the queue before sending (see drop reasons below)
`orphaned`	Yes	Message had no valid sending list — removed from queue and recorded to dead-letter

Drop Reasons

When a message is dropped, the status_detail field contains the reason.

Reason	Description
`stale`	Message sat in the queue longer than 30 minutes and was discarded
`blocked_content`	Message body matched a prohibited content filter (crypto, phishing, bank names)
`contact_blocked`	Recipient is unsubscribed or blocked on the sending list
`inactive_list`	The sending list is no longer in `active` status
`billing_expired`	Account billing is invalid and the message exceeded the 60-minute retry window
`webhook_not_configured`	BYOC (bring-your-own-carrier) list requires a webhook endpoint but none is configured
`orphan`	Message had no `sending_list` reference — likely a data integrity issue

Webhook Events

Provider delivery reports and inbound activity update your account asynchronously.

Event	Fires when
`message.delivered`	The carrier confirms delivery to the recipient’s handset
`message.failed`	The provider rejects the message, or the carrier reports a delivery failure (including undelivered messages)
`message.reply`	The recipient replies to a message
`contact.opted_out`	The recipient opts out

The sent state is set immediately when the provider accepts the message. Final delivery status arrives via webhook, typically within seconds.

Timing

Threshold	Value	Description
Queue pickup delay	10 seconds	Messages must be at least 10 seconds old before Trackly picks them up for sending
Stale message cutoff	30 minutes	Messages in the queue longer than this are dropped as stale
Billing retry backoff	5 minutes	Messages for accounts with billing issues are retried after 5 minutes
Billing block TTL	60 minutes	After 60 minutes of billing failure, messages are permanently dropped

Getting Started

AI Agents & MCP

Guides

Account & Team

Integrations

Resources

State Diagram

Message States

Drop Reasons

Webhook Events

Timing

Next Steps

Data Model

Compliance

​State Diagram

​Message States

​Drop Reasons

​Webhook Events

​Timing

​Next Steps

Data Model

Compliance

State Diagram

Message States

Drop Reasons

Webhook Events

Timing

Next Steps