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

# List messages

> List messages with optional filters for market, status, sender ID, and date range.

**Required permission:** `messaging:read`

## Query parameters

<ParamField query="market" type="string">
  Filter by ISO 3166-1 alpha-2 country code.
</ParamField>

<ParamField query="status" type="string">
  Filter by message status: `queued`, `sent`, `delivered`, `undelivered`, `failed`, `scheduled`, `cancelled`.
</ParamField>

<ParamField query="sender_id" type="string">
  Filter by Sender ID.
</ParamField>

<ParamField query="reference" type="string">
  Filter by your internal reference.
</ParamField>

<ParamField query="from" type="string">
  Start date (ISO 8601). Inclusive.
</ParamField>

<ParamField query="to" type="string">
  End date (ISO 8601). Inclusive.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response.
</ParamField>

<ParamField query="page_size" type="integer" default="50">
  Results per page. Maximum 100.
</ParamField>

## Example

```bash theme={null}
curl "https://api.senderz.ai/v1/messaging/messages?market=AU&status=delivered&from=2026-07-01&page_size=25" \
  -H "Authorization: Bearer sz_live_xxxxxxxxxxxxx"
```

## Response

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": [
      {
        "id": "msg_a1b2c3d4e5",
        "status": "delivered",
        "to": "+61400123456",
        "sender_id": "TrackFast",
        "segments": 1,
        "market": "AU",
        "reference": "shipment-SYD-90421",
        "created_at": "2026-07-17T14:30:00+10:00",
        "delivered_at": "2026-07-17T14:30:03+10:00"
      },
      {
        "id": "msg_f6g7h8i9j0",
        "status": "delivered",
        "to": "+61412345678",
        "sender_id": "SecurBank",
        "segments": 1,
        "market": "AU",
        "reference": "otp-login-user-8821",
        "created_at": "2026-07-17T14:28:00+10:00",
        "delivered_at": "2026-07-17T14:28:02+10:00"
      }
    ],
    "pagination": {
      "has_more": true,
      "next_cursor": "cur_xyz789",
      "page_size": 25
    },
    "meta": {
      "request_id": "req_ghi789",
      "timestamp": "2026-07-17T14:35:00+10:00"
    }
  }
  ```
</ResponseExample>