SMS API Documentation

Base URL: https://{host}

The SMS API allows you to send SMS messages, retrieve delivery reports, view message logs, and manage scheduled messages programmatically.

Authentication

All API requests require authentication using an API key in the Authorization header:

Authorization: YOUR_API_KEY

Getting Your API Key

1. Log in to the SMSDESK Portal
2. Navigate to Settings → API Keys
3. Generate a new API key or copy your existing key

Send SMS Messages

POST /sms/2/messages

Send one or more SMS messages to specified destinations.

Request Headers

Request Body

{
  "bulkId": "BULK-20260701-001",
  "messages": [
    {
      "from": "YourBrand",
      "destinations": [
        {"to": "+264811234567"},
        {"to": "+264812345678"}
      ],
      "text": "Your message text here",
      "sendAt": "2026-07-01T15:00:00.000Z",
      "options": {
        "flash": false
      },
      "includeSmsCountInResponse": true
    }
  ]
}

Parameters

Response (200 OK)

{
  "bulkId": "BULK-20260701-001",
  "messages": [
    {
      "to": "+264811234567",
      "from": "33333",
      "messageId": "12345678-1234-1234-1234-123456789012",
      "smsCount": 1,
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 26,
        "name": "PENDING_ACCEPTED",
        "description": "Message sent to next instance"
      }
    },
    {
      "to": "+264812345678",
      "from": "33333",
      "messageId": "12345678-1234-1234-1234-123456789013",
      "smsCount": 1,
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 26,
        "name": "PENDING_ACCEPTED",
        "description": "Message sent to next instance"
      }
    }
  ]
}

cURL Example

curl -X POST https://{host}/sms/2/messages \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "destinations": [{"to": "+264811234567"}],
      "text": "Hello from SMSDESK!"
    }]
  }'

Delivery Reports

GET /sms/2/reports

Retrieve delivery reports for sent messages. Use this endpoint to check the delivery status of your SMS messages.

Query Parameters

Response (200 OK)

{
  "results": [
    {
      "smsId": 123456,
      "bulkId": "BULK-20260701-001",
      "messageId": "12345678-1234-1234-1234-123456789012",
      "to": "264811234567",
      "sentAt": "2026-06-25T10:30:00.000+0000",
      "doneAt": "2026-06-25T10:30:05.000+0000",
      "scheduledTime": null,
      "smsCount": 1,
      "price": {
        "pricePerMessage": 0.50,
        "currency": "NAD"
      },
      "statusCode": 3,
      "axStatusDesk": "DELIVRD",
      "status": {
        "groupId": 3,
        "groupName": "DELIVERED",
        "id": 5,
        "name": "DELIVERED",
        "description": "Message delivered to handset"
      },
      "error": null
    }
  ]
}

cURL Examples

Get all recent delivery reports:

curl -X GET "https://{host}/sms/2/reports?limit=100" \
  -H "Authorization: YOUR_API_KEY"

Check status by internal SMS ID:

curl -X GET "https://{host}/sms/2/reports?smsId=123456" \
  -H "Authorization: YOUR_API_KEY"

Check status by external message ID:

curl -X GET "https://{host}/sms/2/reports?messageId=12345678-1234-1234-1234-123456789012" \
  -H "Authorization: YOUR_API_KEY"

Get delivery reports for a bulk batch:

curl -X GET "https://{host}/sms/2/reports?bulkId=BULK-20260701-001" \
  -H "Authorization: YOUR_API_KEY"

Message Logs

GET /sms/2/logs

View logs of sent messages with filtering options.

Query Parameters

Response (200 OK)

{
  "results": [
    {
      "messageId": "12345678-1234-1234-1234-123456789012",
      "to": "264811234567",
      "from": "YourBrand",
      "text": "Hello from SMSDESK!",
      "sentAt": "2026-06-25T10:30:00.000+0000",
      "status": {
        "groupId": 3,
        "groupName": "DELIVERED",
        "id": 5,
        "name": "DELIVERED_TO_HANDSET"
      },
      "smsCount": 1,
      "price": {
        "pricePerMessage": 0.50,
        "currency": "NAD"
      }
    }
  ]
}

cURL Example

curl -X GET "https://{host}/sms/2/logs?limit=50" \
  -H "Authorization: YOUR_API_KEY"

Message Preview

POST /sms/2/preview

Preview message details before sending (character count, number of SMS parts, etc.).

Request Body

{
  "text": "Your message text here"
}

Response (200 OK)

{
  "originalText": "Your message text here",
  "textPreview": "Your message text here",
  "messageCount": 1,
  "charactersRemaining": 137,
  "configuration": {
    "language": {
      "languageCode": "EN"
    },
    "transliteration": null
  }
}

Scheduled Messages

GET /sms/2/bulks

PUT /sms/2/bulks - Reschedule messages

DELETE /sms/2/bulks - Cancel scheduled messages

View scheduled messages that are queued for future delivery.

Response (200 OK)

{
  "bulks": [
    {
      "bulkId": "bulk-12345",
      "sendAt": "2026-06-26T09:00:00.000+0000"
    }
  ]
}

Error Codes

The API uses standard HTTP status codes and returns detailed error messages in JSON format.

Common Error Responses

Error Response Format

{
  "requestError": {
    "serviceException": {
      "messageId": "BAD_REQUEST",
      "text": "Invalid request parameters",
      "validationErrors": {
        "from": "Sender ID is required"
      }
    }
  }
}

Code Examples

Python Example

import requests
import json

url = "https://{host}/sms/2/messages"
headers = {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "messages": [{
        "from": "YourBrand",
        "destinations": [{"to": "264811234567"}],
        "text": "Hello from Python!"
    }]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

PHP Example

<?php
$url = "https://{host}/sms/2/messages";
$data = [
    "messages" => [[
        "from" => "YourBrand",
        "destinations" => [["to" => "264811234567"]],
        "text" => "Hello from PHP!"
    ]]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

JavaScript (Node.js) Example

const axios = require('axios');

const url = 'https://{host}/sms/2/messages';
const headers = {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
};
const data = {
    messages: [{
        from: 'YourBrand',
        destinations: [{to: '264811234567'}],
        text: 'Hello from Node.js!'
    }]
};

axios.post(url, data, {headers})
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

C# Example

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "YOUR_API_KEY");

var json = @"{
    ""messages"": [{
        ""from"": ""YourBrand"",
        ""destinations"": [{""to"": ""264811234567""}],
        ""text"": ""Hello from C#!""
    }]
}";

var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://{host}/sms/2/messages", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);