List SMS

Retrieve a paginated list of transactional SMS messages sent by your organization, each with an aggregate per-status count.

Endpoint

GET /sms

Query Parameters

Parameter	Type	Default	Description
limit	number	20	Items per page (min: 1, max: 100)
after	string	—	Cursor — return items after this id (exclusive).
before	string	—	Cursor — return items before this id (exclusive).

Results are returned newest first. See Pagination for cursor details.

Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
      "from": "Arsel",
      "content": "Your verification code is 483920.",
      "country": "KSA",
      "message_parts": 1,
      "category": "verification",
      "status": {
        "sent": 1,
        "delivered": 1,
        "undelivered": 0,
        "blocked": 0,
        "rejected": 0
      },
      "created_at": "2026-03-08T12:00:00.000Z"
    }
  ]
}

Response Fields

Field	Description
from	Sender name
content	Message body. Returns null if content has been purged.
country	Recipient country: KSA or Egypt
message_parts	Number of SMS parts the message was split into
category	Analytics category label, if provided

Status Fields

Field	Description
sent	Messages submitted to the carrier
delivered	Messages confirmed delivered to the handset
undelivered	Delivery failed (phone off, invalid number)
blocked	Blocked by the carrier or regulatory filter
rejected	Rejected before delivery attempt

---

Examples

cURL

curl "https://api.arsel.sa/v1/sms?limit=10" \
  -H "Authorization: Bearer be_your_api_key"

JavaScript

const response = await fetch(
  "https://api.arsel.sa/v1/sms?limit=10",
  {
    headers: { Authorization: "Bearer be_your_api_key" },
  }
);

const { data, has_more } = await response.json();
console.log(`Got ${data.length} messages; more available: ${has_more}`);

for (const sms of data) {
  console.log(`${sms.id}: ${sms.status.delivered} delivered, ${sms.message_parts} part(s)`);
}

Python

import requests

response = requests.get(
    "https://api.arsel.sa/v1/sms",
    headers={"Authorization": "Bearer be_your_api_key"},
    params={"limit": 10},
)

result = response.json()
for sms in result["data"]:
    status = sms["status"]
    print(f"{sms['id']}: {status['delivered']} delivered, {sms['message_parts']} part(s)")

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer be_your_api_key");

var response = await client.GetAsync("https://api.arsel.sa/v1/sms?limit=10");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/sms?limit=10");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);

foreach ($data["data"] as $sms) {
    $status = $sms["status"];
    echo "{$sms['id']}: {$status['delivered']} delivered, {$sms['message_parts']} part(s)\n";
}
curl_close($ch);