> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loyalty.lt/llms.txt
> Use this file to discover all available pages before exploring further.

# Get SMS Status

> Get the delivery status of a sent SMS message

# Get SMS Status

Retrieve the current delivery status and details of a previously sent SMS message.

## Path Parameters

<ParamField path="locale" type="string" required>
  Language code (e.g., `lt`, `en`)
</ParamField>

<ParamField path="message_id" type="string" required>
  Message ID returned from the [Send SMS](/api-reference/endpoints/sms/send) endpoint.

  **Example:** `msg_abc123def456`
</ParamField>

## Authentication

<ParamField header="X-API-Key" type="string" required>
  API key from Partners Portal
</ParamField>

<ParamField header="X-API-Secret" type="string" required>
  API secret from Partners Portal
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="message_id" type="string">
      Unique message identifier
    </ResponseField>

    <ResponseField name="status" type="string">
      Current delivery status: `queued`, `sent`, `delivered`, `failed`, `expired`
    </ResponseField>

    <ResponseField name="source" type="string">
      Sender name used
    </ResponseField>

    <ResponseField name="destination" type="string">
      Recipient phone number
    </ResponseField>

    <ResponseField name="sent_at" type="string">
      Timestamp when message was sent to carrier
    </ResponseField>

    <ResponseField name="delivered_at" type="string">
      Timestamp when message was delivered (if confirmed)
    </ResponseField>

    <ResponseField name="failed_at" type="string">
      Timestamp when delivery failed (if applicable)
    </ResponseField>

    <ResponseField name="scheduled" type="string">
      Scheduled delivery time (if was scheduled)
    </ResponseField>

    <ResponseField name="validity" type="string">
      Message expiry time
    </ResponseField>

    <ResponseField name="cost" type="object">
      <Expandable title="cost">
        <ResponseField name="amount" type="number">
          Total cost in EUR
        </ResponseField>

        <ResponseField name="currency" type="string">
          Currency code (`EUR`)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error_message" type="string">
      Error description if delivery failed
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.loyalty.lt/lt/sms/status/msg_abc123def456" \
    -H "X-API-Key: your_api_key" \
    -H "X-API-Secret: your_api_secret"
  ```

  ```javascript JavaScript theme={null}
  const messageId = 'msg_abc123def456';

  const response = await fetch(`https://api.loyalty.lt/lt/sms/status/${messageId}`, {
    headers: {
      'X-API-Key': 'your_api_key',
      'X-API-Secret': 'your_api_secret'
    }
  });

  const data = await response.json();
  console.log(`Status: ${data.data.status}`);

  if (data.data.delivered_at) {
    console.log(`Delivered at: ${data.data.delivered_at}`);
  }
  ```

  ```php PHP theme={null}
  <?php
  $messageId = 'msg_abc123def456';

  $response = file_get_contents(
      "https://api.loyalty.lt/lt/sms/status/$messageId",
      false,
      stream_context_create([
          'http' => [
              'method' => 'GET',
              'header' => [
                  'X-API-Key: your_api_key',
                  'X-API-Secret: your_api_secret'
              ]
          ]
      ])
  );

  $result = json_decode($response, true);
  echo "Status: " . $result['data']['status'];
  ```

  ```python Python theme={null}
  import requests

  message_id = 'msg_abc123def456'

  response = requests.get(
      f'https://api.loyalty.lt/lt/sms/status/{message_id}',
      headers={
          'X-API-Key': 'your_api_key',
          'X-API-Secret': 'your_api_secret'
      }
  )

  data = response.json()
  print(f"Status: {data['data']['status']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Delivered (200) theme={null}
  {
    "success": true,
    "data": {
      "message_id": "msg_abc123def456",
      "status": "delivered",
      "source": "MyBrand",
      "destination": "+37061234567",
      "sent_at": "2025-01-15T10:30:00Z",
      "delivered_at": "2025-01-15T10:30:05Z",
      "failed_at": null,
      "scheduled": null,
      "validity": "2025-01-16T10:30:00Z",
      "cost": {
        "amount": 0.0556,
        "currency": "EUR"
      },
      "error_message": null
    }
  }
  ```

  ```json Queued (200) theme={null}
  {
    "success": true,
    "data": {
      "message_id": "msg_xyz789",
      "status": "queued",
      "source": "MyBrand",
      "destination": "+37061234567",
      "sent_at": null,
      "delivered_at": null,
      "failed_at": null,
      "scheduled": "2025-01-16T08:00:00Z",
      "validity": "2025-01-17T08:00:00Z",
      "cost": {
        "amount": 0.0556,
        "currency": "EUR"
      },
      "error_message": null
    }
  }
  ```

  ```json Failed (200) theme={null}
  {
    "success": true,
    "data": {
      "message_id": "msg_failed123",
      "status": "failed",
      "source": "MyBrand",
      "destination": "+37061234567",
      "sent_at": "2025-01-15T10:30:00Z",
      "delivered_at": null,
      "failed_at": "2025-01-15T10:30:02Z",
      "scheduled": null,
      "validity": null,
      "cost": {
        "amount": 0.0556,
        "currency": "EUR"
      },
      "error_message": "Number not in service"
    }
  }
  ```

  ```json Not Found (404) theme={null}
  {
    "success": false,
    "message": "Message not found"
  }
  ```
</ResponseExample>

## Status Values

| Status      | Description                                     |
| ----------- | ----------------------------------------------- |
| `queued`    | Message accepted and waiting to be sent         |
| `sent`      | Message sent to carrier network                 |
| `delivered` | Confirmed delivered to recipient's phone        |
| `failed`    | Delivery failed (see `error_message`)           |
| `expired`   | Message validity period expired before delivery |

## Polling vs Webhooks

<Tip>
  For real-time status updates, use webhooks instead of polling this endpoint. Set `receipt: true` and `receiptURL` when sending the message.
</Tip>

If you must poll:

* Wait at least 5 seconds between requests
* Most messages are delivered within 10-30 seconds
* Stop polling after `delivered`, `failed`, or `expired` status

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Send SMS" icon="message" href="/api-reference/endpoints/sms/send">
    Send a new SMS message
  </Card>

  <Card title="SMS Overview" icon="book" href="/api-reference/endpoints/sms/overview">
    Webhook setup and documentation
  </Card>
</CardGroup>