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 and tags. All endpoints use JSON request and response bodies.

Base URL

https://api.arsel.sa/v1

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

Verified Domain Required

All email sending requires a verified domain. Verify your domain in the Arsel Dashboard under Settings > 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

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

Verified Sender Name Required

All SMS sending requires a registered sender name. Register your sender name in the Arsel Dashboard under Settings > SMS Senders before sending.

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

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

Push Notification Endpoints

Method	Endpoint	Description
POST	/push/send	Send a transactional push to one contact
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/: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

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 with search, filter, and sort
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

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

Common Headers

Every request must include:

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

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.