SMS API Documentation

Base URL: https://api.sms.com.na

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: App YOUR_API_KEY

Getting Your API Key

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

Send SMS Messages

POST /sms/3/messages

Send one or more SMS messages to specified destinations.

Request Headers

Request Body

{
  "messages": [
    {
      "from": "SMS.COM.NA",
      "destinations": [
        {"to": "264811234567"},
        {"to": "264812345678"}
      ],
      "text": "Your message text here",
      "notifyUrl": "https://your-domain.com/delivery-webhook",
      "notifyContentType": "application/json",
      "callbackData": "custom-reference-123"
    }
  ]
}

Parameters

Response (200 OK)

{
  "messages": [
    {
      "to": "264811234567",
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 26,
        "name": "MESSAGE_ACCEPTED",
        "description": "Message sent to next instance"
      },
      "messageId": "12345678-1234-1234-1234-123456789012"
    },
    {
      "to": "264812345678",
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 26,
        "name": "MESSAGE_ACCEPTED",
        "description": "Message sent to next instance"
      },
      "messageId": "12345678-1234-1234-1234-123456789013"
    }
  ]
}

cURL Example

curl -X POST https://api.sms.com.na/sms/3/messages \
  -H "Authorization: App YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourBrand",
      "destinations": [{"to": "264811234567"}],
      "text": "Hello from SMS.COM.NA!"
    }]
  }'

Delivery Reports

GET /sms/3/reports

Retrieve delivery reports for sent messages.

Query Parameters

Response (200 OK)

{
  "results": [
    {
      "messageId": "12345678-1234-1234-1234-123456789012",
      "to": "264811234567",
      "from": "YourBrand",
      "text": "Hello from SMS.COM.NA!",
      "sentAt": "2026-06-25T10:30:00.000+0000",
      "doneAt": "2026-06-25T10:30:05.000+0000",
      "smsCount": 1,
      "price": {
        "pricePerMessage": 0.50,
        "currency": "NAD"
      },
      "status": {
        "groupId": 3,
        "groupName": "DELIVERED",
        "id": 5,
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset"
      },
      "error": null,
      "callbackData": "custom-reference-123"
    }
  ]
}

cURL Example

curl -X GET "https://api.sms.com.na/sms/3/reports?limit=100" \
  -H "Authorization: App YOUR_API_KEY"

Message Logs

GET /sms/3/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 SMS.COM.NA!",
      "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://api.sms.com.na/sms/3/logs?limit=50" \
  -H "Authorization: App YOUR_API_KEY"

Message Preview

POST /sms/3/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",
  "previews": [
    {
      "textPreview": "Your message text here",
      "messageCount": 1,
      "charactersRemaining": 137,
      "configuration": {}
    }
  ]
}

Scheduled Messages

GET /sms/3/bulks

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://api.sms.com.na/sms/3/messages"
headers = {
    "Authorization": "App 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://api.sms.com.na/sms/3/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: App 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://api.sms.com.na/sms/3/messages';
const headers = {
    'Authorization': 'App 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", "App 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://api.sms.com.na/sms/3/messages", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);