> ## Documentation Index > Fetch the complete documentation index at: https://docs.ugatext.com/llms.txt > Use this file to discover all available pages before exploring further. # Send a Single SMS Message ## OpenAPI ````yaml https://ugatext.com/api/v1/openapi.json post /sms/send openapi: 3.0.3 info: title: UgaText Developer Communications API version: 1.0.0 description: >- Official REST API for UgaText (https://ugatext.com/api/v1). Supports single and bulk SMS dispatch across Uganda (+256 via Pandora), Kenya (+254 via Ping Africa), and DR Congo (+243 via Coussema SMS Gateway), real-time queued → sent → delivered status polling, wallet balance queries, UCC 21-rule compliance inspection, and OTP verification. Rate limit: 600 requests/minute (10 req/sec). Free sandbox numbers: +256700000000, +254700000000, or +243810000000. contact: name: UgaText Developer Support url: https://ugatext.com/api-docs email: support@ugatext.com servers: - url: https://ugatext.com/api/v1 description: UgaText Production API Gateway security: - ClientIdHeader: [] ClientSecretHeader: [] paths: /sms/send: post: summary: Send a Single SMS Message parameters: - $ref: '#/components/parameters/IdempotencyKeyHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendSMSRequest' responses: '200': description: >- Message accepted and queued for dispatch (poll GET /api/v1/sms/status/{id} for queued → sent → delivered) content: application/json: schema: $ref: '#/components/schemas/SendSMSResponse' '400': description: INVALID_REQUEST (missing recipient or message) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: INVALID_API_KEY (missing, invalid, or revoked credentials) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: INSUFFICIENT_BALANCE (wallet balance too low) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- SENDER_ID_NOT_APPROVED (missing, blank, or unapproved Sender ID) or COMPLIANCE_BLOCKED content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: INVALID_PHONE_NUMBER content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: RATE_LIMIT_EXCEEDED (600 requests/minute limit exceeded) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: IdempotencyKeyHeader: name: Idempotency-Key in: header required: false schema: type: string example: 8f14e45f-ceea-467f-a8f1-4e45fceea67f description: >- 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). schemas: SendSMSRequest: type: object required: - to - message - sender_id properties: to: type: string description: >- 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: type: string description: 'SMS text body (accepted field aliases: "text", "body").' example: Your verification code is 482910. sender_id: type: string description: >- 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 SendSMSResponse: type: object properties: success: type: boolean example: true message_id: type: string description: >- Unique message identifier in format msg_<13-digit-unix-ms>_<8-hex-chars>. example: msg_1760425200000_a1b2c3d4 status: type: string enum: - queued - sent - delivered - failed description: >- Initial state is "queued". Poll GET /api/v1/sms/status/{id} to observe queued → sent → delivered. example: queued recipient: type: string example: '+256750625684' phone: type: string example: '+256750625684' sender_id: type: string example: UGATEXT segments: type: integer example: 1 encoding: type: string enum: - GSM-7 - UCS-2 example: GSM-7 estimated_cost: type: number example: 25 cost_ugx: type: number example: 25 cost_kes: type: number example: 0.4 cost_usd: type: number example: 0.035 currency: type: string enum: - UGX - KES - USD example: UGX country: type: string example: Uganda network: type: string example: Airtel mode: type: string enum: - live - sandbox description: >- "sandbox" when triggered via free sandbox numbers (+256700000000 / +254700000000 / +243810000000) or a sandbox API key; "live" for billable carrier dispatches. example: live created_at: type: string format: date-time example: '2026-10-14T07:00:00.000Z' queued_at: type: string format: date-time example: '2026-10-14T07:00:00.000Z' ErrorResponse: type: object required: - success - error properties: success: type: boolean example: false error: type: object required: - code - message properties: code: type: string enum: - INVALID_API_KEY - INVALID_REQUEST - INVALID_PHONE_NUMBER - INSUFFICIENT_BALANCE - COMPLIANCE_BLOCKED - SENDER_ID_NOT_APPROVED - RATE_LIMIT_EXCEEDED - NOT_FOUND message: type: string example: >- Authentication failed. Provide a valid 'Client-ID' and 'Client-Secret' in the request headers. securitySchemes: ClientIdHeader: type: apiKey in: header name: Client-ID description: >- Your UgaText Client-ID (e.g. uga_...). Accepted header aliases: X-Client-ID, or combined in Authorization: Bearer : / X-API-Key: :. ClientSecretHeader: type: apiKey in: header name: Client-Secret description: >- Your UgaText Client-Secret (e.g. sk_live_...). Accepted header alias: X-Client-Secret. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.