JulySMSAPI documentation
Support Get API keys
JulySMS API · v1

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.

1Create an account

Sign up at julysms.com and buy SMS credit with Mobile Money.

2Get your API keys

Open API & Webhooks in your dashboard and generate a Client ID and Client Secret.

3Send a message

Call POST /sms/send from your server.

Base URL

https://julysms.com/api/v1

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.

HeaderValue
Client-IDYour Client ID
Client-SecretYour 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.

Request headers
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 sendDelivered to
0772123456256772123456Local format
0772 123 456256772123456Spaces are fine
256772123456256772123456International
+256 772 123456256772123456With +

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 lengthUnits per numberSent to 100 numbers
1 to 160 characters1100 units
161 to 320 characters2200 units
321 to 480 characters3300 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

POST/sms/send

Sends one message to one number. The request waits until the message has been handed to the network, then returns the result.

Body

FieldDescription
message requiredstringThe text to send. Long messages are split by the phone and charged as described in billing.
phone required*stringThe recipient's number. See phone numbers.
phones optionalarray of stringsUse 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:

FieldDescription
successbooleanAlways true when the request was processed.
messagestringA short summary.
details[]arrayOne entry per number, in the order you sent them.
details[].phonestringThe number exactly as you sent it.
details[].statusstringsent: accepted by the network. failed: rejected (for example an invalid number).
details[].api_responseobjectThe 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."
  }'
Response · 200
{
  "success": true,
  "message": "SMS attempt complete.",
  "details": [
    {
      "phone": "0772123456",
      "status": "sent",
      "api_response": {
        "Status": "OK",
        "MsgFollowUpUniqueCode": "a1b2c3d4e5"
      }
    }
  ]
}

Send to many

POST/sms/send

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."
  }'
Response · 200 (example)
{
  "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

GET/sms/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.

FieldDescription
balanceintegerSMS units available.
curl https://julysms.com/api/v1/sms/balance \
  -H "Client-ID: YOUR_CLIENT_ID" \
  -H "Client-Secret: YOUR_CLIENT_SECRET"
Response · 200
{
  "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

  1. Create an HTTPS endpoint in your app that accepts JSON POST requests.
  2. In the JulySMS dashboard, open API & Webhooks, paste the URL into Delivery webhook URL and save.
  3. Store MsgFollowUpUniqueCode from each send response. It arrives as message_id in the report.

Payload

FieldDescription
message_idstringThe MsgFollowUpUniqueCode from the send response.
phonestringThe number as you sent it.
statusstringdelivered or failed.
sent_atstringWhen it was sent (ISO 8601, East Africa Time).
delivered_atstringWhen 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 to your webhook URL
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.

  1. Read the raw body exactly as received. Don't decode and re-encode the JSON first, because the bytes must match.
  2. Compute HMAC-SHA256(raw_body, client_secret) as hex.
  3. Compare it with X-Signature using 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);

Errors

Errors use standard HTTP status codes and a JSON body with an error field.

StatusBodyWhat 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.

422 · Validation failed
{
  "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/balance regularly and alert your team before credit runs out.
  • Send marketing messages during the day and tell recipients how to opt out.

Changelog

DateChange
November 2026New documentation site. The API is unchanged: existing integrations keep working.
July 2026Delivery reports to your webhook, signed with X-Signature.
2025API 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.