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, tags and/or segments 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. Max 500 characters.
content	string	No	SMS message body. Max 3,200 characters. 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.
segment_ids	string[]	No	IDs of segments whose matching 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.