Create Segment

Create a segment from a set of rules. A segment is a dynamic audience: the contacts that currently match its rules. Use its id in the segment_ids of a campaign.

The members are computed in the background. The segment is returned with status: "processing" and becomes "ready" once they are, usually within a few minutes. Poll Get Segment to see it change.

Endpoint

POST /segments

Returns: 201 Created

Headers

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

Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Segment name. Max 100 characters.
description	string	No	Optional description. Max 500 characters.
filter	object	Yes	The rules a contact must match. See Segment Filters.

An organization can hold up to 500 segments.

For ready-made filters (engaged subscribers, lapsed customers, birthdays and more), see Common segments.

Response

{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
  "name": "VIP customers",
  "description": "Opened 3+ emails in the last 90 days",
  "status": "processing",
  "filter": {
    "type": "group",
    "operator": "and",
    "conditions": [
      {
        "type": "engagement_count",
        "channel": "email",
        "action": "opened",
        "operator": "greater_than_or_equal",
        "value": 3,
        "time_window": { "value": 90, "unit": "days" }
      },
      { "type": "channel_status", "channel": "email", "consent": "subscribed" }
    ]
  },
  "contact_count": null,
  "counted_at": null,
  "created_at": "2026-03-08T12:00:00.000Z",
  "updated_at": "2026-03-08T12:00:00.000Z"
}

See List Segments for the field reference.

---

Examples

cURL

curl -X POST "https://api.arsel.sa/v1/segments" \
  -H "Authorization: Bearer $ARSEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP customers",
    "description": "Opened 3+ emails in the last 90 days",
    "filter": {
      "type": "group",
      "operator": "and",
      "conditions": [
        {
          "type": "engagement_count",
          "channel": "email",
          "action": "opened",
          "operator": "greater_than_or_equal",
          "value": 3,
          "time_window": {
            "value": 90,
            "unit": "days"
          }
        },
        {
          "type": "channel_status",
          "channel": "email",
          "consent": "subscribed"
        }
      ]
    }
  }'

JavaScript

const response = await fetch("https://api.arsel.sa/v1/segments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "VIP customers",
    description: "Opened 3+ emails in the last 90 days",
    filter: {
      type: "group",
      operator: "and",
      conditions: [
        {
          type: "engagement_count",
          channel: "email",
          action: "opened",
          operator: "greater_than_or_equal",
          value: 3,
          time_window: {
            value: 90,
            unit: "days",
          },
        },
        {
          type: "channel_status",
          channel: "email",
          consent: "subscribed",
        },
      ],
    },
  }),
});

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/segments",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
    json={
        "name": "VIP customers",
        "description": "Opened 3+ emails in the last 90 days",
        "filter": {
            "type": "group",
            "operator": "and",
            "conditions": [
                {
                    "type": "engagement_count",
                    "channel": "email",
                    "action": "opened",
                    "operator": "greater_than_or_equal",
                    "value": 3,
                    "time_window": {
                        "value": 90,
                        "unit": "days",
                    },
                },
                {
                    "type": "channel_status",
                    "channel": "email",
                    "consent": "subscribed",
                },
            ],
        },
    },
)
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/segments")
{
    Content = new StringContent(
        """
        {
          "name": "VIP customers",
          "description": "Opened 3+ emails in the last 90 days",
          "filter": {
            "type": "group",
            "operator": "and",
            "conditions": [
              {
                "type": "engagement_count",
                "channel": "email",
                "action": "opened",
                "operator": "greater_than_or_equal",
                "value": 3,
                "time_window": {
                  "value": 90,
                  "unit": "days"
                }
              },
              {
                "type": "channel_status",
                "channel": "email",
                "consent": "subscribed"
              }
            ]
          }
        }
        """,
        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/segments");
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([
        "name" => "VIP customers",
        "description" => "Opened 3+ emails in the last 90 days",
        "filter" => [
            "type" => "group",
            "operator" => "and",
            "conditions" => [
                [
                    "type" => "engagement_count",
                    "channel" => "email",
                    "action" => "opened",
                    "operator" => "greater_than_or_equal",
                    "value" => 3,
                    "time_window" => [
                        "value" => 90,
                        "unit" => "days",
                    ],
                ],
                [
                    "type" => "channel_status",
                    "channel" => "email",
                    "consent" => "subscribed",
                ],
            ],
        ],
    ]),
]);

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

Create, then wait until it is ready

A new segment is processing until its members are computed. To use it straight away, for example to list its contacts, poll until status is ready.

async function arsel(path, { method = "GET", body } = {}) {
  const response = await fetch(`https://api.arsel.sa/v1${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: body && JSON.stringify(body),
  });
  const data = await response.json();
  if (!response.ok) throw new Error(`${data.name}: ${data.message}`);
  return data;
}

const created = await arsel("/segments", {
  method: "POST",
  body: {
    name: "Lapsed customers",
    filter: {
      type: "group",
      operator: "and",
      conditions: [
        { type: "event", event_name: "order_placed" },
        {
          type: "event",
          event_name: "order_placed",
          time_window: { value: 90, unit: "days" },
          negate: true,
        },
      ],
    },
  },
});

let segment = created;
while (segment.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  segment = await arsel(`/segments/${created.id}`);
}

const members = await arsel(`/contacts?segment_id=${created.id}&limit=100`);
console.log(segment.contact_count, members.data.length);

---

Error Responses

422 Invalid Filter

{
  "status_code": 422,
  "name": "validation_error",
  "message": "Invalid filter: conditions.0.operator: \"created_at\" does not accept the operator \"contains\""
}

422 Segment Limit

{
  "status_code": 422,
  "name": "segment_limit_reached",
  "message": "This organization has reached the limit of 500 segments."
}

401 Unauthorized

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