List SMS Messages

This endpoint allows you to retrieve a paginated list of SMS messages. You can filter the results and control pagination using query parameters.

Endpoint

GET /sms

Authentication

All requests must include your API token in the header:

X-Huduma: Bearer {your_api_token}

Query Parameters

Parameter	Type	Required	Description
records	integer	No	Number of records to return per page. Default is 10.
page	integer	No	Page number for pagination. Default is 1.
sort	array[string]	No	Sort order for results. Default is ["id", "desc"].
userId	integer	No	Filter SMS by specific user ID (for admin accounts).
status	string	No	Filter SMS by status. Default is 'all'.
start-date	string($date)	No	Filter SMS sent after this date. Format: YYYY-MM-DD.
end-date	string($date)	No	Filter SMS sent before this date. Format: YYYY-MM-DD.
campaign-id	string($uuid)	No	Filter SMS by specific campaign ID.
query	string	No	Search term to filter SMS by content or recipient.

Response

Success Response (200 OK)

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

{
  "status": "200 OK",
  "code": 0,
  "message": "SMS messages retrieved successfully",
  "timestamp": "2025-04-10T08:29:14.061Z",
  "reqId": "req-987654321",
  "path": "/sms",
  "data": {
    "content": [
      {
        "id": 12345,
        "recipient": "255712345678",
        "content": "Your verification code is 123456",
        "status": "DELIVERED",
        "sentAt": "2025-04-09T14:30:22Z",
        "deliveredAt": "2025-04-09T14:30:25Z",
        "campaignId": "550e8400-e29b-41d4-a716-446655440000",
        "userId": 789
      },
      {
        "id": 12346,
        "recipient": "255723456789",
        "content": "Your order #45678 has been shipped!",
        "status": "SENT",
        "sentAt": "2025-04-09T15:20:10Z",
        "deliveredAt": null,
        "campaignId": "550e8400-e29b-41d4-a716-446655440000",
        "userId": 789
      }
    ],
    "pagination": {
      "pageNumber": 1,
      "pageSize": 10,
      "sorted": true,
      "totalPages": 5,
      "totalElements": 42,
      "last": false,
      "numberOfElements": 10,
      "first": true,
      "empty": false
    }
  }
}

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API token
402	Payment Required - Account has payment issues
403	Forbidden - Insufficient permissions
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:29:14.066Z",
  "reqId": "req-987654321",
  "path": "/sms",
  "errors": [
    {
      "field": "start-date",
      "message": "Must be a valid date format (YYYY-MM-DD)",
      "rejectedValue": "2025/04/01",
      "rejectingValues": {}
    }
  ]
}

Code Examples

TypeScript Example

import axios from 'axios';

interface SMSListParams {
  records?: number;
  page?: number;
  sort?: string[];
  userId?: number;
  status?: string;
  'start-date'?: string;
  'end-date'?: string;
  'campaign-id'?: string;
  query?: string;
}

interface SMS {
  id: number;
  recipient: string;
  content: string;
  status: string;
  sentAt: string;
  deliveredAt: string | null;
  campaignId: string;
  userId: number;
}

interface SMSListResponse {
  status: string;
  code: number;
  message: string;
  timestamp: string;
  reqId: string;
  path: string;
  data: {
    content: SMS[];
    pagination: {
      pageNumber: number;
      pageSize: number;
      sorted: boolean;
      totalPages: number;
      totalElements: number;
      last: boolean;
      numberOfElements: number;
      first: boolean;
      empty: boolean;
    }
  }
}

async function listSMS(
  apiToken: string,
  params: SMSListParams = {}
): Promise<SMSListResponse> {
  try {
    const response = await axios.get(
      'https://sms-api.huduma.cloud/api/v3/sms',
      {
        params,
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Accept': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error listing SMS messages:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';

// List SMS messages with filters
listSMS(apiToken, {
  records: 20,
  page: 1,
  status: 'DELIVERED',
  'start-date': '2025-04-01',
  'end-date': '2025-04-10'
})
  .then(response => {
    console.log(`Found ${response.data.pagination.totalElements} SMS messages`);
    console.log('First page of results:', response.data.content);
    
    // Process each SMS
    response.data.content.forEach(sms => {
      console.log(`To: ${sms.recipient}, Status: ${sms.status}, Content: ${sms.content}`);
    });
  })
  .catch(error => {
    console.error('Failed to list SMS messages:', error.response?.data || error.message);
  });

JavaScript Example

const axios = require('axios');

async function listSMS(apiToken, params = {}) {
  try {
    const response = await axios.get(
      'https://sms-api.huduma.cloud/api/v3/sms',
      {
        params,
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Accept': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error listing SMS messages:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';

// List SMS messages from a specific campaign
listSMS(apiToken, {
  'campaign-id': '550e8400-e29b-41d4-a716-446655440000',
  status: 'all'
})
  .then(response => {
    console.log(`Found ${response.data.pagination.totalElements} SMS messages`);
    
    // Display SMS information
    response.data.content.forEach(sms => {
      console.log(`ID: ${sms.id}, To: ${sms.recipient}, Status: ${sms.status}`);
      console.log(`Content: ${sms.content}`);
      console.log('---');
    });
    
    // Check if there are more pages
    if (response.data.pagination.totalPages > 1) {
      console.log(`There are ${response.data.pagination.totalPages} pages of SMS messages available.`);
    }
  })
  .catch(error => {
    console.error('Failed to list SMS messages:', error.response?.data || error.message);
  });

Additional Notes

• The maximum number of records per page is 100.
• The query parameter searches across SMS content and recipient numbers.
• Possible values for the status parameter include: 'DELIVERED', 'SENT', 'FAILED', 'PENDING', or 'all'.
• Results can be sorted by various fields including 'id', 'sentAt', 'status', etc. Use an array like ["sentAt", "desc"].
• The start-date and end-date parameters accept dates in the format YYYY-MM-DD.
• For admin accounts, the userId parameter can be used to filter SMS by specific user.
• Campaign-specific messages can be retrieved using the campaign-id parameter.