Send SMS

This endpoint is the core functionality of HudumaSMS, allowing you to send SMS messages to one or multiple recipients. You can send personalized messages to different recipients in a single API call.

Endpoint

POST /sms/send

Authentication

All requests must include your API token in the header:

X-Huduma: Bearer {your_api_token}

JSON Body

For advanced usage, such as sending to multiple recipients or setting callbacks, use a JSON request body:

Parameter	Type	Required	Description
senderId	string	Yes	Your sender ID/name (must be registered in your account)
envelopes	array	Yes	Array of message envelopes (recipients and messages)
envelopes[].message	string	Yes	Message text for this recipient
envelopes[].number	string	Yes	Recipient's phone number in international format
envelopes[].thirdPartyRef	string	No	Custom reference ID for tracking in your system
callbackUrl	string	No	URL to receive delivery status notifications

Example Request Body:

{
  "senderId": "COMPANY",
  "envelopes": [
    {
      "message": "Hello John, your order #12345 has been shipped!",
      "number": "255712345678",
      "thirdPartyRef": "order-12345"
    },
    {
      "message": "Hello Jane, your appointment is confirmed for tomorrow at 2 PM.",
      "number": "255787654321",
      "thirdPartyRef": "appointment-54321"
    }
  ],
  "callbackUrl": "https://your-website.com/sms-callbacks"
}

Response

Success Response (202 Accepted)

A successful request returns a JSON response with the following structure:

{
  "status": "202 ACCEPTED",
  "code": 0,
  "message": "SMS messages queued successfully",
  "timestamp": "2025-04-10T08:12:54.810Z",
  "reqId": "req-123456789",
  "path": "/sms/send",
  "data": {
    "balance": 253,
    "outgoings": [
      {
        "id": 654321,
        "senderId": "COMPANY",
        "recipient": "255712345678",
        "message": "Hello John, your order #12345 has been shipped!",
        "credits": 1,
        "schedule": null,
        "status": "QUEUED",
        "smscId": "sms-987654321",
        "callbackUrl": "https://your-website.com/sms-callbacks",
        "thirdPartyRef": "order-12345",
        "addedBy": {
          "id": 1234,
          "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "firstName": "API",
          "lastName": "User",
          "gender": "N/A",
          "email": "user@example.com",
          "phone": "255712345678",
          "address": ""
        },
        "createdAt": "2025-04-10T08:12:54.810Z",
        "updatedAt": "2025-04-10T08:12:54.810Z"
      }
    ]
  }
}

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API token
402	Payment Required - Insufficient credits
403	Forbidden - Insufficient permissions or unauthorized sender ID
404	Not Found - Resource not found
405	Method Not Allowed - Invalid HTTP method
422	Unprocessable Entity - Invalid input parameters
500	Internal Server Error - Server-side error

Error Response Format

{
  "status": "400 BAD REQUEST",
  "code": 4000,
  "message": "Invalid request parameters",
  "timestamp": "2025-04-10T08:12:54.812Z",
  "reqId": "req-123456789",
  "path": "/sms/send",
  "errors": [
    {
      "field": "envelopes[0].number",
      "message": "Must be a valid phone number in international format",
      "rejectedValue": "12345",
      "rejectingValues": {}
    }
  ]
}

Code Examples

TypeScript Example

import axios from 'axios';

interface SMSEnvelope {
  message: string;
  number: string;
  thirdPartyRef?: string;
}

interface SendSMSRequest {
  senderId: string;
  envelopes: SMSEnvelope[];
  callbackUrl?: string;
}

interface SendSMSResponse {
  status: string;
  code: number;
  message: string;
  timestamp: string;
  reqId: string;
  path: string;
  data: {
    balance: number;
    outgoings: Array<{
      id: number;
      senderId: string;
      recipient: string;
      message: string;
      credits: number;
      schedule: string | null;
      status: string;
      smscId: string;
      callbackUrl: string | null;
      thirdPartyRef: string | null;
      addedBy: {
        id: number;
        uuid: string;
        firstName: string;
        lastName: string;
        gender: string;
        email: string;
        phone: string;
        address: string;
      };
      createdAt: string;
      updatedAt: string;
    }>;
  };
}


// Method 1: Bulk SMS (using JSON body)
async function sendBulkSMS(
  apiToken: string,
  request: SendSMSRequest
): Promise<SendSMSResponse> {
  try {
    const response = await axios.post(
      'https://sms-api.huduma.cloud/api/v3/sms/send',
      request,
      {
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error sending SMS:', error);
    throw error;
  }
}

// Example usage - Simple SMS
const apiToken = 'your_api_token_here';
sendSimpleSMS(apiToken, 'COMPANY', '255712345678', 'Hello from HudumaSMS!')
  .then(response => {
    console.log('SMS sent successfully:', response.data);
  })
  .catch(error => {
    console.error('Failed to send SMS:', error.response?.data || error.message);
  });

// Example usage - Bulk SMS
const bulkRequest: SendSMSRequest = {
  senderId: 'COMPANY',
  envelopes: [
    {
      message: 'Hello John, your package has arrived!',
      number: '255712345678',
      thirdPartyRef: 'pkg-123'
    },
    {
      message: 'Hello Jane, your invoice is due tomorrow.',
      number: '255787654321',
      thirdPartyRef: 'inv-456'
    }
  ],
  callbackUrl: 'https://your-website.com/sms-callbacks'
};

sendBulkSMS(apiToken, bulkRequest)
  .then(response => {
    console.log(`${response.data.outgoings.length} SMS messages sent successfully`);
    console.log(`Remaining balance: ${response.data.balance} credits`);
  })
  .catch(error => {
    console.error('Failed to send SMS:', error.response?.data || error.message);
  });

JavaScript Example

const axios = require('axios');


// Method 1: Bulk SMS (using JSON body)
async function sendBulkSMS(apiToken, request) {
  try {
    const response = await axios.post(
      'https://sms-api.huduma.cloud/api/v3/sms/send',
      request,
      {
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error sending SMS:', error);
    throw error;
  }
}

// Example usage - Simple SMS
const apiToken = 'your_api_token_here';
sendSimpleSMS(apiToken, 'COMPANY', '255712345678', 'Hello from HudumaSMS!')
  .then(response => {
    console.log('SMS sent successfully:', response.data);
  })
  .catch(error => {
    console.error('Failed to send SMS:', error.response?.data || error.message);
  });

// Example usage - Bulk SMS
const bulkRequest = {
  senderId: 'COMPANY',
  envelopes: [
    {
      message: 'Hello John, your package has arrived!',
      number: '255712345678',
      thirdPartyRef: 'pkg-123'
    },
    {
      message: 'Hello Jane, your invoice is due tomorrow.',
      number: '255787654321',
      thirdPartyRef: 'inv-456'
    }
  ],
  callbackUrl: 'https://your-website.com/sms-callbacks'
};

sendBulkSMS(apiToken, bulkRequest)
  .then(response => {
    console.log(`${response.data.outgoings.length} SMS messages sent successfully`);
    console.log(`Remaining balance: ${response.data.balance} credits`);
  })
  .catch(error => {
    console.error('Failed to send SMS:', error.response?.data || error.message);
  });

Additional Notes

• Phone numbers must be in international format with the country code (e.g., 255 for Tanzania) without the plus sign (+).
• The senderId must be registered in your account. Contact support if you need to register a new sender ID.
• Each SMS message consumes credits based on the message length and destination. The response includes your remaining credit balance.
• Message delivery is asynchronous. The 202 Accepted response indicates the messages have been queued for delivery.
• You can track delivery status using the thirdPartyRef in your system or by setting up a callbackUrl to receive status updates.
• For Unicode messages (non-Latin alphabets), message length limits may differ, and credit consumption may be higher.
• The maximum length for a single SMS is 160 characters for plain text (GSM 03.38 character set) or 70 characters for Unicode messages. Longer messages will be automatically split into multiple segments.