Mora SMS API

🚀 Introduction

Welcome to the Mora SMS API documentation. Our RESTful API allows you to integrate SMS functionality into your applications with ease. Whether you need to send notifications, verification codes, or marketing messages, our API provides reliable and fast delivery.

Key Features

• Send SMS messages to single or multiple recipients
• Schedule messages for future delivery
• Check account balance in real-time
• Manage sender names
• Comprehensive error handling
• JSON and text response formats

🔐 Authentication

All API requests require authentication using your unique api_key and username. These parameters must be included in every request.

https://mora-sa.com/api/v1/sendsms?api_key=your_api_key&username=your_username

📱 Sending SMS

Send SMS messages to one or multiple recipients using the /sendsms endpoint.

Endpoint

https://mora-sa.com/api/v1/sendsms

Parameters

Code Examples

curl -X POST "https://mora-sa.com/api/v1/sendsms" \
      -d "api_key=your_api_key" \
      -d "username=your_username" \
      -d "message=Hello from Mora SMS API!" \
      -d "sender=YourApp" \
      -d "numbers=966501234567,966507654321" \
      -d "return=json"

<?php
    $url = 'https://mora-sa.com/api/v1/sendsms';
    $data = array(
        'api_key' => 'your_api_key',
        'username' => 'your_username',
        'message' => 'Hello from Mora SMS API!',
        'sender' => 'YourApp',
        'numbers' => '966501234567,966507654321',
        'return' => 'json'
    );
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    echo $response;
    ?>

import requests
    
url = 'https://mora-sa.com/api/v1/sendsms'
data = {
    'api_key': 'your_api_key',
    'username': 'your_username',
    'message': 'Hello from Mora SMS API!',
    'sender': 'YourApp',
    'numbers': '966501234567,966507654321',
    'return': 'json'
}

response = requests.post(url, data=data)
print(response.json())

const data = new URLSearchParams({
    api_key: 'your_api_key',
    username: 'your_username',
    message: 'Hello from Mora SMS API!',
    sender: 'YourApp',
    numbers: '966501234567,966507654321',
    return: 'json'
});

fetch('https://mora-sa.com/api/v1/sendsms', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: data
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

💰 Balance Inquiry

Check your account balance using the /balance endpoint.

Endpoint

https://mora-sa.com/api/v1/balance

Code Examples

curl "https://mora-sa.com/api/v1/balance?api_key=your_api_key&username=your_username"

<?php
    $url = 'https://mora-sa.com/api/v1/balance';
    $params = array(
        'api_key' => 'your_api_key',
        'username' => 'your_username'
    );
    
    $url .= '?' . http_build_query($params);
    $response = file_get_contents($url);
    echo $response;
    ?>

import requests
    
url = 'https://mora-sa.com/api/v1/balance'
params = {
    'api_key': 'your_api_key',
    'username': 'your_username'
}

response = requests.get(url, params=params)
print(response.json())

const params = new URLSearchParams({
    api_key: 'your_api_key',
    username: 'your_username'
});

fetch(`https://mora-sa.com/api/v1/balance?${params}`)
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

👤 Sender Names

Retrieve available sender names for your account using the /sender_names endpoint.

Endpoint

https://mora-sa.com/api/v1/sender_names

Code Examples

curl "https://mora-sa.com/api/v1/sender_names?api_key=your_api_key&username=your_username"

<?php
    $url = 'https://mora-sa.com/api/v1/sender_names';
    $params = array(
        'api_key' => 'your_api_key',
        'username' => 'your_username'
    );
    
    $url .= '?' . http_build_query($params);
    $response = file_get_contents($url);
    echo $response;
    ?>

import requests
    
url = 'https://mora-sa.com/api/v1/sender_names'
params = {
    'api_key': 'your_api_key',
    'username': 'your_username'
}

response = requests.get(url, params=params)
print(response.json())

const params = new URLSearchParams({
    api_key: 'your_api_key',
    username: 'your_username'
});

fetch(`https://mora-sa.com/api/v1/sender_names?${params}`)
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

⚠️ Error Codes

The API returns specific error codes to help you troubleshoot issues. Here's a complete list of possible response codes:

🔗 Webhook Integration

The platform can push the status of every message you send to a URL of your own (your "webhook"). Instead of polling the API, you receive an HTTP POST with the message and its per-number statuses.

1. Enable your webhook

1. Log in to the portal and open API Keys (/api_keys).
2. In the Webhook Settings card, enter your endpoint URL.
3. Press Activate. (To stop receiving calls, press Disable on the same card).

URL Requirements

2. What we send

A single POST per message, with Content-Type: application/json.

{
  "msg_id": 8842137,
  "sending_time": "2026-08-24 10:15:32",
  "numbers_count": 3,
  "status": "delivered",
  "numbers": [
    { "number": "966500000001", "status": "delivered" },
    { "number": "966500000002", "status": "sending" },
    { "number": "966500000003", "status": "failed", "response": "رقم الجوال خطأ" }
  ]
}

Payload Fields

Status Values

3. How your endpoint must behave

• Answer 2xx: Any other status code (4xx, 5xx), a redirect, a TLS error, or a timeout is treated as a delivery failure.
• Answer fast: Timeouts are 5 s to connect and 10 s in total. Queue the payload and process it asynchronously - don't do slow work in the handler.
• Be idempotent: A call may repeat (for example if we time out after your server already processed it). Deduplicate on msg_id.
• Ordering: Don't rely on ordering guarantees beyond msg_id. Messages are pushed in ascending msg_id order, one at a time.

Securing your endpoint

No signature or authorization header is sent. Protect the endpoint by:

• Using a long unguessable path or query token, e.g., https://example.com/hooks/sms/9f2c1b7e5a..., and rejecting anything else.
• Serving it over HTTPS.
• Optionally allowlisting the platform's outbound IP address.

4. Delivery, retries and auto-disable

Each message is pushed once, shortly after it is created - the payload shows the statuses as they are at that moment, not a final report.

5. Example receivers

<?php
// https://example.com/hooks/sms/<secret>
if (($_GET['token'] ?? '') !== 'YOUR_SECRET') {
    http_response_code(404);
    exit;
}

$payload = json_decode(file_get_contents('php://input'), true);
http_response_code(200); // answer first, work later
fastcgi_finish_request();

foreach ($payload['numbers'] as $n) {
    // store/update by $payload['msg_id'] + $n['number']
    // $n['status'], $n['response'] ?? null
}
?>

// routes/api.php
Route::post('hooks/sms/{token}', function (Request $request, $token) {
    abort_unless(hash_equals(config('services.sms.hook_token'), $token), 404);
    ProcessSmsWebhook::dispatch($request->all()); // queue it
    return response()->json(['ok' => true]);
});

app.post('/hooks/sms/:token', express.json(), (req, res) => {
    if (req.params.token !== process.env.SMS_HOOK_TOKEN) return res.sendStatus(404);
    
    res.sendStatus(200); // ack immediately
    queue.add('sms-status', req.body);
});

6. Webhook log

Every delivery attempt is recorded and shown in the portal under API Keys → Webhook Log (/webhook/logs). Each row holds the time, the message id (linking to the message), whether the call succeeded, the HTTP status code your endpoint returned, how long it took, and the error text when it failed. You can filter by outcome (delivered / failed) or by a specific message id.

Attempts are kept for 7 days and pruned automatically.

Use it to answer the usual questions without contacting support: did the call reach my server? (a row exists), what did my server answer? (HTTP Code), why was my webhook disabled? (a run of failed rows), and is my endpoint too slow? (Duration approaching 10 000 ms).

7. Troubleshooting