Skip to content
SMSRay

API reference · v1

Build with the SMSRay API

A small, predictable REST API for OTP and transactional SMS to Nepal mobile numbers. JSON in, JSON out, one header to authenticate, signed webhooks for every status change.

Quickstart Get an API key

Base URL

https://api.smsray.in/api/sms/v1

Authentication

x-api-key: ls_live_…48 hex

Endpoints

  • POST/sms/send
  • POST/sms/otp/send
  • POST/sms/otp/verify
  • GET/sms/messages/:id
  • GET/sms/balance

Format

JSON over HTTPS. Timestamps are ISO 8601 UTC.

Recipients

Nepal mobiles only: 96/97/98XXXXXXXX, 977 prefix accepted.

Safe retries

Idempotency-Key on any POST, kept 24 h.

Rate

20 requests per second per client by default.

First request

One call sends an SMS

POST a number and your text. You get a messageId back in the reply, and the message status follows by webhook or lookup.

  • → Cost reserved from your balance at accept, refunded if no route can send it.
  • → Segments and encoding returned so you always know what you paid for.
  • → REST only — any language with an HTTP client works.
Send SMS reference 
curl https://api.smsray.in/api/sms/v1/sms/send \
  -H "x-api-key: $SMSRAY_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{ "to": "9779801234567", "text": "Your order #1042 has shipped." }'

Message lifecycle

Every message has a status you can trust

Each change is pushed to your webhook once, signed, and retried on a backoff schedule if your server misses it.

Message status lifecycle: queued, then sent, then delivered or undelivered. A message that no route can send ends as failed and is refunded.queuedacceptedsentleft a SIMdeliveredon handsetundeliveredgave upfailedrefunded
The API reply always says queued. Internal steps (submitting, submitted) and a requeue to another SIM can happen in between.

Reference

Everything in the docs

Get started

QuickstartCreate a workspace, get an API key and send your first SMS to a Nepal mobile number in about five minutes.AuthenticationAuthenticate SMSRay API requests with the x-api-key header. Key format, storage, rotation and workspace status explained.

Endpoints

POSTSend SMSPOST /sms/send — send a transactional, OTP or promotional SMS to a Nepal mobile number with the SMSRay REST API.POSTOTPPOST /sms/otp/send and /sms/otp/verify — six-digit one-time passwords with cooldowns, attempt caps and per-number limits built in.GETMessagesGET /sms/messages/:id — look up the status, segments, cost and timestamps of an SMS sent with the SMSRay API.GETBalanceGET /sms/balance — read your SMSRay workspace balance, per-type rates, allowed message types and client counters.

Guides

WebhooksReceive signed message.status and message.inbound webhooks from SMSRay. Payloads, HMAC-SHA256 verification, retries and secret rotation.ErrorsEvery SMSRay API error code, its HTTP status and what to do about it. One consistent JSON error shape.Rate limitsSMSRay API rate limits: per-client requests per second and OTP limits per number, per end-user IP and per resend.IdempotencyUse the Idempotency-Key header to retry SMSRay POST requests safely without sending or billing a message twice.Segments & encodingHow SMSRay counts SMS segments: GSM-7 (160/153) vs UCS-2 (70/67), extension characters, Nepali text and emoji. Live counter included.

Ready to send your first message?

Create a workspace with your phone or email, generate a key and follow the quickstart.

Create free account Talk to sales