Skip to main content

Check SMS Message Status

Query the delivery status of a previously sent SMS by its Octopods message ID.

Written by Tarek Khalil

Endpoint

GET https://app.octopods.io/api/v1/sms/messages/:message_id

:message_id is the message_id returned when the SMS was created via the send endpoint.

Authentication

Include your Channel API Key in the request header:

X-Octopods-Auth: YOUR_CHANNEL_API_KEY

The key must belong to the same SMS channel that sent the message.

Example request

GET https://app.octopods.io/api/v1/sms/messages/4829174
X-Octopods-Auth: YOUR_CHANNEL_API_KEY

Success response

On success the API returns HTTP 200 OK with a JSON body describing the current status:

{
  "request_id": "b14f0e5a-3f3c-4e9c-b1d1-6d19f0c4a721",
  "message_id": 4829174,
  "status": "delivered",
  "phone_number": "+15551234567",
  "sent_at": "2026-04-24T10:23:45Z",
  "delivered_at": "2026-04-24T10:23:49Z",
  "failure_reason": null
}

The exact set of timestamp fields depends on how far the message has progressed. Fields for stages the message hasn’t reached yet are null.

Status values

Status

Meaning

queued

The SMS has been accepted and is waiting to be handed to the carrier.

sent

The SMS provider confirmed the message has been handed to the mobile network.

delivered

The carrier confirmed the message reached the recipient’s handset.

failed

The send failed. failure_reason describes why.

undelivered

The carrier could not deliver the message within its retry window.

Common failure reasons

When status is failed or undelivered, failure_reason typically contains one of:

  • The phone number is not a valid mobile subscriber.

  • The carrier blocked the message for content or sender reputation reasons.

  • The recipient’s handset is out of coverage or powered off for too long.

  • The sender number is not approved to deliver to the recipient’s country.

Error response

If the request is malformed or the message cannot be found, the API returns HTTP 400 Bad Request:

{
  "request_id": "b14f0e5a-3f3c-4e9c-b1d1-6d19f0c4a721",
  "error_code": 1,
  "error": "You must supply message_id in your request payload."
}

Error codes

Code

Name

When it happens

1

ARGUMENT_MISSING

:message_id was omitted from the URL.

5

DEPRECATED_API_KEY

The API key has been rotated or revoked. Fetch the current key from Octopods.

Polling tips

  • Wait a few seconds before polling. Status updates from the carrier arrive asynchronously. An immediate poll typically returns queued or sent.

  • Stop polling once the status is terminal. delivered, failed, and undelivered are terminal — polling further will not change the result.

What’s next

Did this answer your question?