Skip to main content
POST
Send a Single SMS Message

Authorizations

Client-ID
string
header
required

Your UgaText Client-ID (e.g. uga_...). Accepted header aliases: X-Client-ID, or combined in Authorization: Bearer : / X-API-Key: :.

Client-Secret
string
header
required

Your UgaText Client-Secret (e.g. sk_live_...). Accepted header alias: X-Client-Secret.

Headers

Idempotency-Key
string

Optional unique key (up to 128 chars, e.g. UUID v4) to safely retry POST /api/v1/sms/send without duplicate dispatch or double billing. Cached for 24 hours per account; replays return X-Cache-Lookup: HIT (Idempotent).

Example:

"8f14e45f-ceea-467f-a8f1-4e45fceea67f"

Body

application/json
to
string
required

Recipient phone number in E.164 with or without a leading + (e.g. "+256750625684", "+254712345678", or "+243810000000") or local national format ("0750625684", "0810000000"). Accepted field aliases: "phone", "recipient", or first element of "recipients[]" / "phones[]". Use +256700000000, +254700000000, or +243810000000 to trigger free sandbox mode.

Example:

"+256750625684"

message
string
required

SMS text body (accepted field aliases: "text", "body").

Example:

"Your verification code is 482910."

sender_id
string
required

Approved alphanumeric Sender ID (1-11 chars, e.g. "UGATEXT"; accepted field aliases: "senderId", "from"). Required — missing, blank, or unapproved values are rejected with 403 SENDER_ID_NOT_APPROVED.

Example:

"UGATEXT"

Response

Message accepted and queued for dispatch (poll GET /api/v1/sms/status/{id} for queued → sent → delivered)

success
boolean
Example:

true

message_id
string

Unique message identifier in format msg_<13-digit-unix-ms>_<8-hex-chars>.

Example:

"msg_1760425200000_a1b2c3d4"

status
enum<string>

Initial state is "queued". Poll GET /api/v1/sms/status/{id} to observe queued → sent → delivered.

Available options:
queued,
sent,
delivered,
failed
Example:

"queued"

recipient
string
Example:

"+256750625684"

phone
string
Example:

"+256750625684"

sender_id
string
Example:

"UGATEXT"

segments
integer
Example:

1

encoding
enum<string>
Available options:
GSM-7,
UCS-2
Example:

"GSM-7"

estimated_cost
number
Example:

25

cost_ugx
number
Example:

25

cost_kes
number
Example:

0.4

cost_usd
number
Example:

0.035

currency
enum<string>
Available options:
UGX,
KES,
USD
Example:

"UGX"

country
string
Example:

"Uganda"

network
string
Example:

"Airtel"

mode
enum<string>

"sandbox" when triggered via free sandbox numbers (+256700000000 / +254700000000 / +243810000000) or a sandbox API key; "live" for billable carrier dispatches.

Available options:
live,
sandbox
Example:

"live"

created_at
string<date-time>
Example:

"2026-10-14T07:00:00.000Z"

queued_at
string<date-time>
Example:

"2026-10-14T07:00:00.000Z"