Get SMS

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/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/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/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/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/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);

Error Responses

404 Not Found

{
  "status_code": 404,
  "name": "not_found",
  "message": "SMS not found"
}