SMS Status

Track the delivery status of your transactional SMS messages. List all sent messages with aggregate status counts, or get per-recipient delivery details for a specific message.

List SMS Messages

Retrieve a paginated list of transactional SMS messages sent by your organization.

Endpoint

GET /sms

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	20	Results per page

Response

{
  "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"
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

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/api/v1/sms?page=1&limit=10" \
  -H "Authorization: Bearer be_your_api_key"

JavaScript

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

const { data, meta } = await response.json();
console.log(`Showing ${data.length} of ${meta.total} messages`);

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/api/v1/sms",
    headers={"Authorization": "Bearer be_your_api_key"},
    params={"page": 1, "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/api/v1/sms?page=1&limit=10");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/api/v1/sms?page=1&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);

---

Get SMS Details

Retrieve detailed delivery status for a specific SMS, including per-recipient tracking.

Endpoint

GET /sms/:id

Path Parameters

Parameter	Type	Description
id	string	The SMS ID returned from POST /sms/send

Response

{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
  "from": "Arsel",
  "to": [
    {
      "phone": "+966512345678",
      "status": "delivered",
      "timestamp": "2026-03-08T12:00:03.000Z"
    },
    {
      "phone": "+966598765432",
      "status": "sent",
      "timestamp": null
    }
  ],
  "content": "Your verification code is 483920.",
  "country": "KSA",
  "message_parts": 1,
  "category": "verification",
  "created_at": "2026-03-08T12:00:00.000Z"
}

Recipient Status Values

Status	Description
in_progress	Message is being processed
sent	Submitted to the carrier, awaiting delivery confirmation
delivered	Confirmed delivered to the recipient's handset
undelivered	Delivery failed (phone powered off, invalid number, etc.)
buffered	Queued by the carrier for later delivery
blocked	Blocked by the carrier or a regulatory filter
rejected	Rejected before delivery attempt
expired	Delivery window expired before the message could be delivered
clicked	Recipient clicked a tracked link in the message
unknown	Delivery status could not be determined

Examples

cURL

curl "https://api.arsel.sa/api/v1/sms/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a" \
  -H "Authorization: Bearer be_your_api_key"

JavaScript

const smsId = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a";

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

const sms = await response.json();
for (const recipient of sms.to) {
  console.log(`${recipient.phone}: ${recipient.status}`);
}

Python

import requests

sms_id = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a"

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

sms = response.json()
for recipient in sms["to"]:
    print(f"{recipient['phone']}: {recipient['status']}")

C#

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

var smsId = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a";
var response = await client.GetAsync($"https://api.arsel.sa/api/v1/sms/{smsId}");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

PHP

<?php
$smsId = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a";
$ch = curl_init("https://api.arsel.sa/api/v1/sms/{$smsId}");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$sms = json_decode($response, true);

foreach ($sms["to"] as $recipient) {
    echo "{$recipient['phone']}: {$recipient['status']}\n";
}
curl_close($ch);