API & SMPP Documentation

1. Top up credits. The API draws from the same balance as the dashboard. 1 credit = 1 message part.
2. Copy your API key from the Your credentials section below.
3. Call POST /api/v1/send-sms with a number and a message. That's it.

Authenticate with your API key as a bearer token. Requests without a valid key are rejected with 401.

Authorization: Bearer <API_KEY>
Content-Type: application/json

Every account gets its own API key and SMPP login. Sign up free (new accounts receive free SMS credits) or log in, and your credentials will appear right here and on the API page of your dashboard.

Sends one message to one recipient and deducts the appropriate number of credits.

Request body

Example request

curl -X POST "https://app.bulksmsug.com/api/v1/send-sms" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "0712345678",
  "message": "Sample message"
}'

Success response — 200 OK

{
  "timestamp": 1727118964,
  "calculatedCredits": 1,
  "message": "Sample message",
  "contact": "+256712345678",
  "status": "Sent",
  "id": "bsmsugId906g5153242786d4h64f9e7349d2a7fe"
}

Returns the latest known delivery state for a message you sent. Pass the full id from the send response, including the bsmsugId prefix.

Path parameter

Example request

curl -X GET "https://app.bulksmsug.com/api/v1/status/bsmsugId906g5153242786d4h64f9e7349d2a7fe" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "0712345678",
  "message": "Sample message"
}'

Success response — 200 OK

{
  "status": 1,
  "data": {
    "timestamp": 1727118964,
    "id": "bsmsugId906g5153242786d4h64f9e7349d2a7fe",
    "contact": "+256712345678",
    "status": "Success",
    "message": "Sample message"
  }
}

404 with { "status": 0, "data": "Message not found" } means the ID is unknown to your account (wrong ID, or not yet processed).

Validates the bearer token and echoes back the account it belongs to. No credits are used.

curl -X GET "https://app.bulksmsug.com/api/v1/auth" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "0712345678",
  "message": "Sample message"
}'

Success response — 200 OK

{
  "uid": "0m2S9kQ...",
  "email": "[email protected]"
}

You can send the number in any of the formats below. It is converted to +256XXXXXXXXX automatically, and the contact field in the response reflects the normalised value.

A single SMS carries 160 characters using the GSM-7 alphabet, or 70 characters if the text contains any Unicode character (emoji, curly quotes, many accents). Longer messages are split into parts and each part costs one credit.

The calculatedCredits value in the send response is the exact number of parts (credits) charged. A send is rejected with { "status": 0, "data": "Insufficient credits" } if your balance can't cover it.

The status string moves through these values. The send response captures the initial state; the status endpoint reflects delivery receipts from the carrier.

Errors use standard HTTP status codes. Error bodies are { "status": 0, "data": "<reason>" }.

Use submit_sm with a normalised MSISDN and register for delivery receipts to track status. For dedicated throughput, a custom sender ID, or two-way messaging, talk to support first.

Questions about integration, sender IDs, bulk pricing or your balance:

📞 Call or WhatsApp 0774310842  •  Create a free account  •  See pricing