API Reference

The Arsel API provides RESTful endpoints for managing contacts, sending transactional and campaign email and SMS, 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

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.