All message states, transitions, drop reasons, and the executor pipeline from queue to delivery
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.
The message executor processes queued messages through a 10-step pipeline.
Poll queue — Coordinator queries QueuedTextMessage for unclaimed messages older than 10 seconds, sorted by send time, in batches of up to 50,000
Group by list — Messages are grouped by sending_list for per-list processing and rate limiting
Validate list — Check that the sending list exists and is in active status; drop messages for inactive or missing lists
Billing preflight — Verify the account has valid billing (payment method, no payment failures, free tier limit not exceeded); back off retryable messages 5 minutes or drop after 60-minute TTL
Claim messages — Atomically claim a batch of messages using a unique claim token to prevent duplicate processing across VMs
Filter stale — Discard messages queued longer than 30 minutes (STALE_THRESHOLD_MINUTES)
Filter blocked content — Run message body through the blocked words checker; drop matches with BLOCKED_CONTENT status
Filter blocked contacts — Check recipients against ListContactBlock (unsubscribed/blocked contacts); drop matches with CONTACT_BLOCKED status
Send via provider — Submit messages to the SMS provider (Infobip, Twilio, CM) in batches with per-list rate limiting (default 17,000 messages/min)
Record results — Insert RawMessage records, delete from queue, update MessageSent status, and track billing (segments sent per account)
