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.

*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