Message Lifecycle

​

State Diagram

​

Message States

​

Drop Reasons

​

Executor Pipeline

1. Poll queue — Coordinator queries QueuedTextMessage for unclaimed messages older than 10 seconds, sorted by send time, in batches of up to 50,000
2. Group by list — Messages are grouped by sending_list for per-list processing and rate limiting
3. Validate list — Check that the sending list exists and is in active status; drop messages for inactive or missing lists
4. 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
5. Claim messages — Atomically claim a batch of messages using a unique claim token to prevent duplicate processing across VMs
6. Filter stale — Discard messages queued longer than 30 minutes (STALE_THRESHOLD_MINUTES)
7. Filter blocked content — Run message body through the blocked words checker; drop matches with BLOCKED_CONTENT status
8. Filter blocked contacts — Check recipients against ListContactBlock (unsubscribed/blocked contacts); drop matches with CONTACT_BLOCKED status
9. Send via provider — Submit messages to the list’s SMS provider in batches with per-list rate limiting (default 17,000 messages/min)
10. Record results — Insert RawMessage records, delete from queue, update MessageSent status, and track billing (segments sent per account)

​

Webhook Events

​

Timing

​

Next Steps