Message Statuses
Every outbound SMS processed by Emess passes through a deterministic lifecycle from your application, through Emess and the mobile network operators, to the recipient's phone. This guide explains what each status means and when transitions happen.
Overview
When you submit an SMS via the API, Emess validates the request, reserves the necessary tokens from your balance, and immediately hands off the transmission to the appropriate mobile network operator (telecom carrier).
Because cellular network delivery is asynchronous, each message has a live status that reflects its exact state in this pipeline.
Status Reference
A quick summary of the six message statuses in Emess:
| Status | Stage | Meaning | Tokens | Webhook |
|---|---|---|---|---|
| SENDING | In-progress | Request accepted by Emess; transmission to the operator is underway. | Reserved | — |
| SENT | In-progress | The mobile operator acknowledged receipt and is delivering to the handset. | Billed | sms:sent |
| DELIVERED | Terminal (Success) | The mobile operator confirmed delivery to the recipient's phone. | Billed | sms:delivered |
| FAILED | Terminal (Error) | The operator rejected the message or cellular delivery failed. | Refunded | sms:failed |
| EXPIRED | Terminal (Expired) | Message exceeded its TTL validity window before delivery could complete. | Refunded | sms:failed |
| NOT_SENT | Terminal (Cancelled) | Operator transmission timed out without confirmation; automatically cancelled. | Refunded | — |
Status Details
A detailed explanation of each status, its trigger conditions, and associated behavior:
SENDING
When it occurs: Assigned immediately upon calling POST /api/v1/sms/send, POST /api/v1/sms/bulk, or initiating an OTP session via POST /api/v1/verify/send.
What it means: Emess has validated your template and parameters, reserved tokens for the message, and transmitted the dispatch request to the telecommunications operator.
State type: Transient (In-progress). Messages usually remain in this state for only a few seconds while connecting to the operator.
SENT
When it occurs: When the mobile network operator confirms receipt of the SMS payload from Emess.
What it means: The SMS has been successfully handed over to the mobile carrier and broadcast over the cellular network. The recipient's handset may ring or receive it immediately, while final handset delivery confirmation is awaiting the carrier's report.
Associated metadata: The sentAt timestamp is recorded, and an sms:sent webhook event is fired if configured.
DELIVERED
When it occurs: When the mobile carrier issues an asynchronous Delivery Report (DLR) confirming the message reached the destination phone.
What it means: The recipient has received the message on their device. This is the final successful terminal state.
Associated metadata: The deliveredAt timestamp is populated, and an sms:delivered webhook event is dispatched.
FAILED
When it occurs: When the mobile operator rejects the message or reports that the cellular network could not deliver it (for instance: invalid destination number, disconnected subscriber, roaming restriction, or carrier routing failure).
What it means: The message could not reach the recipient. Emess triggers an automatic token refund to your organization balance.
Next steps: You can inspect the failure reason via webhooks (sms:failed) or retry sending the message using POST /api/v1/messages/:id/retry.
EXPIRED
When it occurs: When the current time exceeds the message's sendBefore timestamp (calculated from the template priority tier: 2 minutes for Critical OTPs, 1 hour for Standard, 24 hours for Bulk) before delivery could take place.
What it means: Emess aborted delivery to prevent a time-sensitive code or alert from arriving late when it is no longer valid. Tokens are automatically refunded.
Learn more: Read our detailed Message Expiration Guide for tier TTL details.
NOT_SENT
When it occurs: A safeguard state applied by Emess background reconciliation if a message was left in SENDING beyond the system timeout window without receiving an operator confirmation.
What it means: The transmission timed out. Rather than leaving your tokens locked in an indeterminate state, Emess automatically cancels the message and returns the tokens to your balance.
Next steps: You can safely retry the message via POST /api/v1/messages/:id/retry.