SMS API

Queue messages, list history, and poll delivery status.

  1. Docs
  2. SMS API

Send

POST /v1/sms/send accepts a message, charges the organisation wallet, and returns 202 when the message is queued for delivery.

POST /v1/sms/send
curl -X POST https://api.netnaunse.com/v1/sms/send \
  -H "Authorization: Bearer YOUR_TOKEN_OR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "255712345678",
    "message": "Your OTP is 847201. Valid for 5 minutes.",
    "senderId": "MyBrand",
    "language": "English"
  }'

Request body

FieldRequiredDescription
toYesDestination MSISDN (9–15 digits). Prefer international format without spaces, e.g. 2557XXXXXXXX.
messageYesMessage body, up to 1,600 characters. Segment billing applies.
senderIdConditionalUp to 11 alphanumeric characters. Required unless your organisation has a platform default Sender ID.
languageNoEnglish (default, 160 chars/segment) or Unicode (70 chars/segment).
scheduledAtNoISO-8601 datetime to delay send.
messageTypeNoOptional pricing hint: otp, transactional, or marketing.

Success response · 202

Response
{
  "data": {
    "id": "cmexample123",
    "status": "queued",
    "to": "255712345678",
    "queuedAt": "2026-09-03T10:43:11.000Z",
    "pricing": {
      "segments": 1,
      "unitPrice": 25,
      "total": 25,
      "currency": "TZS"
    }
  }
}

List messages

GET /v1/sms
curl "https://api.netnaunse.com/v1/sms?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN_OR_API_KEY"

Returns { data: Message[], meta: { page, limit, total } }, scoped to your organisation.

Get message

GET /v1/sms/{id}
curl https://api.netnaunse.com/v1/sms/cmexample123 \
  -H "Authorization: Bearer YOUR_TOKEN_OR_API_KEY"

Message object

Customer message shape
{
  "id": "cmexample123",
  "to": "255712345678",
  "body": "Your OTP is 847201. Valid for 5 minutes.",
  "senderId": "MyBrand",
  "status": "sent",
  "errorCode": null,
  "errorMessage": null,
  "sentAt": "2026-09-03T10:43:16.000Z",
  "createdAt": "2026-09-03T10:43:11.000Z",
  "updatedAt": "2026-09-03T10:43:16.000Z"
}

Statuses

  • queued / processing — accepted, not yet final
  • sent — handed off successfully
  • failed — not delivered; see errorCode / errorMessage

Prefer webhooks for near-real-time updates: Webhooks. For failure codes, see Errors.