Send SMS from your own software
Use the JulySMS API to send SMS to MTN, Airtel and other Ugandan networks from your own app, website or billing system. It is a JSON API over HTTPS with two endpoints, plus an optional webhook for delivery reports.
Sign up at julysms.com and buy SMS credit with Mobile Money.
Open API & Webhooks in your dashboard and generate a Client ID and Client Secret.
Call POST /sms/send from your server.
Base URL
All requests use HTTPS. Send JSON with Content-Type: application/json; responses are always JSON.
Quick start
Replace the two keys with your own and run this from a terminal. You will receive the SMS within a few seconds and one SMS is taken from your balance.
Then see Send SMS for the full request and response, or copy a ready-made example for your language.
There is no separate test mode. Every request sends a real SMS and uses real credit, so test with your own number.
curl -X POST https://julysms.com/api/v1/sms/send \
-H "Client-ID: YOUR_CLIENT_ID" \
-H "Client-Secret: YOUR_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{"phone": "0772123456", "message": "Hello from JulySMS"}'
Authentication
Every request must carry your Client ID and Client Secret in two HTTP headers. You will find them under API & Webhooks in your JulySMS dashboard.
| Header | Value |
|---|---|
Client-ID | Your Client ID |
Client-Secret | Your Client Secret |
A missing or wrong key returns 401 {"error": "Unauthorized"}.
Keep the Client Secret on your server. Anyone who has it can send SMS from your balance. Never put it in a mobile app, browser JavaScript or a public repository. If it leaks, press Regenerate keys in the dashboard; the old keys stop working immediately.
Client-ID: YOUR_CLIENT_ID Client-Secret: YOUR_CLIENT_SECRET Content-Type: application/json Accept: application/json
Phone numbers
Send Ugandan numbers in any of the usual forms. Spaces, dashes and brackets are removed, and a leading 0 is replaced with the country code 256.
| You send | Delivered to | |
|---|---|---|
0772123456 | 256772123456 | Local format |
0772 123 456 | 256772123456 | Spaces are fine |
256772123456 | 256772123456 | International |
+256 772 123456 | 256772123456 | With + |
For numbers outside Uganda use the full international form with + or the bare country code, for example +254712345678. Do not use the 00 prefix.
Message length & billing
Each message is charged in SMS units. One unit covers up to 160 characters; longer messages use one unit per 160 characters or part of it, for every number you send to.
| Message length | Units per number | Sent to 100 numbers |
|---|---|---|
| 1 to 160 characters | 1 | 100 units |
| 161 to 320 characters | 2 | 200 units |
| 321 to 480 characters | 3 | 300 units |
- Length is measured in bytes. Plain English letters, digits and punctuation count as one each; emoji and accented letters (é, ü) count as two to four, so they can push a message into the next unit.
- Before sending, JulySMS checks that your balance covers the whole request. If it doesn't, nothing is sent and you get 400
Insufficient balance. - Units are taken for every number in the request, including any the network rejects. Check numbers before sending to avoid paying for bad ones.
- Your price per unit is shown on your dashboard. Top up any time with MTN or Airtel Mobile Money.
Send SMS
Sends one message to one number. The request waits until the message has been handed to the network, then returns the result.
Body
| Field | Description |
|---|---|
message requiredstring | The text to send. Long messages are split by the phone and charged as described in billing. |
phone required*string | The recipient's number. See phone numbers. |
phones optionalarray of strings | Use instead of phone to send to several numbers. See Send to many. |
* Send either phone or phones. If both are present, phones is used.
Response
200 means JulySMS tried every number. Check status for each one:
| Field | Description |
|---|---|
successboolean | Always true when the request was processed. |
messagestring | A short summary. |
details[]array | One entry per number, in the order you sent them. |
details[].phonestring | The number exactly as you sent it. |
details[].statusstring | sent: accepted by the network. failed: rejected (for example an invalid number). |
details[].api_responseobject | The SMS network's raw reply. Its MsgFollowUpUniqueCode is the message ID used in delivery reports; store it if you use webhooks. Other fields may change, so don't depend on them. |
sent means the network accepted the message, not that it reached the phone. Use delivery reports to learn when it was delivered.
curl -X POST https://julysms.com/api/v1/sms/send \
-H "Client-ID: YOUR_CLIENT_ID" \
-H "Client-Secret: YOUR_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{
"phone": "0772123456",
"message": "Your order #1042 is ready for pickup."
}'
<?php
$ch = curl_init('https://julysms.com/api/v1/sms/send');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => [
'Client-ID: ' . getenv('JULYSMS_CLIENT_ID'),
'Client-Secret: ' . getenv('JULYSMS_CLIENT_SECRET'),
'Content-Type: application/json',
'Accept: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'phone' => '0772123456',
'message' => 'Your order #1042 is ready for pickup.',
]),
]);
$result = json_decode(curl_exec($ch), true);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($code === 200 && $result['details'][0]['status'] === 'sent') {
$messageId = $result['details'][0]['api_response']['MsgFollowUpUniqueCode'] ?? null;
}
use Illuminate\Support\Facades\Http;
$response = Http::withHeaders([
'Client-ID' => config('services.julysms.client_id'),
'Client-Secret' => config('services.julysms.client_secret'),
])
->acceptJson()
->timeout(60)
->post('https://julysms.com/api/v1/sms/send', [
'phone' => '0772123456',
'message' => 'Your order #1042 is ready for pickup.',
]);
$sent = $response->ok() && $response->json('details.0.status') === 'sent';
// Node 18+ (built-in fetch)
const res = await fetch('https://julysms.com/api/v1/sms/send', {
method: 'POST',
headers: {
'Client-ID': process.env.JULYSMS_CLIENT_ID,
'Client-Secret': process.env.JULYSMS_CLIENT_SECRET,
'Content-Type': 'application/json',
'Accept': 'application/json',
},
body: JSON.stringify({
phone: '0772123456',
message: 'Your order #1042 is ready for pickup.',
}),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.details[0].status); // "sent" or "failed"
import os
import requests
res = requests.post(
"https://julysms.com/api/v1/sms/send",
headers={
"Client-ID": os.environ["JULYSMS_CLIENT_ID"],
"Client-Secret": os.environ["JULYSMS_CLIENT_SECRET"],
"Accept": "application/json",
},
json={
"phone": "0772123456",
"message": "Your order #1042 is ready for pickup.",
},
timeout=60,
)
data = res.json()
res.raise_for_status()
print(data["details"][0]["status"]) # "sent" or "failed"
{
"success": true,
"message": "SMS attempt complete.",
"details": [
{
"phone": "0772123456",
"status": "sent",
"api_response": {
"Status": "OK",
"MsgFollowUpUniqueCode": "a1b2c3d4e5"
}
}
]
}
Send to many
Same endpoint: pass an array in phones and every number gets the same message. The response has one entry in details per number, so you can see which ones failed.
- The balance check covers the whole list: if there isn't enough credit for all of them, none are sent.
- Numbers are sent one after another, so large lists take longer. Send up to about 100 numbers per request and allow a generous timeout (60 to 120 seconds). For bigger campaigns, split the list into several requests.
- Remove duplicates first; each entry is sent and charged.
Want different text per person (for example their name)? Send one request per person, or use groups with {first_name} placeholders in the JulySMS dashboard.
curl -X POST https://julysms.com/api/v1/sms/send \
-H "Client-ID: YOUR_CLIENT_ID" \
-H "Client-Secret: YOUR_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{
"phones": ["0772123456", "0701234567", "+256752000111"],
"message": "Our offices are closed on Monday for the public holiday."
}'
numbers = load_numbers() # your list
for i in range(0, len(numbers), 100):
batch = numbers[i:i + 100]
res = requests.post(
"https://julysms.com/api/v1/sms/send",
headers=headers,
json={"phones": batch, "message": text},
timeout=120,
)
for item in res.json().get("details", []):
if item["status"] != "sent":
print("Failed:", item["phone"])
{
"success": true,
"message": "Bulk SMS attempt complete.",
"details": [
{ "phone": "0772123456", "status": "sent", "api_response": { "Status": "OK", "MsgFollowUpUniqueCode": "a1b2c3d4e5" } },
{ "phone": "0701234567", "status": "sent", "api_response": { "Status": "OK", "MsgFollowUpUniqueCode": "f6g7h8i9j0" } },
{ "phone": "+256752000111", "status": "failed", "api_response": { "Status": "Failed", "Message": "Invalid number" } }
]
}
Check balance
Returns how many SMS units are left on your account. Useful before a large send, or to warn your team when credit runs low.
| Field | Description |
|---|---|
balanceinteger | SMS units available. |
curl https://julysms.com/api/v1/sms/balance \ -H "Client-ID: YOUR_CLIENT_ID" \ -H "Client-Secret: YOUR_CLIENT_SECRET"
$ch = curl_init('https://julysms.com/api/v1/sms/balance');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Client-ID: ' . getenv('JULYSMS_CLIENT_ID'),
'Client-Secret: ' . getenv('JULYSMS_CLIENT_SECRET'),
'Accept: application/json',
],
]);
$balance = json_decode(curl_exec($ch), true)['balance'];
const res = await fetch('https://julysms.com/api/v1/sms/balance', {
headers: {
'Client-ID': process.env.JULYSMS_CLIENT_ID,
'Client-Secret': process.env.JULYSMS_CLIENT_SECRET,
},
});
const { balance } = await res.json();
res = requests.get(
"https://julysms.com/api/v1/sms/balance",
headers={
"Client-ID": os.environ["JULYSMS_CLIENT_ID"],
"Client-Secret": os.environ["JULYSMS_CLIENT_SECRET"],
},
timeout=30,
)
balance = res.json()["balance"]
{
"balance": 1483
}
Delivery reports (webhooks)
When the network reports that a message reached the phone, or that it couldn't be delivered, JulySMS sends a POST request to your webhook URL.
Set it up
- Create an HTTPS endpoint in your app that accepts JSON
POSTrequests. - In the JulySMS dashboard, open API & Webhooks, paste the URL into Delivery webhook URL and save.
- Store
MsgFollowUpUniqueCodefrom each send response. It arrives asmessage_idin the report.
Payload
| Field | Description |
|---|---|
message_idstring | The MsgFollowUpUniqueCode from the send response. |
phonestring | The number as you sent it. |
statusstring | delivered or failed. |
sent_atstring | When it was sent (ISO 8601, East Africa Time). |
delivered_atstring | When the report came in (ISO 8601). |
What to expect
- Reply with any 2xx status within 5 seconds. Do slow work (database writes, notifications) after replying, or in a background job.
- Each report is sent once; there are no retries. If your server is down, that report is lost. You can still see every status in History in the dashboard.
- Some networks report late or not at all, so a message without a report isn't necessarily undelivered.
- Always check the signature before trusting a report.
POST /sms/delivery-status HTTP/1.1
Host: yourapp.com
Content-Type: application/json
X-Signature: 5d41402abc4b2a76b9719d911017c592...
{
"message_id": "a1b2c3d4e5",
"phone": "0772123456",
"status": "delivered",
"sent_at": "2026-11-20T09:14:05+03:00",
"delivered_at": "2026-11-20T09:14:11+03:00"
}
Verify the signature
Every report carries an X-Signature header so you can be sure it came from JulySMS and wasn't changed on the way.
The signature is the HMAC-SHA256 of the raw request body, keyed with your Client Secret, written as lowercase hex.
- Read the raw body exactly as received. Don't decode and re-encode the JSON first, because the bytes must match.
- Compute
HMAC-SHA256(raw_body, client_secret)as hex. - Compare it with
X-Signatureusing a constant-time comparison. If it doesn't match, reply 401 and ignore the report.
If you regenerate your API keys, new reports are signed with the new Client Secret. Update your server at the same time.
<?php
$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $raw, getenv('JULYSMS_CLIENT_SECRET'));
$given = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
if (!hash_equals($expected, $given)) {
http_response_code(401);
exit;
}
$report = json_decode($raw, true);
// $report['message_id'], $report['status'] ("delivered" or "failed")
http_response_code(200);
// routes/api.php
Route::post('/sms/delivery-status', function (Request $request) {
$expected = hash_hmac('sha256', $request->getContent(), config('services.julysms.client_secret'));
abort_unless(hash_equals($expected, (string) $request->header('X-Signature')), 401);
Message::where('julysms_id', $request->input('message_id'))
->update(['delivery_status' => $request->input('status')]);
return response()->noContent();
});
// Express: keep the raw body for this route
import express from 'express';
import crypto from 'node:crypto';
const app = express();
app.post('/sms/delivery-status', express.raw({ type: 'application/json' }), (req, res) => {
const expected = crypto
.createHmac('sha256', process.env.JULYSMS_CLIENT_SECRET)
.update(req.body) // Buffer, exactly as received
.digest('hex');
const given = req.get('X-Signature') || '';
const ok = given.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
if (!ok) return res.sendStatus(401);
const report = JSON.parse(req.body.toString('utf8'));
// report.message_id, report.status
res.sendStatus(200);
});
# Flask
import hashlib, hmac, os
from flask import Flask, request, abort
app = Flask(__name__)
@app.post("/sms/delivery-status")
def delivery_status():
raw = request.get_data() # bytes, exactly as received
expected = hmac.new(os.environ["JULYSMS_CLIENT_SECRET"].encode(), raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Signature", "")):
abort(401)
report = request.get_json()
# report["message_id"], report["status"]
return "", 200
Errors
Errors use standard HTTP status codes and a JSON body with an error field.
| Status | Body | What to do |
|---|---|---|
| 401 | {"error": "Unauthorized"} | The Client ID or Client Secret is missing or wrong. Check both headers, and whether the keys were regenerated. |
| 400 | {"error": "Insufficient balance"} | Not enough SMS for the whole request. Nothing was sent. Top up and try again. |
| 422 | {"error": "You must provide \"phone\" or \"phones\"."} | Add a phone or phones field. |
| 422 | {"error": "Validation failed", "details": {...}} | details lists each field's problem, for example a missing message or phones not being an array. |
| 500 | {"error": "..."} | Server error. Retry after a short wait and contact support if it keeps happening. |
A 200 response can still contain numbers with "status": "failed". Always check each entry in details.
{
"error": "Validation failed",
"details": {
"message": ["The message field is required."]
}
}
Good practice
- Call the API from your server and keep the keys in environment variables, not in your code.
- Use a timeout of at least 60 seconds for sends, longer for big lists. A request that times out may still have sent its messages, so check History or your balance before sending again.
- Save the message ID (
MsgFollowUpUniqueCode) with your own record so you can match delivery reports to it. - Stay within 160 plain characters if you want each message to cost one unit, and leave emoji out of transactional messages.
- Check
GET /sms/balanceregularly and alert your team before credit runs out. - Send marketing messages during the day and tell recipients how to opt out.
Changelog
| Date | Change |
|---|---|
| November 2026 | New documentation site. The API is unchanged: existing integrations keep working. |
| July 2026 | Delivery reports to your webhook, signed with X-Signature. |
| 2025 | API v1: send SMS (single and bulk) and check balance. |
Support
Questions about the API, or something not working as described here? Get in touch and include the time of the request and the number you sent to. Never include your Client Secret.
- Dashboard: julysms.com