Skip to content
SMSRay

API reference · v1

Build with the SMSRay API

A small, predictable REST API for OTP and transactional SMS. JSON in, JSON out, one header to authenticate, signed webhooks for every status change. Samples in cURL, Node.js, Python, PHP and Go.

Quickstart Talk to salesSign inYour keys and live examples

Base URL

https://api.smsray.com/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
  • GET/sms/coverage

Format

JSON over HTTPS. Timestamps are ISO 8601 UTC.

Numbers

E.164 recommended; national format accepted for your workspace's country.

Safe retries

Idempotency-Key on any POST, kept 24 h.

Rate

20 requests per second per client by default.

Take the reference with you

The whole API reference as a PDF, plus machine-readable specs generated from these docs.

Print / PDF Download PDFOpenAPI 3.1Postman

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 delivery finally fails.
  • → 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.com/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 cannot be delivered ends as failed and is refunded.queuedacceptedsentto the networkdeliveredon the phoneundeliveredgave upfailedrefunded
The API reply always says queued. Internal steps (submitting, submitted) and automatic retries can happen in between.

Reference

Everything in the docs

Get started

QuickstartFrom API key to your first verified OTP in about five minutes, then your first SMS with delivery tracking and a webhook.AuthenticationAuthenticate SMSRay API requests with the x-api-key header. Key format, storage, rotation and workspace status explained.Test modePut an SMSRay API key in test mode: messages are accepted and recorded but never sent, and they are free.

API reference

API referenceIndex of the SMSRay v1 REST API: base URL, authentication, every endpoint, webhook events, and OpenAPI and Postman downloads.POSTSend SMSPOST /sms/send — send a transactional, OTP or promotional SMS, as free text or from an approved template, 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.GETMessage statusGET /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.GETCoverageGET /sms/coverage — the countries your SMSRay API key can send to, plus where SMSRay delivers today and soon.WebhooksReceive signed message.status and message.inbound webhooks from SMSRay. Payloads, HMAC-SHA256 verification, retries and secret rotation.

Guides

Numbers & countriesPhone number formats for the SMSRay API: E.164 recommended, national format accepted, and how 422 destination_not_supported works.Errors and codesEvery SMSRay API error code, its HTTP status and what to do about it — including 422 destination_not_supported and template_required.Rate limitsSMSRay API rate limits: per-client requests per second, OTP limits per number, per end-user IP and per resend, and webhook retries.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.

Resources

ChangelogDated changes to the SMSRay API and developer docs: templates library, coverage endpoint, E.164 numbers and more.SupportHow to reach SMSRay developer support, security and sales, and what to include so we can help quickly.

Ready to send your first message?

Talk to sales and we set up your workspace. Then sign in, generate a key and follow the quickstart. OTP works on day one.

Talk to sales See pricing

Already a customer? Log in