List SMS

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

Endpoint

GET /sms

Returns: 200 OK

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 $ARSEL_API_KEY"

JavaScript

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

const data = await response.json();
if (!response.ok) {
  throw new Error(`${data.name}: ${data.message}`);
}

console.log(data);

Python

import os

import requests

response = requests.get(
    "https://api.arsel.sa/v1/sms?limit=10",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;

var client = new HttpClient(); // share one instance across requests
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("ARSEL_API_KEY"));

var response = await client.GetAsync("https://api.arsel.sa/v1/sms?limit=10");
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"{(int)response.StatusCode}: {body}");

Console.WriteLine(body);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/sms?limit=10");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
    ],
]);

$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
    throw new Exception("{$data['name']}: {$data['message']}");
}

print_r($data);

---

Error Responses

401 Unauthorized

{
  "status_code": 401,
  "name": "unauthorized",
  "message": "Invalid API Key"
}