> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairosafrika.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Bulk SMS

> Send SMS messages to multiple recipients in a single request

# Send Bulk SMS

This endpoint allows you to send SMS messages to multiple recipients in a single request.

**Endpoint:** `POST /v1/external/sms/bulk`

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.kairosafrika.com/v1/external/sms/bulk \
    --header 'x-api-key: YOUR_API_KEY' \
    --header 'x-api-secret: YOUR_API_SECRET' \
    --header 'x-api-version: 2025-08-01' \
    --header 'Content-Type: application/json' \
    --data '{
      "messages": [
        {
          "to": "233200746417",
          "from": "PHCCU",
          "message": "Dear TETTEH-KORBOE MARIAN (DR), GHS 224.52 Interest on Savings for the 3rd Quarter of 2023\r\nBalance GHS 24471.33.\r\nThank you. PHCCU… Happy Family!",
          "type": "Quick"
        },
        {
          "to": "233559400612",
          "from": "PHCCU",
          "message": "Dear TETTEH-KORBOE MARIAN (DR), GHS 224.52 Interest on Savings for the 3rd Quarter of 2023\r\nBalance GHS 24471.33.\r\nThank you. PHCCU… Happy Family!",
          "type": "Quick"
        }
      ],
      "isGlobal": false
    }'
  ```
</RequestExample>

## Request Body

* **messages** (array, required): Array of SMS message objects to send.
  * **to** (string, required): Recipient phone number (without + prefix).
  * **from** (string, required): Sender ID or name.
  * **message** (string, required): The SMS message content.
  * **type** (string, required): SMS type (use "Quick" for quick SMS).
* **isGlobal** (boolean, required): Whether to use global routing (true/false).

## Responses

* **200 OK**: Bulk SMS sent successfully.
* **400 Bad Request**: Invalid request data.
* **401 Unauthorized**: Invalid or missing API key.


## OpenAPI

````yaml POST /v1/external/sms/bulk
openapi: 3.0.3
info:
  title: Kairos Afrika SMS API
  description: >-
    Send SMS messages through the Kairos Afrika platform. Switch between staging
    and production environments using the server dropdown.
  version: 1.0.0
  contact:
    name: Kairos Afrika Support
    email: support@kairosafrika.com
servers:
  - url: https://api.kairosafrika.com
    description: Sms API Base URL
security:
  - apiKeyAuth: []
    apiSecretAuth: []
paths:
  /v1/external/sms/bulk:
    post:
      tags:
        - SMS
      summary: Send Bulk SMS
      description: Send SMS messages to multiple recipients in a single request
      operationId: sendBulkSMS
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            enum:
              - '2025-08-01'
          description: API version header (required for full JSON response)
          example: '2025-08-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendBulkSMSRequest'
      responses:
        '200':
          description: Bulk SMS sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSMSResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: 12d72d1c-08f7-4821-a05c-05fef961553f
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: 12d72d1c-08f7-4821-a05c-05fef961553f
components:
  schemas:
    SendBulkSMSRequest:
      type: object
      required:
        - messages
        - isGlobal
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/BulkSMSMessage'
          description: Array of SMS message objects to send
          minItems: 1
        isGlobal:
          type: boolean
          description: Whether to use global routing
          example: false
    BulkSMSResponse:
      type: object
      properties:
        statusCode:
          type: integer
          description: HTTP status code
          example: 201
        statusMessage:
          type: string
          description: Status message
          example: Bulk messages successfully sent
        transactionId:
          type: string
          description: Unique transaction identifier
          example: e43597d8-2fcb-479f-a4eb-68a3502efa4a
        sequenceNo:
          type: string
          nullable: true
          description: Sequence number
          example: null
        data:
          type: object
          properties:
            totalBatches:
              type: integer
              description: Total number of batches
              example: 1
            batches:
              type: array
              items:
                type: object
                properties:
                  jobId:
                    type: string
                    description: Unique job identifier
                    example: 27bf8f64-b804-4d99-b64b-b13efc67d5ed
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        to:
                          type: string
                          description: Recipient phone number
                          example: '233200746417'
                        from:
                          type: string
                          description: Sender ID
                          example: PHCCU
                        message:
                          type: string
                          description: SMS message content
                          example: "Dear TETTEH-KORBOE MARIAN (DR), GHS 224.52 Interest on Savings for the 3rd Quarter of 2023\r\nBalance GHS 24471.33.\r\nThank you. PHCCU… Happy Family!"
                        type:
                          type: string
                          description: SMS type
                          example: Quick
                        sequenceNo:
                          type: string
                          description: Message sequence number
                          example: 01K6MNZ814E5GDJ5Y95460QY9S
                        transactionId:
                          type: string
                          description: Transaction identifier
                          example: e43597d8-2fcb-479f-a4eb-68a3502efa4a
            senderAddress:
              type: string
              description: Sender address/ID
              example: PHCCU
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp
          example: '2025-10-03T09:20:40.575Z'
    BulkSMSMessage:
      type: object
      required:
        - to
        - from
        - message
        - type
      properties:
        to:
          type: string
          description: Recipient phone number (without + prefix)
          example: '233200746417'
        from:
          type: string
          description: Sender ID or name
          example: PHCCU
        message:
          type: string
          description: The SMS message content
          maxLength: 1600
          example: >-
            Dear TETTEH-KORBOE MARIAN (DR), GHS 224.52 Interest on Savings for
            the 3rd Quarter of 2023\r\nBalance GHS 24471.33.\r\nThank you.
            PHCCU… Happy Family!
        type:
          type: string
          description: SMS type (use 'Quick' for quick SMS)
          example: Quick
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key for authentication
    apiSecretAuth:
      type: apiKey
      in: header
      name: x-api-secret
      description: API Secret for authentication

````