Message status
Look up any message you sent with this key. Use it for support tools and reconciliation; use webhooks for real-time updates.
GET
/sms/messages/:idhttps://api.smsray.com/api/sms/v1/sms/messages/:idFetch the current state of a message sent with this API key: status, encoding, segments, cost and timestamps.
Request
Headers
| Name | Type | Required | Rules |
|---|---|---|---|
x-api-key | string | required | Your secret key, ls_live_ followed by 48 hex characters. |
Path parameters
| Name | Type | Required | Rules |
|---|---|---|---|
id | string (uuid) | required | The messageId returned by /sms/send or /sms/otp/send. |
Example request
curl https://api.smsray.com/api/sms/v1/sms/messages/2b1f6c1e-8d4f-4c55-9a51-0d2b0b7f3a11 \
-H "x-api-key: $SMSRAY_API_KEY"Response
200
200 application/json
{
"_id": "2b1f6c1e-8d4f-4c55-9a51-0d2b0b7f3a11",
"to": "+9779801234567",
"from": "SMSRay",
"text": "Your order #1042 has shipped.",
"type": "transactional",
"encoding": "GSM7",
"segments": 1,
"cost": 0.5,
"status": "delivered",
"error": "",
"attempts": 1,
"submittedAt": "2026-10-10T04:15:01.000Z",
"sentAt": "2026-10-10T04:15:03.000Z",
"deliveredAt": "2026-10-10T04:15:07.000Z",
"failedAt": null,
"createdAt": "2026-10-10T04:15:00.000Z",
"updatedAt": "2026-10-10T04:15:07.000Z"
}404Unknown id
404 application/json
{ "error": "Message not found", "code": "not_found" }Response fields
| Name | Type | Required | Rules |
|---|---|---|---|
status | string | required | queued, submitting, submitted, sent, delivered, undelivered, failed or rejected (test for keys in test mode). |
to | string | required | The recipient in E.164. |
text | string | required | The message body, or (OTP hidden) for messages created by /sms/otp/send. |
from | string | required | The sender recorded for the message. |
attempts | integer | required | How many delivery attempts were made. |
error | string | required | A neutral failure code when one is known (network_unavailable, delivery_timeout, carrier_rejected, invalid_number, delivery_failed), otherwise empty. |
dlr | object | optional | Delivery report { status, code, raw, at }, present when the network returned one. |
submittedAt · sentAt · deliveredAt · failedAt | string | null | required | ISO 8601 UTC timestamps for each transition. |
Errors
Every error uses the same shape: { "error", "code", "details"? }. Branch on code, not on the message.
| HTTP | code | When |
|---|---|---|
| 401 | unauthorized | The x-api-key header is missing ("Missing x-api-key") or the key is unknown ("Invalid API key"). |
| 403 | client_disabled | The API client that owns this key has been disabled in the dashboard. |
| 404 | not_found | No message with this id was sent by this API key. Messages from other keys — even in the same workspace — are not visible. |
| 429 | rate_limited | You exceeded your per-client request rate (default 20 requests per second). Honour Retry-After. |
| 500 | server_error | Something went wrong on our side. The body never contains a stack trace. |
Notes
- Polling works, but webhooks are cheaper and faster. If you poll, back off (for example 2 s, 5 s, 15 s, 60 s) and stop at a final status:
delivered,undelivered,failedorrejected. - Internal delivery details are never returned.