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

# Send SMS

> Send an SMS message to one or more recipients. Supports JSON (`application/json`) and XML (`application/xml`) request bodies.



## OpenAPI

````yaml /openapi/sms.json post /v1/send
openapi: 3.0.3
info:
  title: Beem SMS API
  version: 1.0.0
  description: >-
    The Beem SMS API provides endpoints for sending SMS, checking balance,
    delivery reports, sender names, and SMS templates.
  contact:
    name: Beem
    url: https://beem.africa
    email: support@beem.africa
servers:
  - url: https://apisms.beem.africa
    description: Production server
  - url: https://dev-sms.beem.africa
    description: Staging server
security: []
tags: []
paths:
  /v1/send:
    post:
      summary: Send SMS
      description: >-
        Send an SMS message to one or more recipients. Supports JSON
        (`application/json`) and XML (`application/xml`) request bodies.
      operationId: sendSms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - source_addr
                - message
                - encoding
                - recipients
              properties:
                source_addr:
                  type: string
                  description: >-
                    Sender ID. Alphanumeric sender IDs must not exceed 11
                    characters. Must be active on your account.
                  example: INFO
                message:
                  type: string
                  description: SMS message text.
                  example: Hello World
                encoding:
                  type: integer
                  description: Message encoding type. Use 0 for default GSM encoding.
                  example: 0
                recipients:
                  type: array
                  description: List of message recipients.
                  items:
                    type: object
                    required:
                      - recipient_id
                      - dest_addr
                    properties:
                      recipient_id:
                        type: integer
                        description: >-
                          Unique reference ID for this recipient within the
                          request.
                        example: 1
                      dest_addr:
                        type: string
                        description: >-
                          Destination mobile number in international format
                          without a leading + sign.
                        example: '255700000001'
                  minItems: 1
                schedule_time:
                  type: string
                  description: >-
                    Optional scheduled send time in GMT+0 using the format
                    `yyyy-mm-dd hh:mm`. Leave empty to send immediately.
                  example: ''
                job_name:
                  type: string
                  description: Optional job name for tracking.
                campaign_title:
                  type: string
                  description: Optional campaign title for tracking.
            examples:
              singleRecipient:
                summary: Single recipient
                value:
                  source_addr: INFO
                  schedule_time: ''
                  encoding: 0
                  message: Hello World
                  recipients:
                    - recipient_id: 1
                      dest_addr: '255700000001'
              multipleRecipients:
                summary: Multiple recipients
                value:
                  source_addr: INFO
                  schedule_time: ''
                  encoding: 0
                  message: Hello world
                  recipients:
                    - recipient_id: 1
                      dest_addr: '255700000001'
                    - recipient_id: 2
                      dest_addr: '255700000002'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  successful:
                    description: True when the message was accepted for processing.
                    type: boolean
                  request_id:
                    description: >-
                      Beem transaction ID — use with delivery reports to track
                      status.
                    type: string
                  code:
                    description: API response code (100 = success).
                    type: integer
                  message:
                    description: Human-readable status message.
                    type: string
                  valid:
                    description: Number of valid recipients accepted.
                    type: integer
                  invalid:
                    description: Number of recipients rejected due to validation errors.
                    type: integer
                  duplicates:
                    description: Number of duplicate recipient entries removed.
                    type: integer
                  opted_out:
                    description: Number of recipients who have opted out of SMS.
                    type: integer
                  total_validated:
                    description: Total number of recipients validated in the request.
                    type: integer
                additionalProperties: false
                required:
                  - successful
                  - request_id
                  - code
                  - message
                  - valid
                  - invalid
                  - duplicates
                  - opted_out
                  - total_validated
        '400':
          description: Bad request — invalid parameters or missing authorization header.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              examples:
                invalidSenderId:
                  summary: Invalid Sender ID
                  value:
                    code: 111
                    message: Invalid Sender ID
                missingAuthorization:
                  summary: Missing authorization header
                  value:
                    error: No authorization headers
        '401':
          description: Unauthorized — invalid or missing API credentials.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: API error code.
                    example: 120
                  message:
                    type: string
                    description: Error message.
                required:
                  - code
                  - message
                additionalProperties: true
              examples:
                invalidAuthentication:
                  summary: Invalid authentication
                  value:
                    code: 120
                    message: Invalid Authentication Parameters
      security:
        - basicAuth: []
        - accessToken: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Beem API credentials: API key as username, API secret as password.'
    accessToken:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Access token only. Send as Authorization: <token> — do not use a Bearer
        prefix.

````