Code Samples

Code samples for every use case

Copy-paste examples in JavaScript, Python, and cURL. Each sample uses real API endpoints and shows complete request and response handling.

Get your API keyBack to docs
SMS

SMS API samples

Send single messages, bulk campaigns, and handle delivery receipts with the Messages API.

Send single SMS

Send a single text message to one recipient with delivery tracking.

import { SakuraSMS } from "@sakura-sms/sdk";

const client = new SakuraSMS("sk_live_your_api_key");

const message = await client.messages.send({
  to: "+255712345678",
  from: "MYBRAND",
  body: "Hi Amina, your order #4821 has been confirmed. Expected delivery: tomorrow by 3 PM.",
});

console.log(message.sid);    // msg_abc123
console.log(message.status); // "sent"

Send bulk SMS

Send the same or personalized messages to multiple recipients in a single API call.

import { SakuraSMS } from "@sakura-sms/sdk";

const client = new SakuraSMS("sk_live_your_api_key");

const batch = await client.messages.sendBatch({
  from: "MYBRAND",
  messages: [
    { to: "+255712345678", body: "Flash sale starts now! 30% off all items. Shop: https://shop.example.com" },
    { to: "+255754321098", body: "Flash sale starts now! 30% off all items. Shop: https://shop.example.com" },
    { to: "+255688765432", body: "Flash sale starts now! 30% off all items. Shop: https://shop.example.com" },
  ],
});

console.log(batch.batch_id);      // batch_xyz789
console.log(batch.total_sent);    // 3
console.log(batch.total_failed);  // 0

Receive delivery receipt

Set up a webhook to receive real-time delivery status updates for every message.

// Express.js webhook handler for delivery receipts
import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/dlr", (req, res) => {
  const { message_id, status, to, delivered_at, error_code } = req.body;

  console.log(`Message ${message_id} to ${to}: ${status}`);
  // status: "delivered" | "failed" | "expired" | "rejected"

  if (status === "failed") {
    console.log(`Error code: ${error_code}`);
    // Handle retry logic
  }

  res.status(200).json({ received: true });
});

app.listen(3000);
WhatsApp

WhatsApp API samples

Send template messages, media, and handle incoming webhooks with the WhatsApp Business API.

Send template message

Send a pre-approved WhatsApp template message with dynamic parameters.

import { SakuraSMS } from "@sakura-sms/sdk";

const client = new SakuraSMS("sk_live_your_api_key");

const message = await client.whatsapp.sendTemplate({
  to: "+255712345678",
  template: {
    name: "order_confirmation",
    language: "en",
    components: [
      {
        type: "body",
        parameters: [
          { type: "text", text: "Amina" },
          { type: "text", text: "#4821" },
          { type: "text", text: "January 16, 2026" },
        ],
      },
    ],
  },
});

console.log(message.sid);      // wa_msg_def456
console.log(message.channel);  // "whatsapp"

Send media message

Send images, documents, or videos via WhatsApp with optional captions.

import { SakuraSMS } from "@sakura-sms/sdk";

const client = new SakuraSMS("sk_live_your_api_key");

const message = await client.whatsapp.sendMedia({
  to: "+255712345678",
  type: "image",
  media: {
    url: "https://cdn.example.com/products/shoe-red.jpg",
    caption: "New arrival: Red sneakers now in stock. TZS 45,000. Reply BUY to order.",
  },
});

console.log(message.sid);       // wa_msg_ghi789
console.log(message.media_id);  // media_abc123

Handle incoming webhook

Receive and process incoming WhatsApp messages from your customers.

// Express.js webhook handler for incoming WhatsApp messages
import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/whatsapp", (req, res) => {
  const { event, message } = req.body;

  if (event === "message.received") {
    console.log(`From: ${message.from}`);
    console.log(`Body: ${message.body}`);
    console.log(`Type: ${message.type}`); // "text" | "image" | "document"

    // Auto-reply example
    if (message.body.toUpperCase() === "BUY") {
      // Trigger order flow
      console.log("Processing order...");
    }
  }

  res.status(200).json({ received: true });
});

app.listen(3000);
OTP / Verify

OTP and verification samples

Request and validate one-time passwords with automatic channel fallback and fraud detection.

Request OTP

Generate and send a one-time password to a phone number via SMS, WhatsApp, or voice.

import { SakuraSMS } from "@sakura-sms/sdk";

const client = new SakuraSMS("sk_live_your_api_key");

const verification = await client.verify.request({
  to: "+255712345678",
  channel: "sms",              // "sms" | "whatsapp" | "voice"
  code_length: 6,
  expiry: 300,                 // seconds (5 minutes)
  brand_name: "MyApp",
  template: "Your {{brand}} code is {{code}}. Expires in 5 minutes.",
});

console.log(verification.request_id);  // ver_mno345
console.log(verification.status);      // "pending"
console.log(verification.channel);     // "sms"

Verify OTP

Validate the code entered by the user and confirm their identity.

import { SakuraSMS } from "@sakura-sms/sdk";

const client = new SakuraSMS("sk_live_your_api_key");

const result = await client.verify.check({
  request_id: "ver_mno345",
  code: "482910",
});

console.log(result.status);  // "approved" | "expired" | "invalid"
console.log(result.valid);   // true

if (result.valid) {
  // User verified successfully -- proceed with login / transaction
  console.log("Verification successful");
} else {
  console.log(`Verification failed: ${result.status}`);
}
Contacts

Contacts API samples

Manage your contact lists with tags, custom fields, and powerful filtering.

Create contact

Add a new contact to your address book with tags and custom fields.

import { SakuraSMS } from "@sakura-sms/sdk";

const client = new SakuraSMS("sk_live_your_api_key");

const contact = await client.contacts.create({
  phone: "+255712345678",
  first_name: "Amina",
  last_name: "Mwangi",
  email: "[email protected]",
  tags: ["vip", "dar-es-salaam"],
  custom_fields: {
    company: "Karibu Ltd",
    tier: "premium",
  },
});

console.log(contact.id);         // con_pqr678
console.log(contact.phone);      // "+255712345678"
console.log(contact.created_at); // "2026-01-15T10:00:00Z"

List contacts

Retrieve a paginated list of contacts with filtering and sorting options.

import { SakuraSMS } from "@sakura-sms/sdk";

const client = new SakuraSMS("sk_live_your_api_key");

const result = await client.contacts.list({
  page: 1,
  per_page: 25,
  tags: ["vip"],
  sort: "created_at",
  order: "desc",
});

console.log(result.total);       // 142
console.log(result.page);        // 1
console.log(result.per_page);    // 25

for (const contact of result.contacts) {
  console.log(`${contact.first_name} ${contact.last_name}: ${contact.phone}`);
}

Ready to build? Get your API key

Create a free account and start sending messages in minutes. 100 free test messages included.

Create accountBack to docs