Developer Documentation

A developer-friendly API for reliable SMS delivery.

Integrate standard and bulk SMS into your web applications, e-commerce stores, and backend microservices with predictable JSON endpoints, atomic idempotency, and real-time webhooks.

Base URL: https://api.smsgenix.net/v1

Interactive Reference

Core Endpoints

Idempotency Guarantee

Pass an Idempotency-Key header with retry calls. If a network drop occurs, our server returns the cached response without double-debiting funds or sending duplicate SMS.

Request Payload

curl -X POST https://api.smsgenix.net/v1/messages \
  -H "Authorization: Bearer sk_live_9a7b...4c2d" \
  -H "Idempotency-Key: idemp_9281048291" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+94771234567",
    "sender": "SMSGENIX",
    "text": "Your order #1042 has been confirmed.",
    "projectId": "proj_marketing"
  }'

200 OK Responseapplication/json

{
  "id": "msg_01J8P4S1",
  "status": "QUEUED",
  "to": "+94771234567",
  "sender": "SMSGENIX",
  "encoding": "GSM-7",
  "segments": 1,
  "costMinor": 250,
  "currency": "LKR",
  "createdAt": "2026-09-17T08:12:00.000Z"
}

Event Notifications

Real-time delivery webhooks.

Receive HTTP POST callbacks to your endpoint whenever a message status changes. Each webhook payload is signed with a shared HMAC-SHA256 secret in the X-SMSGenix-Signature header.

message.delivered

Handset delivery confirmed by operator network.

message.failed

Undeliverable number, invalid prefix, or carrier timeout.

wallet.low_balance

Prepaid balance dropped below your low-balance threshold.

Verify Webhook Signature (Node.js)

import crypto from 'crypto';

function verifySignature(payload, signatureHeader, secret) {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(hmac),
    Buffer.from(signatureHeader)
  );
}

Error Handling

Customer-Safe Error Codes

Our API returns clear, standardized error messages without leaking internal routing or upstream carrier infrastructure.

HTTP Status	Error Code	Description	Recommended Action
400	INVALID_DESTINATION	Phone number is not a valid E.164 format (+94...).	Validate number prefix before retrying.
401	UNAUTHORIZED	API key is missing, revoked, or invalid.	Check Bearer token in request header.
402	INSUFFICIENT_FUNDS	Organisation wallet balance or bundle segments exhausted.	Submit a bank transfer or purchase a bundle.
403	SENDER_NOT_APPROVED	Requested Sender ID is pending TRCSL regulatory review.	Use default mask until approval completes.
429	RATE_LIMIT_EXCEEDED	Exceeded project TPS throughput quota (100 req/s default).	Queue requests or request TPS increase.

smsgenix