Send Campaign

Queue a push campaign for fan-out, immediately or at a scheduled time.

Endpoint

POST /push/campaigns/:id/send

Returns: 200 OK

Path Parameters

Parameter	Type	Description
id	string	Campaign ID

Headers

Header	Value	Required
Authorization	Bearer <your-api-key>	Yes
Content-Type	application/json	When sending a body
Idempotency-Key	Any unique string, max 256 chars	No — makes a retry safe; see Idempotency

Body Parameters

Parameter	Type	Required	Description
scheduled_at	string	No	ISO 8601 date-time to schedule for. Must be in the future. Omit to send immediately.

{
  "scheduled_at": "2026-09-01T09:00:00Z"
}

Send an empty body — or no body at all — to send now.

---

How recipients are filtered

Every recipient passes the same push consent gate as a single Send Push. The difference is what happens when someone fails it:

• In a campaign, a contact who opted out or whose devices are all dead is skipped, not refused. A partially-reachable audience still sends to the reachable part.
• In a single send, the same contact returns 403.

If smart_sending_enabled is on, contacts who received a push too recently are also skipped, according to your organization's frequency cap.

A campaign whose audience resolves to zero reachable contacts is rejected with 400 rather than sent — see the error tabs below.

---

Response

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

The campaign moves to Queued (immediate) or Scheduled (with scheduled_at). A 200 means accepted for fan-out, not that notifications have been delivered.

To reschedule, call this endpoint again with a new scheduled_at — a campaign that is already Scheduled simply takes the new time. You do not need to cancel it first.

---

Examples

Send now:

cURL

curl -X POST "https://api.arsel.sa/v1/push/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/send" \
  -H "Authorization: Bearer $ARSEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const response = await fetch("https://api.arsel.sa/v1/push/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});

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/push/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/send",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
    json={},
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;
using System.Text;

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/push/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/send")
{
    Content = new StringContent(
        """
        {}
        """,
        Encoding.UTF8,
        "application/json"),
};

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/push/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/send");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => "{}",
]);

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

Schedule:

cURL

curl -X POST "https://api.arsel.sa/v1/push/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/send" \
  -H "Authorization: Bearer $ARSEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_at": "2026-09-01T09:00:00Z"
  }'

JavaScript

const response = await fetch("https://api.arsel.sa/v1/push/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    scheduled_at: "2026-09-01T09:00:00Z",
  }),
});

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/push/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/send",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
    json={
        "scheduled_at": "2026-09-01T09:00:00Z",
    },
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;
using System.Text;

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/push/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/send")
{
    Content = new StringContent(
        """
        {
          "scheduled_at": "2026-09-01T09:00:00Z"
        }
        """,
        Encoding.UTF8,
        "application/json"),
};

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/push/campaigns/0192a1b2-c3d4-7e5f-9000-abcdef123456/send");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "scheduled_at" => "2026-09-01T09:00:00Z",
    ]),
]);

$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 Already Processing

Only a Draft or Scheduled campaign can be sent:

{
  "status_code": 400,
  "name": "bad_request",
  "message": "Campaign is already being processed"
}

400 Empty Audience

{
  "status_code": 400,
  "name": "bad_request",
  "message": "Campaign has no reachable recipients. Push only reaches contacts with a registered device — check the estimate before sending."
}

When Smart Sending is what emptied the audience, the message says so instead:

{
  "status_code": 400,
  "name": "bad_request",
  "message": "All 1240 reachable recipients were skipped by Smart Sending (at least 24 hours must pass between sends). Disable Smart Sending for this campaign or try again later."
}

400 Schedule

{
  "status_code": 400,
  "name": "bad_request",
  "message": "Schedule time must be in the future"
}

A campaign that is already fanning out cannot be scheduled:

{
  "status_code": 400,
  "name": "bad_request",
  "message": "Campaign cannot be scheduled — it is already being processed or sent"
}

429 Quota

{
  "status_code": 429,
  "name": "monthly_quota_exceeded",
  "message": "Insufficient push quota to send this campaign (12000 recipients). Monthly limit: 45000/50000 used."
}

404 Not Found

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

401 Unauthorized

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