Send SMS

Queue a transactional SMS for immediate delivery to recipients in Saudi Arabia and Egypt.

OTP and verification codes
Appointment reminders
Order status updates
Account notifications

Endpoint

POST /sms/send

Returns: 202 Accepted

Prerequisites

Verified Sender Name Required

The from sender name must be registered and approved in the Arsel Dashboard under Settings > SMS Senders. Sender name registration is required by telecom regulators in KSA and Egypt. Messages with unregistered sender names will be rejected.

Headers

Header	Value	Required
`Authorization`	`Bearer <your-api-key>`	Yes
`Content-Type`	`application/json`	Yes
`Idempotency-Key`	Any unique string, max 256 chars	No — see Idempotency

Body Parameters

Parameter	Type	Required	Description
`from`	string	Yes	Registered sender name. Alphanumeric, 3-11 characters.
`to`	string[]	Yes	Array of phone numbers in international format. Max 100 recipients.
`content`	string	Yes	Message body. Supports `{{variables}}`.
`variables`	object	No	Key-value pairs for `{{variable}}` replacement in content.
`category`	string	No	Label for grouping messages in analytics. Max 100 characters.

Phone Number Format

All recipients in a single request must be from the same country. Mixing KSA and Egypt numbers in one request is not allowed.

Country	Format	Example
Saudi Arabia (KSA)	`+9665XXXXXXXX`	`+966512345678`
Egypt	`+201XXXXXXXXX`	`+201012345678`

Character Encoding and Message Parts

SMS messages are automatically split into parts based on content encoding:

Encoding	Characters	Single SMS	Per Part (Multi-part)
GSM (Latin, digits, basic symbols)	A-Z, 0-9, common punctuation	160 characters	153 characters
Unicode (Arabic, emoji, special chars)	Arabic script, CJK, emoji	70 characters	67 characters

The encoding is detected automatically based on message content. If any character requires Unicode, the entire message uses Unicode encoding.

A message may run to at most 10 parts — 1,530 GSM characters, or 670 Unicode ones. Longer content is rejected with 400 bad_request.

Response

{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a"
}

Field	Type	Description
`id`	string	Unique SMS ID. Use this to track delivery status via `GET /sms/:id`.

tip

The 202 Accepted response means the SMS is queued, not yet delivered. Use GET /sms/:id to track delivery progress.

Idempotency

Sending the same SMS message twice — for example because a network timeout made you retry — could send the SMS twice — and bill you for both. To make a retry safe, send an Idempotency-Key header whose value is unique to that SMS message (for example otp/123):

The first request with a given key is processed normally and its response is stored.
Any later request with the same key (within 24 hours) is not reprocessed — it returns the original response unchanged, plus an Idempotent-Replayed: true response header. The side effect happens only once.
After 24 hours the key expires and may be reused.

The key can be any unique string up to 256 characters. A UUID works, but a value derived from the entity the request is about — like otp/123 — is easier to regenerate identically on a retry. Keys are scoped per endpoint, so the same value can be reused independently across the send-email, send-SMS, and send-event endpoints without colliding.

Reusing a key with a different payload

Reuse a key with a different request body and the request is rejected with 409 invalid_idempotent_request, which protects you from receiving the wrong cached response. Use a fresh key for a genuinely different request.

Idempotency error responses

Status	`name`	When
`400`	`invalid_idempotency_key`	The key is empty or longer than 256 characters.
`409`	`invalid_idempotent_request`	The key was already used with a different request body.
`409`	`concurrent_idempotent_requests`	An earlier request with the same key is still being processed — retry shortly.

Examples

Basic SMS

cURL
JavaScript
Python
C#
PHP

curl -X POST "https://api.arsel.sa/v1/sms/send" \
  -H "Authorization: Bearer be_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: otp/123" \
  -d '{
    "from": "Arsel",
    "to": ["+966512345678"],
    "content": "Your verification code is 483920. It expires in 5 minutes."
  }'

const response = await fetch("https://api.arsel.sa/v1/sms/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer be_your_api_key",
  },
  body: JSON.stringify({
    from: "Arsel",
    to: ["+966512345678"],
    content: "Your verification code is 483920. It expires in 5 minutes.",
  }),
});

const { id } = await response.json();
console.log(id); // Use this to track delivery

import requests

response = requests.post(
    "https://api.arsel.sa/v1/sms/send",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer be_your_api_key",
    },
    json={
        "from": "Arsel",
        "to": ["+966512345678"],
        "content": "Your verification code is 483920. It expires in 5 minutes.",
    },
)

data = response.json()
print(data["id"])  # Use this to track delivery

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

var payload = new
{
    from = "Arsel",
    to = new[] { "+966512345678" },
    content = "Your verification code is 483920. It expires in 5 minutes."
};

var json = System.Text.Json.JsonSerializer.Serialize(payload);
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.arsel.sa/v1/sms/send", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

<?php
$ch = curl_init("https://api.arsel.sa/v1/sms/send");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "from" => "Arsel",
    "to" => ["+966512345678"],
    "content" => "Your verification code is 483920. It expires in 5 minutes."
]));
$response = curl_exec($ch);
echo $response;
curl_close($ch);

With Template Variables

cURL
JavaScript
Python
C#
PHP

curl -X POST "https://api.arsel.sa/v1/sms/send" \
  -H "Authorization: Bearer be_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "MyStore",
    "to": ["+966512345678", "+966598765432"],
    "content": "Hi {{name}}, your order {{order_id}} has been shipped and will arrive by {{date}}.",
    "variables": {
      "name": "Ahmed",
      "order_id": "ORD-12345",
      "date": "March 10"
    },
    "category": "shipping-updates"
  }'

const response = await fetch("https://api.arsel.sa/v1/sms/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer be_your_api_key",
  },
  body: JSON.stringify({
    from: "MyStore",
    to: ["+966512345678", "+966598765432"],
    content:
      "Hi {{name}}, your order {{order_id}} has been shipped and will arrive by {{date}}.",
    variables: {
      name: "Ahmed",
      order_id: "ORD-12345",
      date: "March 10",
    },
    category: "shipping-updates",
  }),
});

const { id } = await response.json();
console.log(id); // Use this to track delivery

import requests

response = requests.post(
    "https://api.arsel.sa/v1/sms/send",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer be_your_api_key",
    },
    json={
        "from": "MyStore",
        "to": ["+966512345678", "+966598765432"],
        "content": "Hi {{name}}, your order {{order_id}} has been shipped and will arrive by {{date}}.",
        "variables": {
            "name": "Ahmed",
            "order_id": "ORD-12345",
            "date": "March 10",
        },
        "category": "shipping-updates",
    },
)

print(response.json())

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

var payload = new
{
    from = "MyStore",
    to = new[] { "+966512345678", "+966598765432" },
    content = "Hi {{name}}, your order {{order_id}} has been shipped and will arrive by {{date}}.",
    variables = new
    {
        name = "Ahmed",
        order_id = "ORD-12345",
        date = "March 10"
    },
    category = "shipping-updates"
};

var json = System.Text.Json.JsonSerializer.Serialize(payload);
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.arsel.sa/v1/sms/send", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

<?php
$ch = curl_init("https://api.arsel.sa/v1/sms/send");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "from" => "MyStore",
    "to" => ["+966512345678", "+966598765432"],
    "content" => "Hi {{name}}, your order {{order_id}} has been shipped and will arrive by {{date}}.",
    "variables" => [
        "name" => "Ahmed",
        "order_id" => "ORD-12345",
        "date" => "March 10"
    ],
    "category" => "shipping-updates"
]));
$response = curl_exec($ch);
echo $response;
curl_close($ch);

Arabic Content (Unicode)

cURL
JavaScript
Python
C#
PHP

curl -X POST "https://api.arsel.sa/v1/sms/send" \
  -H "Authorization: Bearer be_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Arsel",
    "to": ["+966512345678"],
    "content": "مرحباً {{name}}، رمز التحقق الخاص بك هو {{code}}. صالح لمدة 5 دقائق.",
    "variables": {
      "name": "أحمد",
      "code": "839201"
    }
  }'

const response = await fetch("https://api.arsel.sa/v1/sms/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer be_your_api_key",
  },
  body: JSON.stringify({
    from: "Arsel",
    to: ["+966512345678"],
    content: "مرحباً {{name}}، رمز التحقق الخاص بك هو {{code}}. صالح لمدة 5 دقائق.",
    variables: {
      name: "أحمد",
      code: "839201",
    },
  }),
});

const { id } = await response.json();
console.log(id); // Use this to track delivery

import requests

response = requests.post(
    "https://api.arsel.sa/v1/sms/send",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer be_your_api_key",
    },
    json={
        "from": "Arsel",
        "to": ["+966512345678"],
        "content": "مرحباً {{name}}، رمز التحقق الخاص بك هو {{code}}. صالح لمدة 5 دقائق.",
        "variables": {
            "name": "أحمد",
            "code": "839201",
        },
    },
)

print(response.json())

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

var payload = new
{
    from = "Arsel",
    to = new[] { "+966512345678" },
    content = "مرحباً {{name}}، رمز التحقق الخاص بك هو {{code}}. صالح لمدة 5 دقائق.",
    variables = new
    {
        name = "أحمد",
        code = "839201"
    }
};

var json = System.Text.Json.JsonSerializer.Serialize(payload);
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.arsel.sa/v1/sms/send", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

<?php
$ch = curl_init("https://api.arsel.sa/v1/sms/send");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "from" => "Arsel",
    "to" => ["+966512345678"],
    "content" => "مرحباً {{name}}، رمز التحقق الخاص بك هو {{code}}. صالح لمدة 5 دقائق.",
    "variables" => [
        "name" => "أحمد",
        "code" => "839201"
    ]
]));
$response = curl_exec($ch);
echo $response;
curl_close($ch);

Error Responses

422 Validation Error
401 Unauthorized
429 Rate Limited

{
  "status_code": 422,
  "name": "validation_error",
  "message": "All recipients must be from the same country"
}

{
  "status_code": 401,
  "name": "unauthorized",
  "message": "Invalid or missing API key"
}

{
  "status_code": 429,
  "name": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after the period indicated in the retry-after header."
}

Endpoint​

Prerequisites​

Headers​

Body Parameters​

Phone Number Format​

Character Encoding and Message Parts​

Response​

Idempotency​

Examples​

Basic SMS​

With Template Variables​

Arabic Content (Unicode)​

Error Responses​