Cancel Campaign

Cancel a Scheduled, Queued, or Sending campaign. Messages that have already been handed off for delivery cannot be recalled — cancellation only prevents messages that have not yet been dispatched.

Endpoint

POST /sms/campaigns/:id/cancel

Returns: 200 OK

Prerequisites

Cancellation Limits

Cancellation only stops messages that have not yet been handed off for delivery. Recipients who already received the message will not be affected. Campaigns in Sent, Failed, or Cancelled status cannot be cancelled again.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The campaign ID.

Headers

Header	Value	Required
Authorization	Bearer <your-api-key>	Yes
Idempotency-Key	Any unique string, max 256 chars	No — makes a retry safe; see Idempotency

Response

{
  "message": "Campaign cancelled"
}

---

Examples

cURL

curl -X POST "https://api.arsel.sa/v1/sms/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/cancel" \
  -H "Authorization: Bearer $ARSEL_API_KEY"

JavaScript

const response = await fetch("https://api.arsel.sa/v1/sms/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/cancel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) {
  throw new Error(`${data.name}: ${data.message}`);
}

console.log(data);

Python

import os

import requests

response = requests.post(
    "https://api.arsel.sa/v1/sms/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/cancel",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;

var client = new HttpClient(); // share one instance across requests
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("ARSEL_API_KEY"));

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.arsel.sa/v1/sms/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/cancel");

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"{(int)response.StatusCode}: {body}");

Console.WriteLine(body);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/sms/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/cancel");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
    ],
]);

$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
    throw new Exception("{$data['name']}: {$data['message']}");
}

print_r($data);

---

Error Responses

400 Bad Request

{
  "status_code": 400,
  "name": "bad_request",
  "message": "Campaign cannot be cancelled in its current status"
}

404 Not Found

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

401 Unauthorized

{
  "status_code": 401,
  "name": "unauthorized",
  "message": "Invalid API Key"
}