API v1 Documentation
LegacyVersion 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.