Email Status

Track the delivery status of your transactional emails. List all sent emails with aggregate status counts, or get per-recipient delivery details for a specific email.

List Emails

Retrieve a paginated list of transactional emails sent by your organization.

Endpoint

GET /email

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	20	Results per page

Response

{
  "data": [
    {
      "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
      "from": "noreply@yourdomain.com",
      "from_name": "My App",
      "subject": "Welcome to our platform",
      "category": "welcome",
      "status": {
        "sent": 1,
        "delivered": 1,
        "opened": 0,
        "bounced": 0,
        "complained": 0
      },
      "created_at": "2026-03-08T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Status Fields

Field	Description
sent	Messages accepted by the mail provider
delivered	Messages confirmed delivered to the recipient's inbox
opened	Unique opens tracked
bounced	Messages that bounced (hard or soft)
complained	Recipients who marked the email as spam

tip

The subject field returns null if the email content has been purged (content retention policy).

---

Examples

cURL

curl "https://api.arsel.sa/api/v1/email?page=1&limit=10" \
  -H "Authorization: Bearer be_your_api_key"

JavaScript

const response = await fetch(
  "https://api.arsel.sa/api/v1/email?page=1&limit=10",
  {
    headers: { Authorization: "Bearer be_your_api_key" },
  }
);

const { data, meta } = await response.json();
console.log(`Showing ${data.length} of ${meta.total} emails`);

for (const email of data) {
  console.log(`${email.id}: ${email.status.delivered} delivered, ${email.status.bounced} bounced`);
}

Python

import requests

response = requests.get(
    "https://api.arsel.sa/api/v1/email",
    headers={"Authorization": "Bearer be_your_api_key"},
    params={"page": 1, "limit": 10},
)

result = response.json()
for email in result["data"]:
    status = email["status"]
    print(f"{email['id']}: {status['delivered']} delivered, {status['bounced']} bounced")

C#

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

var response = await client.GetAsync("https://api.arsel.sa/api/v1/email?page=1&limit=10");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/api/v1/email?page=1&limit=10");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);

foreach ($data["data"] as $email) {
    $status = $email["status"];
    echo "{$email['id']}: {$status['delivered']} delivered, {$status['bounced']} bounced\n";
}
curl_close($ch);

---

Get Email Details

Retrieve detailed delivery status for a specific email, including per-recipient tracking.

Endpoint

GET /email/:id

Path Parameters

Parameter	Type	Description
id	string	The email ID returned from POST /email/send

Response

{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
  "from": "noreply@yourdomain.com",
  "from_name": "My App",
  "to": [
    {
      "email": "user@example.com",
      "status": "delivered",
      "timestamp": "2026-03-08T12:00:05.000Z"
    },
    {
      "email": "other@example.com",
      "status": "bounced",
      "timestamp": "2026-03-08T12:00:03.000Z"
    }
  ],
  "subject": "Welcome to our platform",
  "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  "text": null,
  "reply_to": null,
  "category": "welcome",
  "attachments": [
    {
      "filename": "guide.pdf",
      "size": 204800,
      "content_type": "application/pdf"
    }
  ],
  "created_at": "2026-03-08T12:00:00.000Z"
}

Recipient Status Values

Status	Description
sent	Accepted by the mail provider, delivery pending
delivered	Confirmed delivered to the recipient's inbox
opened	Recipient opened the email
clicked	Recipient clicked a link in the email
bounced	Delivery failed (address doesn't exist or mailbox full)
complained	Recipient reported the email as spam
rejected	The mail provider rejected the message
unsubscribed	Recipient unsubscribed via the email's unsubscribe link
render_failure	The email template failed to render

Examples

cURL

curl "https://api.arsel.sa/api/v1/email/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a" \
  -H "Authorization: Bearer be_your_api_key"

JavaScript

const emailId = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a";

const response = await fetch(`https://api.arsel.sa/api/v1/email/${emailId}`, {
  headers: { Authorization: "Bearer be_your_api_key" },
});

const email = await response.json();
for (const recipient of email.to) {
  console.log(`${recipient.email}: ${recipient.status}`);
}

Python

import requests

email_id = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a"

response = requests.get(
    f"https://api.arsel.sa/api/v1/email/{email_id}",
    headers={"Authorization": "Bearer be_your_api_key"},
)

email = response.json()
for recipient in email["to"]:
    print(f"{recipient['email']}: {recipient['status']}")

C#

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

var emailId = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a";
var response = await client.GetAsync($"https://api.arsel.sa/api/v1/email/{emailId}");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

PHP

<?php
$emailId = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a";
$ch = curl_init("https://api.arsel.sa/api/v1/email/{$emailId}");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$email = json_decode($response, true);

foreach ($email["to"] as $recipient) {
    echo "{$recipient['email']}: {$recipient['status']}\n";
}
curl_close($ch);