SMS API Documentation
- Home
- SMS API Documentation
๐ก REST API ยท v1.0
SMS API Integration Guide
Send SMS messages programmatically from any platform. Simple REST API with GET/POST support โ compatible with all major languages and frameworks.
GET / POST
https://sms.gonlinesites.com/app/sms/api
Authentication
All requests require your api_key. Keep it secret โ store it as an environment variable.
โ ๏ธNever expose your API key in client-side code or public repositories.
Parameters
All five parameters are required for every send-sms request.
| Parameter | Type | Description |
|---|---|---|
| actionrequired | string | Always send-sms |
| api_keyrequired | string | Your API key from the dashboard. |
| torequired | string | Recipient in international format: +233244000000. Comma-separate for bulk. |
| fromrequired | string | Registered Sender ID (max 11 alphanumeric chars). |
| smsrequired | string | Message body. Max 160 chars per unit โ longer messages split automatically. |
Response Format
Success
{ "code" : "OK", "message_id" : "MSG1234567890", "to" : "+233244000000", "units" : 1, "balance" : 49 }
Error
{ "code" : 103, "message" : "Invalid phone number" }
| Code | Meaning | How to Handle |
|---|---|---|
| OK | Successfully Sent | Store message_id for delivery tracking. |
| 100 | Bad gateway request | Check the endpoint URL and all parameter names. |
| 101 | Wrong action | action must be exactly send-sms. |
| 102 | Authentication failed | Invalid api_key. Check your dashboard โ no extra spaces. |
| 103 | Invalid phone number | Use international format: +233244000000. No spaces or dashes. |
| 104 | Phone coverage not active | The destination network is not supported. Contact support. |
| 105 | Insufficient balance | Top up SMS credits in the dashboard. |
| 106 | Invalid Sender ID | Sender ID not registered or >11 alphanumeric chars. |
| 109 | Invalid Schedule Time | Schedule time is in the past or has invalid format. |
| 111 | SMS contains spam word | Message awaiting approval. Avoid spam trigger words. |
cURL
Test the API directly from your terminal.
terminal
# GET request curl "https://sms.gonlinesites.com/app/sms/api?action=send-sms\ &api_key=YOUR_API_KEY\ &to=+233244000000\ &from=MySenderID\ &sms=Hello%20from%20the%20API"
terminal
# POST request curl -X POST "https://sms.gonlinesites.com/app/sms/api" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "action=send-sms" -d "api_key=YOUR_API_KEY" \ -d "to=+233244000000" -d "from=MySenderID" -d "sms=Hello!"
Python
Use requests, built-in urllib, or a reusable class.
send_sms.py
import requests API_URL = "https://sms.gonlinesites.com/app/sms/api" API_KEY = "YOUR_API_KEY" def send_sms(to, sender_id, message): r = requests.get(API_URL, params={ "action":"send-sms", "api_key":API_KEY, "to":to, "from":sender_id, "sms":message, }, timeout=30) r.raise_for_status() data = r.json() if data.get("code") == "OK": print(f"Sent! ID: {data['message_id']}") else: print(f"Error {data['code']}: {data.get('message')}") return data send_sms("+233244000000", "MySenderID", "Hello!")
send_sms_urllib.py
import urllib.request, urllib.parse, json def send_sms(to, sender_id, message): p = urllib.parse.urlencode({ "action":"send-sms", "api_key":"YOUR_API_KEY", "to":to, "from":sender_id, "sms":message, }) with urllib.request.urlopen(f"https://sms.gonlinesites.com/app/sms/api?{p}", timeout=30) as r: return json.loads(r.read().decode()) print(send_sms("+233244000000", "MySenderID", "Hello!"))
sms_client.py
import requests from typing import Union, List class SMSClient: BASE_URL = "https://sms.gonlinesites.com/app/sms/api" def __init__(self, api_key: str, sender_id: str): self.api_key = api_key; self.sender_id = sender_id self.session = requests.Session() def send(self, to: Union[str, List[str]], message: str) -> dict: r = self.session.get(self.BASE_URL, params={ "action":"send-sms", "api_key":self.api_key, "to":",".join(to) if isinstance(to, list) else to, "from":self.sender_id, "sms":message }, timeout=30) r.raise_for_status(); return r.json() sms = SMSClient("YOUR_API_KEY", "MySenderID") sms.send("+233244000000", "Hello!") sms.send(["+233244000000", "+233200111222"], "Bulk!")
PHP
cURL, file_get_contents, or Guzzle.
send_sms.php
<?php define('SMS_URL', 'https://sms.gonlinesites.com/app/sms/api'); define('SMS_KEY', 'YOUR_API_KEY'); function sendSMS($to, $from, $message): array { $params = http_build_query([ 'action' => 'send-sms', 'api_key' => SMS_KEY, 'to' => $to, 'from' => $from, 'sms' => $message, ]); $ch = curl_init(SMS_URL . '?' . $params); curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30]); $resp = curl_exec($ch); $err = curl_error($ch); curl_close($ch); if ($err) return ['code' => 'error', 'message' => $err]; $data = json_decode($resp, true); match ($data['code']) { 'OK' => error_log("Sent: {$data['message_id']}"), 102 => error_log('Authentication failed โ check API key'), 105 => error_log('Insufficient balance'), 111 => error_log('Spam flag โ awaiting approval'), default => error_log("SMS error {$data['code']}"), }; return $data; } sendSMS('+233244000000', 'MySenderID', 'Hello!');
send_sms_simple.php
<?php $query = http_build_query([ 'action' => 'send-sms', 'api_key' => 'YOUR_API_KEY', 'to' => '+233244000000', 'from' => 'MySenderID', 'sms' => 'Hello World!', ]); $ctx = stream_context_create(['http' => ['timeout' => 30]]); $data = json_decode(file_get_contents("https://sms.gonlinesites.com/app/sms/api?{$query}", context: $ctx), true); var_dump($data);
send_sms_guzzle.php
<?php // composer require guzzlehttp/guzzle use GuzzleHttp\Client; $data = json_decode((new Client(['base_uri' => 'https://sms.gonlinesites.com'])) ->get('/app/sms/api', ['query' => [ 'action' => 'send-sms', 'api_key' => 'YOUR_API_KEY', 'to' => '+233244000000', 'from' => 'MySenderID', 'sms' => 'Hello!', ]])->getBody(), true); print_r($data);
Laravel
Service class, Http Facade with code handling, config, and Notification channel.
app/Services/SmsService.php
<?php namespace App\Services; use Illuminate\Support\Facades\Http, Log; class SmsService { protected string $apiKey, $senderId; protected string $url = 'https://sms.gonlinesites.com/app/sms/api'; public function __construct() { $this->apiKey = config('sms.api_key'); $this->senderId = config('sms.sender_id'); } public function send(string $to, string $message): array { $data = Http::timeout(30)->get($this->url, [ 'action' => 'send-sms', 'api_key' => $this->apiKey, 'to' => $to, 'from' => $this->senderId, 'sms' => $message, ])->json(); if ($data['code'] !== 'OK') Log::warning("SMS [{$data['code']}]: {$data['message']}"); return $data; } public function sendBulk(array $numbers, string $msg): array { return $this->send(implode(',', $numbers), $msg); } }
Controller (inline)
use Illuminate\Support\Facades\Http; $data = Http::get('https://sms.gonlinesites.com/app/sms/api', [ 'action' => 'send-sms', 'api_key' => env('SMS_API_KEY'), 'to' => '+233244000000', 'from' => env('SMS_SENDER_ID'), 'sms' => 'Hello from Laravel!', ])->json(); match ($data['code']) { 'OK' => logger("Sent: {$data['message_id']}"), 102 => abort(401, 'SMS auth failed'), 105 => abort(402, 'Insufficient balance'), 111 => logger('SMS pending spam review'), default => logger("SMS error {$data['code']}"), };
.env
SMS_API_KEY=YOUR_API_KEY SMS_SENDER_ID=MySenderID SMS_BASE_URL=https://sms.gonlinesites.com/app/sms/api
config/sms.php
<?php return [ 'api_key' => env('SMS_API_KEY'), 'sender_id' => env('SMS_SENDER_ID', 'MySenderID'), 'base_url' => env('SMS_BASE_URL', 'https://sms.gonlinesites.com/app/sms/api'), ];
SmsNotification.php
<?php namespace App\Notifications; use Illuminate\Notifications\Notification; class SmsNotification extends Notification { public function __construct(protected string $message) {} public function via($n): array { return ['sms']; } public function toSms($n): array { return ['to' => $n->phone_number, 'message' => $this->message]; } } // $user->notify(new SmsNotification('Your OTP is 4921'));
Node.js
sendSms.js
const axios = require('axios'); // npm install axios async function sendSms(to, message) { const { data } = await axios.get('https://sms.gonlinesites.com/app/sms/api', { params: { action:'send-sms', api_key:'YOUR_API_KEY', to, from:'MySenderID', sms: message }, timeout: 30000, }); if (data.code === 'OK') { console.log(`โ Sent: ${data.message_id}`); } else { console.error(`โ Error ${data.code}: ${data.message}`); } return data; } sendSms('+233244000000', 'Hello!').catch(console.error);
sendSms_native.js
const https = require('https'), qs = require('querystring'); const q = qs.stringify({ action:'send-sms', api_key:'YOUR_API_KEY', to:'+233244000000', from:'MySenderID', sms:'Hello!' }); https.get(`https://sms.gonlinesites.com/app/sms/api?${q}`, r => { let b = ''; r.on('data', c => b += c); r.on('end', () => console.log(JSON.parse(b))); });
smsClient.ts
import axios from 'axios'; interface SmsResponse { code: string | number; message_id?: string; message?: string; units?: number; balance?: number; } export async function sendSms( to: string | string[], message: string, ): Promise<SmsResponse> { const { data } = await axios.get<SmsResponse>( 'https://sms.gonlinesites.com/app/sms/api', { params: { action:'send-sms', api_key: process.env.SMS_API_KEY, to: Array.isArray(to) ? to.join(',') : to, from: process.env.SMS_SENDER_ID, sms: message }, } ); if (data.code !== 'OK') throw new Error(`[${data.code}] ${data.message}`); return data; }
JavaScript (Browser)
โ ๏ธNever expose your API key in client-side code. Route requests through your backend.
sms.js
const p = new URLSearchParams({ action:'send-sms', api_key:'YOUR_API_KEY', to:'+233244000000', from:'MySenderID', sms:'Hello!', }); fetch(`https://sms.gonlinesites.com/app/sms/api?${p}`) .then(r => r.json()) .then(d => d.code === 'OK' ? console.log('Sent!',d) : console.error(d)) .catch(console.error);
sms_async.js
async function sendSms({ to, from, message }) { const url = new URL('https://sms.gonlinesites.com/app/sms/api'); Object.entries({action:'send-sms',api_key:'YOUR_API_KEY',to,from,sms:message}) .forEach(([k,v]) => url.searchParams.set(k,v)); const data = await (await fetch(url)).json(); if (data.code !== 'OK') throw new Error(`[${data.code}] ${data.message}`); return data; }
Java
SmsClient.java
import java.net.*; import java.net.http.*; import java.nio.charset.StandardCharsets; import java.time.Duration; public class SmsClient { private static final String BASE = "https://sms.gonlinesites.com/app/sms/api"; private static final String KEY = "YOUR_API_KEY"; private static final String SENDER = "MySenderID"; private final HttpClient http = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(30)).build(); public String send(String to, String msg) throws Exception { String url = BASE + "?action=send-sms&api_key=" + URLEncoder.encode(KEY,StandardCharsets.UTF_8) + "&to=" + URLEncoder.encode(to,StandardCharsets.UTF_8) + "&from=" + URLEncoder.encode(SENDER,StandardCharsets.UTF_8) + "&sms=" + URLEncoder.encode(msg,StandardCharsets.UTF_8); return http.send(HttpRequest.newBuilder().uri(URI.create(url)) .GET().timeout(Duration.ofSeconds(30)).build(), HttpResponse.BodyHandlers.ofString()).body(); } }
SmsOkHttp.java
// implementation 'com.squareup.okhttp3:okhttp:4.12.0' import okhttp3.*; HttpUrl url = HttpUrl.parse("https://sms.gonlinesites.com/app/sms/api") .newBuilder() .addQueryParameter("action", "send-sms") .addQueryParameter("api_key", "YOUR_API_KEY") .addQueryParameter("to", "+233244000000") .addQueryParameter("from", "MySenderID") .addQueryParameter("sms", "Hello!").build(); try (Response r = new OkHttpClient() .newCall(new Request.Builder().url(url).build()).execute()) { System.out.println(r.body().string()); }
C# / .NET
SmsClient.cs
using System.Net.Http; using System.Text.Json; public class SmsClient { private const string Base="https://sms.gonlinesites.com/app/sms/api",Key="YOUR_API_KEY",Sender="MySenderID"; private static readonly HttpClient _h = new(); public static async Task<JsonDocument> SendAsync(string to, string msg) { var b = new UriBuilder(Base); var q = System.Web.HttpUtility.ParseQueryString(string.Empty); q["action"]="send-sms";q["api_key"]=Key;q["to"]=to;q["from"]=Sender;q["sms"]=msg; b.Query=q.ToString(); var r=await _h.GetAsync(b.Uri); r.EnsureSuccessStatusCode(); return JsonDocument.Parse(await r.Content.ReadAsStringAsync()); } }
SmsService.cs (DI)
// Program.cs builder.Services.AddHttpClient<ISmsService,SmsService>(); builder.Services.Configure<SmsOptions>(builder.Configuration.GetSection("Sms")); public interface ISmsService { Task<bool> SendAsync(string to,string msg); } public class SmsService(HttpClient http,IOptions<SmsOptions> opts):ISmsService { public async Task<bool> SendAsync(string to,string msg) { var o=opts.Value; var r=await http.GetAsync($"{o.BaseUrl}?action=send-sms&api_key={o.ApiKey}&to={to}&from={o.SenderId}&sms={Uri.EscapeDataString(msg)}"); return r.IsSuccessStatusCode; } } // appsettings: { "Sms": { "ApiKey":"...", "SenderId":"...", "BaseUrl":"..." } }
Ruby
send_sms.rb
require 'net/http'; require 'uri'; require 'json' def send_sms(to:, from:, message:) uri = URI('https://sms.gonlinesites.com/app/sms/api') uri.query = URI.encode_www_form( action: 'send-sms', api_key: 'YOUR_API_KEY', to:, from:, sms: message ) data = JSON.parse(Net::HTTP.get_response(uri).body) data['code'] == 'OK' ? puts("Sent: #{data['message_id']}") : puts("Error: #{data}") end send_sms(to: '+233244000000', from: 'MySenderID', message: 'Hello!')
sms_httparty.rb
# gem install httparty require 'httparty' class SmsClient include HTTParty base_uri 'https://sms.gonlinesites.com' def initialize(key, sender); @key=key; @sender=sender; end def send(to, msg) self.class.get('/app/sms/api', query:{action:'send-sms',api_key:@key,to:,from:@sender,sms:msg}) end end puts SmsClient.new('YOUR_API_KEY','MySenderID').send('+233244000000','Hello!')
Go
sms.go
package main import ("encoding/json";"fmt";"net/http";"net/url";"time") type SMSResponse struct { Code interface{} `json:"code"` MessageID string `json:"message_id,omitempty"` Message string `json:"message,omitempty"` } func (r SMSResponse) OK() bool { c,_:=r.Code.(string); return c=="OK" } func SendSMS(to, msg string) (SMSResponse, error) { p := url.Values{ "action":{"send-sms"}, "api_key":{"YOUR_API_KEY"}, "to":{to}, "from":{"MySenderID"}, "sms":{msg}, } c := &http.Client{Timeout:30*time.Second} resp, err := c.Get("https://sms.gonlinesites.com/app/sms/api?"+p.Encode()) if err!=nil { return SMSResponse{}, err } defer resp.Body.Close() var r SMSResponse; json.NewDecoder(resp.Body).Decode(&r); return r, nil } func main() { r, _ := SendSMS("+233244000000", "Hello from Go!") if r.OK() { fmt.Println("Sent:",r.MessageID) } else { fmt.Println("Error:",r.Code,r.Message) } }
Bulk SMS
Comma-separate the to parameter to send to multiple recipients at once.
bulk_sms.py
import requests numbers = ["+233244000001", "+233244000002", "+233200111222"] r = requests.get("https://sms.gonlinesites.com/app/sms/api", params={ "action":"send-sms", "api_key":"YOUR_API_KEY", "to":",".join(numbers), "from":"MySenderID", "sms":"Announcement!", }) print(r.json())
bulk_sms.php
<?php $numbers = ['+233244000001', '+233244000002', '+233200111222']; $q = http_build_query([ 'action' => 'send-sms', 'api_key' => 'YOUR_API_KEY', 'to' => implode(',', $numbers), 'from' => 'MySenderID', 'sms' => 'Announcement!', ]); print_r(json_decode(file_get_contents("https://sms.gonlinesites.com/app/sms/api?{$q}"), true));
bulk_sms.js
const axios = require('axios'); const nums = ['+233244000001','+233244000002','+233200111222']; axios.get('https://sms.gonlinesites.com/app/sms/api', { params:{ action:'send-sms', api_key:'YOUR_API_KEY', to:nums.join(','), from:'MySenderID', sms:'Announcement!' } }).then(r=>console.log(r.data));
Response Codes
Complete reference for all API response codes and recommended handling.
| Code | Meaning | Recommended Action |
|---|---|---|
| OK | Successfully Sent | Message accepted. Log message_id and update delivery status. |
| 100 | Bad gateway request | Malformed request. Check the endpoint URL and all parameter names. |
| 101 | Wrong action | action must be exactly send-sms. Check for typos. |
| 102 | Authentication failed | Invalid api_key. Verify in the dashboard โ no leading/trailing spaces. |
| 103 | Invalid phone number | Use full international format: +233244000000. Remove spaces and dashes. |
| 104 | Phone coverage not active | Destination network not supported. Contact support to check available routes. |
| 105 | Insufficient balance | Log in to the dashboard and top up your SMS credits before retrying. |
| 106 | Invalid Sender ID | Sender ID not registered or exceeds 11 alphanumeric characters. |
| 109 | Invalid Schedule Time | Schedule time is in the past or incorrectly formatted. Use a future UTC timestamp. |
| 111 | SMS contains spam word | Message flagged, awaiting manual approval. Revise to avoid spam trigger words. |