TypeScript SDK

npm install sendafrica

import { SendAfricaClient } from 'sendafrica'
 
const client = new SendAfricaClient({
  apiKey: process.env.SENDAFRICA_API_KEY!,
})
 
const result = await client.sms.send({
  to: '0712345678',
  message: 'Your verification code is 4921.',
})
 
console.log(result.messageId, result.status, result.creditsUsed)

import { SendAfricaClient } from 'sendafrica'
 
const client = new SendAfricaClient({
  apiKey: 'SA-...',                            // required
  baseUrl: 'https://api.sendafrica.online/v1', // optional override
  timeoutMs: 15_000,                           // optional, default 15000
  maxRetries: 2,                               // optional, default 2
  fetch: customFetch,                          // optional: supply your own fetch
})

const result = await client.sms.send(
  {
    to: '0712345678',
    message: 'Welcome to SendAfrica!',
    from: 'SENDAFRICA', // optional registered sender ID
  },
  {
    idempotencyKey: 'order-123', // optional safe retries
  }
)
 
console.log(result.messageId, result.creditsUsed, result.requestId)

const res = await client.sms.sendMany(
  [
    { to: '0712345678', message: 'Hi Ali' },
    { to: '0765432109', message: 'Hi Zainab', idempotencyKey: 'm2' },
  ],
  { rateLimitPerSec: 10.0 } // default 10
)
console.log(res.results.length, res.failed)

const bulk = await client.sms.bulk({
  to: ['0712345678', '0765432109'],
  message: 'Black Friday starts now!',
  from: 'MYBRAND',
})
console.log(bulk.total, bulk.sent, bulk.failed)
for (const r of bulk.results) {
  console.log(r.to, r.status, r.messageId, r.error)
}

const logs = await client.sms.logs({
  page: 1,
  perPage: 25,
  status: 'delivered',        // pending | sent | delivered | failed
  search: '0712345678',
  dateFrom: '2026-09-01T00:00:00Z',
})
for (const entry of logs.items) {
  console.log(entry.toPhone, entry.status, entry.creditsUsed, entry.deliveredAt)
}

const logs = await client.sms.logsJwt(jwtToken, { page: 1, perPage: 25, status: 'sent' })

const balance = await client.credits.balance()
console.log(balance.accountId, balance.balance)
 
const history = await client.credits.history({ page: 1, perPage: 25 })
for (const txn of history) {
  console.log(txn.type, txn.amount, txn.balanceAfter, txn.description)
}

const rates = await client.rates.list()
for (const r of rates) console.log(r.name, r.iso2, r.rateTzs)
 
const tz = await client.rates.get('TZ')
console.log(tz.name, tz.rateTzs)

const reqs = await client.senderIds.requirements()
console.log(reqs.eligibility?.canRequest, reqs.purposes)
 
const usable = await client.senderIds.usable('swala')
const all = await client.senderIds.list()
 
const created = await client.senderIds.create({
  name: 'MYBRAND',
  country: 'TZ',
  purpose: 'Marketing',
  sampleMessage: 'Welcome to MYBRAND',
  documents: [{ requirementUid: '...', filename: 'doc.pdf', contentBase64: '...' }],
})
 
const one = await client.senderIds.get(created.id)
await client.senderIds.setDefault(created.id)

const rate = await client.payments.rate()
console.log(rate.minAmountTzs, rate.tiers)
 
const payment = await client.payments.create(
  {
    provider: 'snippe',       // or 'manual'
    amount: 10000,            // TZS — credits computed server-side
    phone: '0712345678',
  },
  { idempotencyKey: 'topup-42' }
)
console.log(payment.id, payment.status, payment.creditAmount)

await client.payments.sendDeclaredPhoneOtp('0765432109')
await client.payments.verifyDeclaredPhoneOtp('0765432109', '4921')

import crypto from 'node:crypto'
import { NextResponse } from 'next/server'
 
export async function POST(request: Request) {
  const rawBody = await request.text()
  const expected = crypto
    .createHmac('sha256', process.env.SENDAFRICA_WEBHOOK_SECRET!)
    .update(rawBody)
    .digest('hex')
  const actual = request.headers.get('x-sendafrica-signature') ?? ''
 
  if (
    actual.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(actual))
  ) {
    return NextResponse.json({ error: 'invalid signature' }, { status: 401 })
  }
 
  const event = JSON.parse(rawBody)
  console.log(event.event, event.message_id, event.to, event.status)
  return NextResponse.json({ ok: true }) // durable work before this return
}

import {
  normalizeTzPhone,
  isValidTzPhone,
  TZ_MOBILE_PREFIXES,
  detectEncoding,
  getSmsPartInfo,
  countSmsParts,
} from 'sendafrica'
 
normalizeTzPhone('0712345678')     // '+255712345678'
isValidTzPhone('0712345678')       // true
getSmsPartInfo('Hello world')      // { encoding: 'GSM-7', length: 11, parts: 1, creditsRequired: 1 }
countSmsParts('Long message...')   // number of parts

import {
  SendAfricaError,
  SendAfricaNetworkError,
} from 'sendafrica'
 
try {
  await client.sms.send({ to: '999', message: 'test' })
} catch (err) {
  if (err instanceof SendAfricaError) {
    console.log(err.code, err.message, err.requestId, err.httpStatus)
    if (err.isInsufficientCredits) { /* 402 */ }
    if (err.isRateLimited) { /* 429 */ }
    if (err.isUnauthorized) { /* 401 */ }
  } else if (err instanceof SendAfricaNetworkError) {
    console.error('network failure or timeout', err.cause)
  }
}