Check message status

GET /status/{message_id} returns the current state of a previously- submitted SMS. The path parameter is the message_id returned by POST /send.

Request

cURL

curl $BASE_URL/api/v1/lisoloo/sms-api/status/507f1f77bcf86cd799439011 \
  -H "app-key: $LISOLOO_API_KEY"

Python

r = requests.get(
    f"{API_URL}/status/{message_id}",
    headers={"app-key": API_KEY},
    timeout=10,
)
r.raise_for_status()
print(r.json())

JavaScript

const r = await fetch(`${API_URL}/status/${messageId}`, {
  headers: { "app-key": API_KEY },
});
console.log(await r.json());

PHP

$ch = curl_init("$apiUrl/status/$messageId");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["app-key: $apiKey"],
]);
echo curl_exec($ch);

Response

{
  "status_code": 200,
  "data": {
    "message_id":       "507f1f77bcf86cd799439011",
    "status":           "delivered",
    "total_recipients": 1,
    "delivered":        1,
    "failed":           0,
    "pending":          0,
    "created_at":       "2026-05-27T10:15:00Z",
    "updated_at":       "2026-05-27T10:15:08Z"
  }
}

Field	Description
status	Aggregate status across all recipients. See Message lifecycle for the full enum.
total_recipients	Number of recipients in the original to array (from OPS_SMS_MESSAGE.total_recipients).
delivered / failed / pending	Per-state counts derived from the underlying OPS_SMS_MESSAGE_CONTACT rows. pending includes contacts in any non-terminal state.
created_at	When POST /send returned.
updated_at	Last state-change timestamp.

Polling pattern

The right cadence depends on traffic shape. For interactive flows (OTP, single-recipient confirmations), poll 3 times then give up:

import time
import requests

def wait_for_delivery(message_id, max_attempts=3, delay=2):
    for _ in range(max_attempts):
        r = requests.get(f"{API_URL}/status/{message_id}", headers=HEADERS)
        data = r.json()["data"]
        if data["status"] in ("delivered", "failed"):
            return data
        time.sleep(delay)
    return data  # last-seen state

For batch flows, switch to webhooks instead — polling 1 000 message_ids burns rate-limit budget.

Poll terminal states only when you have to

If you have webhooks set up, the status endpoint is for “I lost the webhook event, what happened?” — not the primary signal. Treat it as a fallback, not the default.

404 — unknown message ID

HTTP/1.1 404 Not Found

{
  "detail": "Message not found"
}

Returned when:

• The message_id doesn’t exist.
• The message_id belongs to a different merchant — the lookup is scoped to your sys_organization_id, so cross-tenant IDs surface as 404 and never leak existence.

Cross-recipient mixed terminal states

A multi-recipient send can finish with some recipients delivered and others failed. The aggregate status field reflects the message- level state machine (see Message lifecycle); the delivered and failed counters give you the exact split.

See also

• Message lifecycle — full state diagram
• Webhooks overview — push instead of poll
• Errors — error envelope shape