API Documentation

Base URL: https://sms.macrasms.com/api/v1/

1. Overview

This API allows you to send single or bulk SMS messages using your Macra SMS account. Authentication is done via sender_id and api_key passed in the JSON body.

2. Send SMS Endpoint

Request Headers

• Content-Type: application/json

Request Body (JSON)

Example Request Body

{
  "sender_id": "MACRASMS",
  "api_key": "6bd654a1ed437c7d0d60a48c2d3b4911de685cfad68aff35a531b3f7491835fa",
  "message_text": "Hello! Your verification code is 48291.",
  "recipients": "+254712345678,0712345678",
  "scheduled_at": "2026-02-15 10:00:00"
}

3. Response Format

The API always returns HTTP 200 OK with JSON content.

Success Response

{
  "success": true,
  "message_ids": [1456, 1457],
  "credits_used": 2,
  "recipients_count": 2,
  "new_balance": 1247,
  "message_length": 68,
  "credits_per_message": 1,
  "transaction_id": 8923
}

Error Response

{
  "success": false,
  "error": "Invalid sender_id or api_key"
}

Common Error Messages

• "Missing required parameters"
• "Invalid phone number: ..."
• "No valid recipients"
• "Max 100 recipients allowed"
• "Message too long (>1600 chars)"
• "Invalid sender_id or api_key"
• "Insufficient credits. Need X, have Y"

4. Limits & Rules

• Maximum 100 recipients per request
• Maximum message length: 1600 characters
• Cost: ceil(message_length / 160) credits per recipient
• Phone numbers are automatically normalized to +254... format
• Unicode messages are supported (may use more credits per segment)

5. Sample Code – Sending SMS

PHP (cURL)

<?php
$payload = [
    'sender_id'     => 'MACRASMS',
    'api_key'       => 'your-api-key-here',
    'message_text'  => 'Test message from PHP',
    'recipients'    => '+254712345678,0712345678'
];

$ch = curl_init('https://sms.macrasms.com/api/v1/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data['success'] ?? false) {
    echo "Success! Sent to {$data['recipients_count']} recipients.\n";
} else {
    echo "Error: " . ($data['error'] ?? 'Unknown') . "\n";
}
?>

Python (requests)

import requests

payload = {
    "sender_id": "MACRASMS",
    "api_key": "your-api-key-here",
    "message_text": "Hello from Python!",
    "recipients": "+254712345678,0712345678"
}

response = requests.post(
    "https://sms.macrasms.com/api/v1/",
    json=payload
)

data = response.json()

if data.get("success"):
    print(f"Success → {data['recipients_count']} sent")
else:
    print(f"Failed: {data.get('error')}")

JavaScript (fetch)

const payload = {
  sender_id: "MACRASMS",
  api_key: "your-api-key-here",
  message_text: "Test from JS",
  recipients: "+254712345678,+254723456789"
};

fetch("https://sms.macrasms.com/api/v1/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload)
})
  .then(res => res.json())
  .then(data => {
    if (data.success) {
      console.log(`Sent to ${data.recipients_count} numbers`);
    } else {
      console.error("Error:", data.error);
    }
  })
  .catch(err => console.error(err));