Delivery Status

GET

Track the delivery status of a single SMS message in real time. Returns detailed information including current status, segments, cost, and delivery timestamps.

Endpoint

GET

https://api.smsgateway.com/api/v1/sms/{messageId}/status

Path Parameters

Parameter	Type	Required	Description
messageId	string	Required	The unique message ID returned from the send endpoint (e.g., `msg_8f2k3j4h5g6d1a0b`).

Request Headers

Header	Required	Description
Authorization	Required	Bearer token API key with `sms:read` permission.

Examples

Check delivery status with cURL

1curl -X GET https://api.smsgateway.com/api/v1/sms/msg_8f2k3j4h5g6d1a0b/status \
2  -H "Authorization: Bearer sg_live_xxxxxxxxxxxx"

Response

Success (200 OK)

Response with delivery status

1{
2  "success": true,
3  "data": {
4    "messageId": "msg_8f2k3j4h5g6d1a0b",
5    "status": "DELIVERED",
6    "to": "+251911234567",
7    "from": "MyApp",
8    "segments": 1,
9    "cost": 0.02,
10    "isOtp": false,
11    "isSandbox": false,
12    "sentAt": "2026-07-20T14:30:01.000Z",
13    "deliveredAt": "2026-07-20T14:30:05.234Z"
14  }
15}

Response Fields

Field	Type	Description
messageId	string	Unique identifier for the message.
status	string	Current delivery status (see table below).
to	string	Recipient phone number in E.164 format.
from	string	Sender ID or originating number.
segments	number	Number of SMS segments used. Long messages may be split.
cost	number	Total cost charged for this message (in USD).
isOtp	boolean	Whether this was an OTP message.
isSandbox	boolean	Whether this was a sandbox (test) message.
sentAt	string	ISO 8601 timestamp when the message was sent to the carrier.
deliveredAt	string \| null	ISO 8601 timestamp when delivery was confirmed. Null if not yet delivered.

Status Progression

Messages progress through a lifecycle of statuses. The progression is linear unless an error occurs, in which case the status moves to FAILED.

QUEUED

→

PROCESSING

→

SENT

→

DELIVERED

At any stage:

FAILED

Status	Description
QUEUED	Message is queued and waiting to be processed.
PROCESSING	Message is being processed and routed to the carrier network.
SENT	Message has been accepted by the carrier network and is on its way to the recipient.
DELIVERED	Carrier has confirmed delivery to the recipient's device.
FAILED	Message delivery failed. Check the error details for the reason (e.g., invalid number, carrier rejection, insufficient balance).

Error Responses

404

Message Not Found

The specified message ID does not exist or you do not have permission to view it.

json

1{
2  "success": false,
3  "error": {
4    "code": "NOT_FOUND",
5    "message": "Message not found. Verify the message ID and try again."
6  }
7}

Polling Recommendation

We recommend polling the status endpoint with an exponential backoff strategy rather than rapid repeated requests. Most messages are delivered within 5–30 seconds.

Suggested intervals: 1s, 2s, 5s, 10s, 30s, 60s

For real-time delivery notifications, consider configuring a webhook to receive status updates pushed to your server.