Send Event

Send (ingest) a custom event for a contact. The event name must already be defined for your organization, and the payload is validated against that definition's schema. Accepted events can trigger automations in real time.

Endpoint

POST /events/send

Returns: 202 Accepted

Headers

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

Body Parameters

Parameter	Type	Required	Description
event	string	Yes	Name of a defined event for your organization.
email	string	Conditional	Email of the contact the event is about. Provide exactly one of email or contact_id. If no contact with this email exists, one is auto-created when the automation runs.
contact_id	string	Conditional	Contact UUID the event is about. Provide exactly one of email or contact_id.
data	object	Yes	Event payload. Validated against the event's declared schema.
timestamp	string	No	ISO 8601 timestamp the event occurred. Defaults to server time.

Identify the contact

You must provide exactly one of email or contact_id. Providing both returns 400, and providing neither returns 400.

{
  "event": "order.completed",
  "email": "john.doe@example.com",
  "data": {
    "order_id": "A-1023",
    "total": 149.99
  },
  "timestamp": "2026-06-01T12:00:00.000Z"
}

---

Response

The event is accepted for asynchronous processing. id is the event log ID.

{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
  "status": "accepted"
}

Field	Type	Description
id	string	Event log ID (UUIDv7)
status	string	Always accepted for a 202 response

---

Examples

cURL

curl -X POST "https://api.arsel.sa/v1/events/send" \
  -H "Authorization: Bearer be_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order.completed",
    "email": "john.doe@example.com",
    "data": { "order_id": "A-1023", "total": 149.99 }
  }'

JavaScript

const response = await fetch("https://api.arsel.sa/v1/events/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer be_your_api_key",
  },
  body: JSON.stringify({
    event: "order.completed",
    email: "john.doe@example.com",
    data: { order_id: "A-1023", total: 149.99 },
  }),
});

const result = await response.json();
console.log(result.id, result.status);

Python

import requests

response = requests.post(
    "https://api.arsel.sa/v1/events/send",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer be_your_api_key",
    },
    json={
        "event": "order.completed",
        "email": "john.doe@example.com",
        "data": {"order_id": "A-1023", "total": 149.99},
    },
)

result = response.json()
print(result["id"], result["status"])

C#

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

var payload = new
{
    @event = "order.completed",
    email = "john.doe@example.com",
    data = new { order_id = "A-1023", total = 149.99 }
};

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/events/send", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/events/send");
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([
    "event" => "order.completed",
    "email" => "john.doe@example.com",
    "data" => ["order_id" => "A-1023", "total" => 149.99]
]));
$response = curl_exec($ch);
echo $response;
curl_close($ch);

---

Error Responses

400 Contact

Provide exactly one of email or contact_id:

{
  "status_code": 400,
  "name": "bad_request",
  "message": "Provide either email or contact_id."
}

404 Event

{
  "status_code": 404,
  "name": "not_found",
  "message": "No event named \"order.completed\" is defined in this organization."
}

422 Schema Mismatch

The payload does not satisfy the event's schema (missing required field, wrong type, etc.):

{
  "status_code": 422,
  "name": "validation_error",
  "message": "Payload does not match the \"order.completed\" schema."
}

401 Unauthorized

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