> For the complete documentation index, see [llms.txt](https://postman-v2.guides.gov.sg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://postman-v2.guides.gov.sg/technical-users-api/api-reference/message-statuses.md).
# Message statuses
The `latestStatus` field on a message object indicates where the message is in the delivery lifecycle. Messages progress through the following statuses:
```
created → enqueued → sending → sent → sent_to_telco → success
↘ ↘
failure failure
```
| Status | Terminal | Description |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created` | No | Postman is aware of your request and has created the necessary records. However, it has not yet made the request to the relevant messaging service provider to have the message sent. |
| `enqueued` | No | Your message is now in the queue and in the process of getting sent to the relevant messaging service provider. |
| `sending` | No | Your message has been taken out of the queue and is in the process of getting sent to the relevant messaging service provider. |
| `sent` | No | Postman has made the request to the relevant messaging service provider to have the message sent. However, it has not yet received a notification from the provider on the request status. |
| `sent_to_telco` | No\* | The relevant messaging service provider has sent an update to Postman saying that the message has been sent to the recipient's telco. The message may or may not have been delivered to the recipient's phone (e.g. the phone could be off or in airplane mode). |
| `success` | Yes | The relevant messaging service provider has confirmed that the message has been delivered by the telco to the recipient. |
| `failure` | Yes | The message failed to send due to an error in Postman or from the messaging service. See the `error` object in the message's `attempts` array for details, or refer to [Message Delivery Errors](https://postman-v2.guides.gov.sg/general-notes-for-api-users/message-delivery-errors). |
\*If `latestStatus` remains `sent_to_telco` beyond 48 hours, it is unlikely that a further status update will be received from the telco. This is a telco limitation and is expected behaviour. For foreign numbers, `sent_to_telco` is the terminal status. You may compose a new message if needed, though the recipient may receive the same message twice.
***
**Checking Message Status**
* The response from the Single Send or Batch Send endpoint confirms the message was created, but does not indicate delivery status.
* You must poll the Retrieve Message or Retrieve Batch endpoint to get the `latestStatus`.
* Webhooks for delivery status updates are not currently supported.
* Telcos do not provide read statuses.
***
**Billing by Status**
Whether a message is charged depends on its final status. Messages sent to invalid phone numbers or with invalid content are still charged, as the attempt still consumes network resources.
| Status | Charged |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `success` | Yes |
| `recipient_invalid` | Yes |
| `recipient_unavailable` | Yes |
| `content_invalid` | Yes |
| `routing_error` | Yes |
| `message_expired` | Yes |
| `delivery_unknown_error` | No |
| `server_unknown_error` | No |
| `sent_to_telco` | Yes (only for foreign numbers, as this is the terminal status for foreign numbers) |
Verify your recipients' numbers and message content before sending to avoid unnecessary charges.
***
**Delivery Error Details**
When a message has `latestStatus` of `failure`, the `attempts` array in the Retrieve Message response will contain an `error` object with:
* `type`: the error type (`delivery_error` or `server_error`)
* `code`: the specific error code
| Error Type | Error Code | Retryable | Description |
| ---------------- | ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `delivery_error` | `recipient_invalid` | No | The recipient's mobile number is not recognised by the network operator. Caused by deactivated numbers, incorrect format, or numbers not released by the regulator. |
| `delivery_error` | `recipient_unavailable` | Yes | The recipient's device is not currently connected to the mobile network. Caused by coverage gaps, SIM issues, or device problems. |
| `delivery_error` | `content_invalid` | No | There is an issue with the message content, such as prohibited content or incorrect encoding. |
| `delivery_error` | `routing_error` | Maybe | There is a failure in routing the message to the recipient's mobile network. Caused by operator routing infrastructure issues or unapproved numbers. |
| `delivery_error` | `message_expired` | Maybe | The message was not delivered within the 48-hour timeframe set by SMS aggregators. May be caused by network delays or temporary aggregator infrastructure issues. |
| `delivery_error` | `delivery_unknown_error` | Maybe | The exact cause of failure is not identifiable. May relate to recipient device configuration (e.g. third-party apps, expired prepaid card) or international restrictions. |
| `server_error` | `server_unknown_error` | Maybe | An internal error, typically due to an unknown issue with Postman or the aggregator's server. May be caused by temporary server outages. |
Not all messages are suitable for retries, especially OTPs, as the recipient's next step will be to request another OTP.
***
**Test Numbers**
The following test numbers are available in the **Postman test environment only** to simulate different delivery error codes. Do not use these numbers in the production environment.
| Test Number | Error Code |
| ------------ | ------------------------ |
| 65 1111 1111 | `recipient_invalid` |
| 65 1111 2222 | `recipient_unavailable` |
| 65 1111 3333 | `content_invalid` |
| 65 1111 4444 | `routing_error` |
| 65 1111 5555 | `message_expired` |
| 65 1111 9999 | `delivery_unknown_error` |
| 65 2222 2222 | `server_unknown_error` |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://postman-v2.guides.gov.sg/technical-users-api/api-reference/message-statuses.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.