Basic SMS API Documentation

Base URL: https://{host}/api/http/main.ashx

The Basic SMS API provides simple HTTP GET/POST endpoints for sending SMS messages, retrieving incoming messages, and checking delivery status.

Authentication

All API requests require authentication using an API key. The recommended method is to pass the API key in the request header:

Recommended: Header-Based Authentication

Pass your API key in the X-API-Key header:

X-API-Key: your-api-key-here

Alternatively, you can use the Authorization header with Bearer or ApiKey prefix:

Authorization: Bearer your-api-key-here
# OR
Authorization: ApiKey your-api-key-here

Alternative: Username/Password Authentication

For legacy integrations, you can authenticate using username, password, and client ID as form/query parameters:

username=your-email@example.com
password=your-password
clientid=12345

Getting Your API Key

1. Log in to the SMSDESK Portal
2. Navigate to your SMS Channel settings
3. Click "Generate" to create a new secure API key
4. Copy and store your API key securely

Send SMS Messages

Send one or more SMS messages using the sendsms action.

Endpoint

POST /api/http/main.ashx

GET /api/http/main.ashx

Request Headers

Parameters

* At least one recipient parameter (to/mobile/msisdn/recipient) and one message parameter (msg/message/body) required

Response Format

The API returns a pipe-delimited response with status in both body and headers:

success|{sms_id}:{recipient}:{status}|{sms_id}:{recipient}:{status}

Response Headers

• sms_api_response: Overall status (success/error/partial_success)
• sms_recipient_1, sms_recipient_2, etc.: Individual recipient results

Status Values

• success: All messages queued successfully
• error: All messages failed
• partial_success: Some messages succeeded, some failed

cURL Example (POST with Header)

curl -X POST https://{host}/api/http/main.ashx \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "to=264811234567&msg=Hello from SMSDESK!"

cURL Example (Multiple Recipients)

curl -X POST https://{host}/api/http/main.ashx \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "to=264811234567,264812345678&msg=Bulk message&ref=BATCH-001"

Success Response Example

success|12345:264811234567:PENDING|12346:264812345678:PENDING

Error Response Example

ERR-SENDSMS-01: TO or MSISDN or MOBILE or RECIPIENT List of recipients (mobile numbers) NOT GIVEN

Retrieve Incoming Messages

Retrieve incoming SMS messages received on your channels.

Endpoint

GET /api/http/main.ashx?action=incoming

Request Headers

Query Parameters

cURL Example

curl -X GET "https://{host}/api/http/main.ashx?action=incoming&rows=50&format=json" \
  -H "X-API-Key: your-api-key-here"

Response Example (JSON)

[
  {
    "id": "12345",
    "sender": "264811234567",
    "channel": "33333",
    "message": "Hello",
    "timestamp": "2026-07-10 14:30:00",
    "status": "1"
  }
]

Check Message Status

Check the delivery status of sent messages.

Endpoint

GET /api/http/main.ashx?action=status

Request Headers

Query Parameters

cURL Example

curl -X GET "https://{host}/api/http/main.ashx?action=status&msgid_list=12345,12346" \
  -H "X-API-Key: your-api-key-here"

Response Format

{msgid}:{mobile}:{status}:{status_date_unix}:{delivery_status}:{delivery_date_unix}

Response Example

12345:264811234567:DELIVERED:1720618200:DELIVERED:1720618205|12346:264812345678:PENDING:1720618200:PENDING:0

Error Codes

The API returns error messages in plain text format with error codes.

Common Error Codes

Code Examples

Python Example

import requests

url = "https://{host}/api/http/main.ashx"
headers = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/x-www-form-urlencoded"
}
data = {
    "to": "264811234567",
    "msg": "Hello from Python!",
    "ref": "PY-001"
}

response = requests.post(url, headers=headers, data=data)
print(response.text)
print(response.headers.get('sms_api_response'))

PHP Example

<?php
$url = "https://{host}/api/http/main.ashx";
$data = http_build_query([
    "to" => "264811234567",
    "msg" => "Hello from PHP!",
    "ref" => "PHP-001"
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: your-api-key-here",
    "Content-Type: application/x-www-form-urlencoded"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, true);

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

echo $response;
?>

JavaScript (Node.js) Example

const axios = require('axios');
const querystring = require('querystring');

const url = 'https://{host}/api/http/main.ashx';
const headers = {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/x-www-form-urlencoded'
};
const data = querystring.stringify({
    to: '264811234567',
    msg: 'Hello from Node.js!',
    ref: 'NODE-001'
});

axios.post(url, data, {headers})
    .then(response => {
        console.log(response.data);
        console.log('Status:', response.headers['sms_api_response']);
    })
    .catch(error => console.error(error));

C# Example

using System;
using System.Net.Http;
using System.Collections.Generic;
using System.Threading.Tasks;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your-api-key-here");

var data = new FormUrlEncodedContent(new Dictionary<string, string>
{
    {"to", "264811234567"},
    {"msg", "Hello from C#!"},
    {"ref", "CS-001"}
});

var response = await client.PostAsync(
    "https://{host}/api/http/main.ashx", 
    data
);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

if (response.Headers.Contains("sms_api_response"))
{
    var status = response.Headers.GetValues("sms_api_response");
    Console.WriteLine($"Status: {string.Join(", ", status)}");
}

Java Example

import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

String data = "to=264811234567&msg=Hello from Java!&ref=JAVA-001";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://{host}/api/http/main.ashx"))
    .header("X-API-Key", "your-api-key-here")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .POST(HttpRequest.BodyPublishers.ofString(data))
    .build();

HttpResponse<String> response = client.send(request, 
    HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
System.out.println("Status: " + response.headers()
    .firstValue("sms_api_response").orElse("N/A"));