API Reference

The Arsel API provides RESTful endpoints for managing contacts, sending transactional and campaign email, SMS, WhatsApp and push, and organizing recipients with lists, tags and segments. All endpoints use JSON request and response bodies.

Base URL

https://api.arsel.sa/v1

OpenAPI specification

The whole API is described by an OpenAPI 3.0 document, served without authentication:

https://api.arsel.sa/v1/openapi.json

Import it into Postman or Insomnia, or feed it to a client generator, to work with typed requests and responses instead of hand-written calls.

Email Endpoints

Method	Endpoint	Description
POST	/email/send	Send a transactional email
GET	/email	List sent emails with delivery status
GET	/email/:id	Get detailed status for a specific email
POST	/email/domains	Register a sending domain and get its DNS records
GET	/email/domains	List sending domains and their verification status
GET	/email/domains/:id	Get a sending domain and its DNS records
POST	/email/domains/:id/verify	Check a domain's DNS records now
DELETE	/email/domains/:id	Delete a sending domain

Verified Domain Required

All email sending requires a verified domain. Verify your domain with the endpoints above, or in the Arsel Dashboard under Domains, before sending.

Email Campaign Endpoints

Method	Endpoint	Description
POST	/email/campaigns	Create an email campaign
GET	/email/campaigns	List email campaigns
GET	/email/campaigns/:id	Get an email campaign
PATCH	/email/campaigns/:id	Update an email campaign
DELETE	/email/campaigns/:id	Delete an email campaign
POST	/email/campaigns/:id/send	Send or schedule an email campaign
POST	/email/campaigns/:id/cancel	Cancel an email campaign
GET	/email/campaigns/:id/stats	Get delivery and engagement stats for an email campaign

SMS Endpoints

Method	Endpoint	Description
POST	/sms/send	Send a transactional SMS
GET	/sms	List sent SMS messages with delivery status
GET	/sms/:id	Get detailed status for a specific SMS
GET	/sms/senders	List approved SMS sender names

Verified Sender Name Required

All SMS sending requires a registered sender name. Sender names are provisioned by Arsel on your behalf — contact support@arsel.sa to register one.

SMS Campaign Endpoints

Method	Endpoint	Description
POST	/sms/campaigns	Create an SMS campaign
GET	/sms/campaigns	List SMS campaigns
GET	/sms/campaigns/:id	Get an SMS campaign
PATCH	/sms/campaigns/:id	Update an SMS campaign
DELETE	/sms/campaigns/:id	Delete an SMS campaign
POST	/sms/campaigns/:id/send	Send or schedule an SMS campaign
POST	/sms/campaigns/:id/cancel	Cancel an SMS campaign
GET	/sms/campaigns/:id/stats	Get delivery and engagement stats for an SMS campaign

WhatsApp Endpoints

WhatsApp messages must be sent from a template Meta has approved — business-initiated free text is not allowed.

Method	Endpoint	Description
POST	/whatsapp/send	Send a transactional WhatsApp message
GET	/whatsapp	List transactional WhatsApp messages
GET	/whatsapp/:id	Get delivery status for a specific message
GET	/whatsapp/campaigns/:id/stats	Get delivery and engagement stats for a WhatsApp campaign
POST	/whatsapp/templates	Create a template and submit it to Meta
GET	/whatsapp/templates	List templates
GET	/whatsapp/templates/:id	Get a template and its approval status
PATCH	/whatsapp/templates/:id	Edit a template and resubmit it
DELETE	/whatsapp/templates/:id	Delete a template

Push Notification Endpoints

Method	Endpoint	Description
POST	/push/send	Send a transactional push to one contact
GET	/push	List transactional pushes
GET	/push/:id	Get a transactional push and how many devices it reached
POST	/push/devices	Register a device
POST	/push/devices/bulk	Import up to 1,000 devices
GET	/push/imports/:job_id	Poll a device import
POST	/push/devices/unregister	Revoke a device
GET	/push/contacts/:contact_id/devices	List a contact's devices

Most integrations register devices through a Client SDK rather than these endpoints — delivery and engagement metrics are reported by the SDK on the device.

Push Notification Campaign Endpoints

Method	Endpoint	Description
POST	/push/campaigns	Create a push campaign
GET	/push/campaigns	List push campaigns
GET	/push/campaigns/:id	Get a push campaign
PATCH	/push/campaigns/:id	Update a push campaign
DELETE	/push/campaigns/:id	Delete a push campaign
POST	/push/campaigns/:id/send	Send or schedule a push campaign
POST	/push/campaigns/:id/cancel	Cancel a push campaign
GET	/push/campaigns/:id/stats	Get delivery and engagement stats for a push campaign

Event Endpoints

Custom events let you trigger automations and conversion reporting from your own product activity. Define an event once, then send occurrences against it.

Method	Endpoint	Description
POST	/events	Define a custom event (name + payload schema)
GET	/events	List event definitions
GET	/events/:id	Get an event definition
PATCH	/events/:id	Update an event definition
DELETE	/events/:id	Delete an event definition
POST	/events/send	Send (ingest) an event for a contact, or a batch of up to 50

Contact Endpoints

Method	Endpoint	Description
POST	/contacts	Create a new contact
GET	/contacts	List contacts, or find one by email, phone or external ID
GET	/contacts/:id	Get a specific contact
PATCH	/contacts/:id	Update a contact
DELETE	/contacts/:id	Delete a contact
POST	/contacts/bulk-delete	Bulk delete up to 1,000 contacts

List Endpoints

Method	Endpoint	Description
POST	/lists	Create a contact list
GET	/lists	List all contact lists
GET	/lists/:id	Get a specific list
PATCH	/lists/:id	Update a list
DELETE	/lists/:id	Delete a list
POST	/lists/:id/contacts	Add contacts to a list
DELETE	/lists/:id/contacts	Remove contacts from a list

Tag Endpoints

Method	Endpoint	Description
POST	/tags	Create a tag
GET	/tags	List all tags
GET	/tags/:id	Get a specific tag
PATCH	/tags/:id	Update a tag
DELETE	/tags/:id	Delete a tag
POST	/tags/:id/contacts	Apply a tag to contacts
DELETE	/tags/:id/contacts	Remove a tag from contacts

Segment Endpoints

Segments are dynamic audiences defined by rules, written as a filter. Create them here or in the dashboard, and target one from a campaign.

Method	Endpoint	Description
POST	/segments	Create a segment
GET	/segments	List all segments
GET	/segments/:id	Get a specific segment
PATCH	/segments/:id	Update a segment
DELETE	/segments/:id	Delete a segment
GET	/contacts?segment_id=	List the contacts in a segment

Custom Template Endpoints

Method	Endpoint	Description
POST	/templates	Create an email template
GET	/templates	List templates
GET	/templates/:id	Get a specific template
PATCH	/templates/:id	Update a template
DELETE	/templates/:id	Delete a template

Template Gallery Endpoints

Method	Endpoint	Description
GET	/templates/gallery	Browse the starter-template gallery
GET	/templates/gallery/categories	List gallery filter values
GET	/templates/gallery/:id	Get a gallery template (with HTML)
POST	/templates/gallery/:id/copy	Copy a gallery template into your custom templates

Property Endpoints

Method	Endpoint	Description
POST	/properties	Create a custom property
GET	/properties	List custom properties
GET	/properties/:id	Get a specific property
PATCH	/properties/:id	Update a property
DELETE	/properties/:id	Delete a property

Usage Endpoints

Method	Endpoint	Description
GET	/usage	Get this month's usage against your plan limits

Common Headers

Header	Value	When
Authorization	Bearer <your-api-key>	Every request
Content-Type	application/json	Requests with a body
Idempotency-Key	A unique string, max 256 chars	Optional, on send endpoints — see Idempotency

Response Conventions

Sending endpoints return 202 Accepted with the message ID. Use this ID with the status endpoints to track delivery progress.

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

Create endpoints return 201 Created. Campaign create endpoints return { id } only — use GET /:id to fetch the full record. Other create endpoints return the full created resource.

List endpoints return 200 OK with cursor-paginated results:

{
  "object": "list",
  "has_more": true,
  "data": []
}

See Pagination for cursor parameters (limit, after, before) and walking strategies.

Error responses follow a consistent format across all endpoints. See Errors for details.