Message status

Look up the current status of a message you sent through the API.

GEThttps://api.cloudmetis.com/v1/sms/status/{message_id}scope: sms:read

Prefer webhooks for tracking delivery — they arrive as soon as the status changes. Use this endpoint to check a single message on demand or to recover after missed webhooks.

Request

curl https://api.cloudmetis.com/v1/sms/status/msg_247 \
  -H "Authorization: Bearer cm_live_your_key"

Response (200)

{
  "message_id": "msg_247",
  "to": "+254712345678",
  "status": "delivered",
  "sms_parts": 1,
  "network": "Safaricom",
  "sent_at": "2026-11-01T14:30:21+03:00",
  "delivered_at": "2026-11-01T14:30:25+03:00",
  "failure_reason": null,
  "sandbox": false
}

Field	Description
status	See the table below
sms_parts	Units used by this message
network	Safaricom, Airtel, Telkom or null if unknown
sent_at	When the message was handed to the network
delivered_at	When the network confirmed delivery, or null
failure_reason	Why it failed, or null

Statuses

Status	Meaning	Final?
queued	Accepted, waiting to be sent	No
submitted	Handed to the gateway, waiting for the network	No
sent	Accepted by the mobile network	No
delivered	The phone received it	Yes
failed	The network could not deliver it (phone off too long, number not in service…)	Yes
expired	The network gave up after its delivery window	Yes
rejected	The network refused it (invalid number, blocked sender…)	Yes
optedout	The number opted out of your messages	Yes

Once a message reaches a final status it never changes.

Errors

Status	Code	When
404	not_found	Unknown ID, or the message belongs to another organisation or was not sent through the API
403	scope_denied	The key lacks sms:read

Only messages sent through the API can be looked up. Messages sent from the app's campaigns are not visible here.