> ## 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 Bulk SMS to Multiple Recipients



## OpenAPI

````yaml https://ugatext.com/api/v1/openapi.json post /sms/bulk
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/bulk:
    post:
      summary: Send Bulk SMS to Multiple Recipients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkSMSRequest'
      responses:
        '200':
          description: Bulk messages processed with one result per recipient
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSMSResponse'
        '400':
          description: INVALID_REQUEST
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: INVALID_API_KEY
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: INSUFFICIENT_BALANCE
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: SENDER_ID_NOT_APPROVED or COMPLIANCE_BLOCKED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BulkSMSRequest:
      type: object
      required:
        - recipients
        - message
        - sender_id
      properties:
        recipients:
          type: array
          items:
            type: string
          description: >-
            List of recipient phone numbers up to 5,000 per request (accepted
            field aliases: "phones", "to", "messages"; items may also be objects
            with { to, message, sender_id }).
          example:
            - '+256700000000'
            - '+256772123456'
        message:
          type: string
          description: 'SMS broadcast message body (accepted field aliases: "text", "body").'
          example: Important community update from UgaText.
        sender_id:
          type: string
          description: >-
            Approved alphanumeric Sender ID (e.g. "UGATEXT"; accepted field
            aliases: "senderId", "from"). Required — missing, blank, or
            unapproved values return 403 SENDER_ID_NOT_APPROVED.
          example: UGATEXT
    BulkSMSResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        batch_id:
          type: string
          example: batch_1760425200000_1a2b3c4d
        status:
          type: string
          example: queued
        sender_id:
          type: string
          example: UGATEXT
        mode:
          type: string
          enum:
            - live
            - sandbox
            - mixed
          example: sandbox
        total_recipients:
          type: integer
          example: 2
        total_accepted:
          type: integer
          example: 2
        dispatched_count:
          type: integer
          example: 2
        failed_count:
          type: integer
          example: 0
        total_segments:
          type: integer
          example: 2
        total_units:
          type: integer
          example: 2
        estimated_cost_ugx:
          type: number
          example: 25
        total_cost_ugx:
          type: number
          example: 25
        currency:
          type: string
          example: UGX
        results:
          type: array
          items:
            $ref: '#/components/schemas/BulkSMSRecipientResult'
    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.
    BulkSMSRecipientResult:
      type: object
      properties:
        recipient:
          type: string
          example: '+256700000000'
        phone:
          type: string
          example: '+256700000000'
        message_id:
          type: string
          nullable: true
          example: msg_1760425200000_f9e8d7c6
        status:
          type: string
          enum:
            - queued
            - sent
            - delivered
            - failed
          example: queued
        segments:
          type: integer
          example: 1
        cost_ugx:
          type: number
          example: 0
        currency:
          type: string
          example: UGX
        network:
          type: string
          example: Airtel
        mode:
          type: string
          enum:
            - live
            - sandbox
          example: sandbox
        success:
          type: boolean
          example: true
        error:
          type: string
          nullable: true
  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
        <Client-ID>:<Client-Secret> / X-API-Key: <Client-ID>:<Client-Secret>.
    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.