Create Campaign

Create a new SMS campaign. The campaign is created in Draft status and is fully editable until it is sent or scheduled for delivery. Recipients are configured by attaching contact lists and/or tags to the campaign. Use this endpoint to prepare the campaign, then call POST /sms/campaigns/:id/send when you are ready to send or schedule.

Common use cases:

• A retail brand announcing a weekend sale to their KSA subscriber list.
• An e-commerce store sending a limited-time discount to tagged VIP contacts.

Endpoint

POST /sms/campaigns

Returns: 201 Created

Prerequisites

Registered Sender Required

The from must be registered and approved for the destination country. Register your sender names in the Arsel Dashboard under Settings > SMS Senders. Approval timelines vary by country (KSA, Egypt). Campaigns with unregistered sender names will be rejected at send time.

Headers

Header	Value	Required
Authorization	Bearer <your-api-key>	Yes
Content-Type	application/json	Yes

Body Parameters

All parameters are optional. You can create an empty campaign and fill in the details later via PATCH /sms/campaigns/:id.

Parameter	Type	Required	Description
name	string	No	Internal name for the campaign. Max 100 characters.
description	string	No	Optional description for internal reference.
content	string	No	SMS message body. Supports {{variables}} from contact properties.
from	string	No	Registered SMS sender name. Country-specific approval required.
list_ids	string[]	No	IDs of contact lists whose contacts should receive the campaign.
tag_ids	string[]	No	IDs of tags whose tagged contacts should receive the campaign.

Response

{
  "id": "0192a1b2-c3d4-7e5f-9000-abcdef123456"
}

Response Fields

Field	Type	Description
id	string	Unique campaign ID. Use this with GET /sms/campaigns/:id to fetch the full record, or with POST /sms/campaigns/:id/send to send or schedule.

---

Examples

cURL

curl -X POST "https://api.arsel.sa/v1/sms/campaigns" \
  -H "Authorization: Bearer be_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Sale 2026",
    "description": "Sale announcement to KSA list",
    "content": "Acme Store: 50% off everything this weekend! Shop now: {{link}}",
    "from": "ACME",
    "list_ids": ["list-uuid-1"]
  }'

JavaScript

const response = await fetch("https://api.arsel.sa/v1/sms/campaigns", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer be_your_api_key",
  },
  body: JSON.stringify({
    name: "Summer Sale 2026",
    description: "Sale announcement to KSA list",
    content: "Acme Store: 50% off everything this weekend! Shop now: {{link}}",
    from: "ACME",
    list_ids: ["list-uuid-1"],
  }),
});

const { id } = await response.json();
console.log(id); // Use this ID for subsequent operations

Python

import requests

response = requests.post(
    "https://api.arsel.sa/v1/sms/campaigns",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer be_your_api_key",
    },
    json={
        "name": "Summer Sale 2026",
        "description": "Sale announcement to KSA list",
        "content": "Acme Store: 50% off everything this weekend! Shop now: {{link}}",
        "from": "ACME",
        "list_ids": ["list-uuid-1"],
    },
)

data = response.json()
print(data["id"])

C#

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

var payload = new
{
    name = "Summer Sale 2026",
    description = "Sale announcement to KSA list",
    content = "Acme Store: 50% off everything this weekend! Shop now: {{link}}",
    from = "ACME",
    list_ids = new[] { "list-uuid-1" }
};

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/campaigns", content);
var result = await response.Content.ReadAsStringAsync();
// result: {"id":"..."}
Console.WriteLine(result);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/sms/campaigns");
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([
    "name" => "Summer Sale 2026",
    "description" => "Sale announcement to KSA list",
    "content" => "Acme Store: 50% off everything this weekend! Shop now: {{link}}",
    "from" => "ACME",
    "list_ids" => ["list-uuid-1"]
]));
$response = curl_exec($ch);
$data = json_decode($response, true);
echo $data["id"];
curl_close($ch);

---

Error Responses

401 Unauthorized

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

422 Validation Error

{
  "status_code": 422,
  "name": "validation_error",
  "message": "name must not exceed 100 characters"
}

---

After creating a campaign, you can:

• Update its content with PATCH /sms/campaigns/:id.
• Browse all campaigns with GET /sms/campaigns.
• Send or schedule it with POST /sms/campaigns/:id/send.