Skip to Content

Message Lifecycle & Routing

Submission acceptance, later delivery, traffic classes, and message statuses.

View Markdown (.md)

A common misconception among developers new to telecommunications is assuming that receiving an HTTP 200 or 202 response means the recipient's mobile phone has buzzed. In reality, SMS operates as an asynchronous, distributed store-and-forward system.


1. Submission Acceptance vs. Handset Delivery

The transmission of an SMS is bifurcated into two distinct phases:

Synchronous Submission vs Asynchronous Delivery

Phase 1: Acceptance

  • The API checks the key, the body, the numbers, and the idempotency key.
  • It returns HTTP 202 Accepted with a messageId. That means SMS Pro has accepted the message. It does not mean the handset has it yet.

Phase 2: Delivery

  • The carrier delivers the message.
  • SMS Pro later posts a signed webhook with the terminal status.

2. Ingestion Pipeline & Architecture

When you call POST /api/v1/public/sms/send, SMS Pro checks the key, validates the body, and returns 202 Accepted. Delivery happens after that response.

Acceptance, then delivery


3. Traffic Classes & Priority Queuing

Set the traffic class on the API key so verification messages are not held behind a large broadcast.

Traffic classUse it for
OTP and 2FAOne-time passwords and MFA.
TransactionalReceipts, booking updates, and account alerts.
MarketingPromotions and announcements.

Keep OTP off the marketing path

A marketing broadcast does not have to delay OTP traffic. Put verification on an OTP key and broadcasts on a marketing key.


4. The Message State Machine

Statuses you can see on a message:

Message statuses

While it is moving

PENDING, QUEUED, IN_PROGRESS, SENT, ENROUTE, and ACCEPTED.

When it is finished

DELIVERED, UNDELIVERED, EXPIRED, FAILED, FAILED_DLQ, REJECTED, BLOCKED, BLOCKED_SPAM, and CANCELLED.

REJECTED_SPAM and UNDELIVERABLE are results of the sandbox magic numbers. Live content filtering is reported as BLOCKED_SPAM.


5. Validity Periods & Message Expiry

When a recipient handset is out of coverage or turned off, the carrier SMSC stores the message and periodically retries delivery.

  • Default Validity Timer (TTL): 24 hours.
  • Retry Schedule: Carriers typically retry with an initial burst (after 1 minute, 5 minutes, 15 minutes), transitioning to hourly polling.
  • Expiry Transition: If the subscriber does not reconnect within the validity window, the SMSC drops the message from its buffer and emits an EXPIRED status receipt.

On this page