Dashboard Top Up Send SMS History API Keys Sender IDs Contact Us Sign Out

API Documentation

Complete guide for integrating with TAPSA Bulk SMS API

🚀 Quick Start

  1. Generate an API key from the API Keys page
  2. Include the API key in the X-API-Key header
  3. Start making requests to the API endpoints
// Example: Check balance
curl -X GET \
  -H "X-API-Key: your_api_key_here" \
  https://api.smstapsa.site/v1/account/balance

🔐 Authentication

All API requests must include your API key in the header:

X-API-Key: your_api_key_here
Note: Keep your API keys secure. Do not expose them in client-side code.

📡 API Endpoints

GET
/v1/account/balance

Check your current SMS balance and account information.

Response

{
  "success": true,
  "balance": 150,
  "currency": "TZS",
  "smsRate": 30
}
POST
/v1/sms/send

Send SMS messages to one or multiple recipients.

Request Body

{
  "phoneNumbers": ["255712345678", "255765432100"],
  "message": "Hello from TAPSA!",
  "senderId": "TAPSA"
}

Parameters

Parameter Type Required Description
phoneNumbers Array/String Yes Recipient phone numbers (255XXXXXXXXX format)
message String Yes SMS message content (max 160 characters)
senderId String No Sender ID (default: "TAPSA")

Response

{
  "success": true,
  "message": "Messages processed",
  "senderId": "TAPSA",
  "recipients": [...],
  "deducted": 2,
  "remainingBalance": 148
}

💻 Code Examples

Send SMS with JavaScript

async function sendSMS() {
  const response = await fetch('https://api.smstapsa.site/v1/sms/send', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phoneNumbers: ['255712345678'],
      message: 'Hello from our app!',
      senderId: 'TAPSA'
    })
  });
  
  const result = await response.json();
  console.log(result);
}

Send SMS with Python

import requests

url = "https://api.smstapsa.site/v1/sms/send"
headers = {
    "X-API-Key": "your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "phoneNumbers": ["255712345678"],
    "message": "Hello from our app!",
    "senderId": "TAPSA"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Send SMS with PHP

$url = "https://api.smstapsa.site/v1/sms/send";
$data = [
    'phoneNumbers' => ['255712345678'],
    'message' => 'Hello from our app!',
    'senderId' => 'TAPSA'
];

$options = [
    'http' => [
        'header' => 
            "X-API-Key: your_api_key_here\r\n" .
            "Content-Type: application/json\r\n",
        'method' => 'POST',
        'content' => json_encode($data)
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Send SMS with cURL

curl -X POST \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumbers": ["255712345678"],
    "message": "Hello from our app!",
    "senderId": "TAPSA"
  }' \
  https://api.smstapsa.site/v1/sms/send

🚨 Error Handling

The API uses standard HTTP status codes:

Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
402 Insufficient balance
500 Internal server error

Error Response Format

{
  "success": false,
  "error": "Error message description"
}

💬 Support

Need help with integration?