SMS API Quick Start Guide

Send SMS via API

The Sakura SMS API lets you send SMS messages programmatically. This guide covers authentication, the correct request format, and working examples in multiple languages.

Endpoint

POST https://sms.sakuragroup.co.tz/api/v1/messages

Authentication

Include your API key as a Bearer token in the Authorization header:

Authorization: Bearer sk_live_your_api_key

Generate API keys at Portal > Developer > API Keys.

Request Body

Field	Type	Required	Description
to	string or string[]	Yes	Recipient number(s). Format: 255XXXXXXXXX or 07XXXXXXXX
sender	string	Yes	Your approved sender name (max 11 characters)
message	string	Yes	SMS text content
idempotency_key	string	No	Unique key to prevent duplicate sends

cURL Example

curl -X POST https://sms.sakuragroup.co.tz/api/v1/messages \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "255712345678",
    "sender": "MYBRAND",
    "message": "Hello from Sakura SMS!"
  }'

Send to Multiple Recipients

{
  "to": ["255712345678", "255698765432", "0754321098"],
  "sender": "MYBRAND",
  "message": "Flash sale! 30% off all items today."
}

JavaScript / Node.js

const response = await fetch(
  "https://sms.sakuragroup.co.tz/api/v1/messages",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: "255712345678",
      sender: "MYBRAND",
      message: "Hello from Sakura SMS!",
    }),
  }
);
const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://sms.sakuragroup.co.tz/api/v1/messages",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "to": "255712345678",
        "sender": "MYBRAND",
        "message": "Hello from Sakura SMS!",
    },
)
print(response.json())

PHP

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "https://sms.sakuragroup.co.tz/api/v1/messages",
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $apiKey,
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "to" => "255712345678",
        "sender" => "MYBRAND",
        "message" => "Hello from Sakura SMS!",
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo $response;

Google Apps Script

function sendSMS() {
  var options = {
    method: "post",
    contentType: "application/json",
    headers: {
      "Authorization": "Bearer sk_live_your_api_key"
    },
    payload: JSON.stringify({
      to: "255712345678",
      sender: "MYBRAND",
      message: "Hello from Sakura SMS!",
    }),
  };
  var response = UrlFetchApp.fetch(
    "https://sms.sakuragroup.co.tz/api/v1/messages",
    options
  );
  Logger.log(response.getContentText());
}

Success Response (201)

{
  "id": "clx1234abc...",
  "status": "queued",
  "to": ["255712345678"],
  "from": "MYBRAND",
  "cost": 1,
  "segments": 1,
  "provider_id": "abc123"
}

Error Codes

Code	Meaning	Fix
401	Invalid API key	Check your Bearer token is correct and active
402	Insufficient credits	Top up your balance at Portal > Billing
403	Account not approved	Wait for admin approval or contact support
422	Missing required fields	Ensure to, sender, and message are all present
429	Rate limit exceeded	Max 300 requests/minute. Wait and retry.
502	Provider error	Gateway issue. Retry after a few seconds.

Sender IDs

You must use an approved sender ID. To request a new one:

• Go to Portal > Sender IDs
• Click Request New Sender ID
• Enter a name related to your business (max 11 characters, no generic names like "PROMO")
• Approval typically takes 1-2 business days

Rate Limits

• 300 requests per minute per API key
• Use the to array to send to multiple recipients in one request (more efficient than individual calls)
• Check X-RateLimit-Remaining header in responses

Webhooks for Delivery Status

Set up webhooks at Portal > Developer > Webhooks to receive real-time delivery notifications. Configure a URL and select the events you want to track (delivered, failed, etc.).