API v1 Documentation

Legacy

Version 1 uses username and password authentication. This is the legacy API version.

Overview

Base URL
https://ugsms.com/v1
Authentication

Include username and password in either:

  • Request body (JSON)
  • Query parameters
Response Format
{
    "success": true,
    "message": "Message sent successfully",
    "data": {
        "message_id": "uuid",
        "recipients": 2,
        "estimated_cost": 20.0,
        "remaining_balance": 980.0
    }
}

Send SMS

POST /v1/sms/send (GET also supported)

Send SMS to one or multiple Ugandan mobile numbers.

Request Parameters
Parameter Type Required Description Example
username String Yes Your UGSMS username john_doe
password String Yes Your UGSMS password secret123
numbers String Yes Comma-separated phone numbers 0702913454,0776913451
message_body String Yes SMS message content Hello from UGSMS
sender_id String No Sender ID (max 11 chars) UGSMS
Example Request
curl -X POST "https://ugsms.com/v1/sms/send" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password",
    "numbers": "0702913454,0776913451",
    "message_body": "Hello from UGSMS API v1",
    "sender_id": "UGSMS"
  }'
fetch('https://ugsms.com/v1/sms/send', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        username: 'your_username',
        password: 'your_password',
        numbers: '0702913454,0776913451',
        message_body: 'Hello from UGSMS API v1',
        sender_id: 'UGSMS'
    })
})
.then(response => response.json())
.then(data => console.log(data));
$data = [
    'username' => 'your_username',
    'password' => 'your_password',
    'numbers' => '0702913454,0776913451',
    'message_body' => 'Hello from UGSMS API v1',
    'sender_id' => 'UGSMS'
];

$ch = curl_init('https://ugsms.com/v1/sms/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

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

$result = json_decode($response, true);
print_r($result);
import requests
import json

url = "https://ugsms.com/v1/sms/send"
data = {
    "username": "your_username",
    "password": "your_password",
    "numbers": "0702913454,0776913451",
    "message_body": "Hello from UGSMS API v1",
    "sender_id": "UGSMS"
}

response = requests.post(url, json=data)
result = response.json()
print(result)
#include <stdio.h>
#include <curl/curl.h>
#include <string.h>

struct MemoryStruct {
    char *memory;
    size_t size;
};

static size_t WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp) {
    size_t realsize = size * nmemb;
    struct MemoryStruct *mem = (struct MemoryStruct *)userp;

    char *ptr = realloc(mem->memory, mem->size + realsize + 1);
    if(!ptr) {
        return 0;
    }

    mem->memory = ptr;
    memcpy(&(mem->memory[mem->size]), contents, realsize);
    mem->size += realsize;
    mem->memory[mem->size] = 0;

    return realsize;
}

int main(void) {
    CURL *curl;
    CURLcode res;

    char *url = "https://ugsms.com/v1/sms/send";

    struct MemoryStruct chunk;
    chunk.memory = malloc(1);
    chunk.size = 0;

    curl = curl_easy_init();
    if(curl) {
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Content-Type: application/json");

        char *json_data = "{\"username\":\"your_username\",\"password\":\"your_password\",\"numbers\":\"0702913454,0776913451\",\"message_body\":\"Hello from UGSMS API v1\",\"sender_id\":\"UGSMS\"}";

        curl_easy_setopt(curl, CURLOPT_URL, url);
        curl_easy_setopt(curl, CURLOPT_POST, 1L);
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json_data);
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteMemoryCallback);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);

        res = curl_easy_perform(curl);

        if(res == CURLE_OK) {
            printf("%s\n", chunk.memory);
        } else {
            fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res));
        }

        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
        free(chunk.memory);
    }

    return 0;
}
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var url = "https://ugsms.com/v1/sms/send";

        var data = new
        {
            username = "your_username",
            password = "your_password",
            numbers = "0702913454,0776913451",
            message_body = "Hello from UGSMS API v1",
            sender_id = "UGSMS"
        };

        var json = JsonSerializer.Serialize(data);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        using (var client = new HttpClient())
        {
            var response = await client.PostAsync(url, content);
            var responseString = await response.Content.ReadAsStringAsync();

            Console.WriteLine(responseString);
        }
    }
}
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://ugsms.com/v1/sms/send"

    data := map[string]string{
        "username":      "your_username",
        "password":      "your_password",
        "numbers":       "0702913454,0776913451",
        "message_body":  "Hello from UGSMS API v1",
        "sender_id":     "UGSMS",
    }

    jsonData, err := json.Marshal(data)
    if err != nil {
        fmt.Println("Error marshaling JSON:", err)
        return
    }

    req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Println("Error creating request:", err)
        return
    }

    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error sending request:", err)
        return
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    fmt.Println(result)
}
import 'dart:convert';
import 'package:http/http.dart' as http;

void main() async {
  final url = 'https://ugsms.com/v1/sms/send';

  final data = {
    'username': 'your_username',
    'password': 'your_password',
    'numbers': '0702913454,0776913451',
    'message_body': 'Hello from UGSMS API v1',
    'sender_id': 'UGSMS',
  };

  final response = await http.post(
    Uri.parse(url),
    headers: {
      'Content-Type': 'application/json',
    },
    body: jsonEncode(data),
  );

  final result = jsonDecode(response.body);
  print(result);
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.google.gson.Gson;

public class SendSMS {
    public static void main(String[] args) {
        String url = "https://ugsms.com/v1/sms/send";

        SMSData data = new SMSData();
        data.username = "your_username";
        data.password = "your_password";
        data.numbers = "0702913454,0776913451";
        data.message_body = "Hello from UGSMS API v1";
        data.sender_id = "UGSMS";

        Gson gson = new Gson();
        String jsonData = gson.toJson(data);

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(jsonData))
                .build();

        try {
            HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
            System.out.println(response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

class SMSData {
    public String username;
    public String password;
    public String numbers;
    public String message_body;
    public String sender_id;
}
require 'net/http'
require 'json'

url = URI('https://ugsms.com/v1/sms/send')

data = {
  username: 'your_username',
  password: 'your_password',
  numbers: '0702913454,0776913451',
  message_body: 'Hello from UGSMS API v1',
  sender_id: 'UGSMS'
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = (url.scheme == 'https')

request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request.body = data.to_json

response = http.request(request)
puts response.body
Example Response
{
    "success": true,
    "message": "Message sent successfully",
    "data": {
        "message_id": "123e4567-e89b-12d3-a456-426614174000",
        "recipient_id": "123e4567-e89b-12d3-a456-426614174001",
        "recipients": 2,
        "message_segments": 1,
        "estimated_cost": 20.0,
        "remaining_balance": 980.0,
        "status": "pending",
        "timestamp": "2024-01-01T12:00:00Z"
    }
}

Phone Number Formats

UGSMS API accepts Ugandan mobile numbers in these formats:

Format Example Description
07XXXXXXXX 0702913454 10 digits starting with 07
+2567XXXXXXXX +256702913454 International format with +256
2567XXXXXXXX 256702913454 International format without +
Note: Numbers can be comma-separated for multiple recipients: 0702913454,0776913451,+256702913454

Error Codes

HTTP Status Code Description Solution
400 VALIDATION_ERROR Invalid request parameters Check request format and parameters
400 INVALID_NUMBERS No valid phone numbers provided Use valid Ugandan number formats
401 UNAUTHORIZED Invalid username/password Check credentials
402 INSUFFICIENT_BALANCE Not enough balance to send SMS Top up your account
429 RATE_LIMIT_EXCEEDED Too many requests Wait 1 minute before retrying
500 INTERNAL_ERROR Server error Contact support
Important: API v1 is maintained for backward compatibility. For new integrations, we recommend using API v2 with API key authentication.