Skip to content
SMSRay
Print / PDF Download PDFFull reference PDF

Quickstart

From API key to your first verified OTP in about five minutes. OTP uses SMSRay's built-in template, so it works on day one.

1

Sign in and open your workspace

Talk to sales and pick a plan (see pricing); the SMSRay team creates your workspace. Then sign in at app.smsray.com with your phone number or email — we send you a one-time code, no password needed.

Activation

Until your workspace is activated it shows as pending. You can create keys and call the GET endpoints straight away; POST requests return 403 workspace_pending until activation.
2

Create an API key

In the dashboard, open Clients and create an API client — one per app or environment works well. Give it a brand name: it appears at the start of every OTP message. You get two secrets, shown once. The portal's developer page shows your keys and live examples pre-filled for them.

  • ls_live_… — your API key, sent as x-api-key.
  • whsec_… — your webhook signing secret.

Store them in your secret manager or environment, never in client-side code:

shell
export SMSRAY_API_KEY="ls_live_..."

Test mode

Integrating in CI or staging? Put the key in test mode: messages are recorded but never sent, and they're free. For this quickstart leave it off, so the code really reaches your phone.
3

Send your first OTP

Send a code to your own mobile number. Use E.164 (+9779801234567); the national format of your workspace's country works too. OTP uses SMSRay's built-in template, so it works on day one — no template approval needed.

curl https://api.smsray.com/api/sms/v1/sms/otp/send \
  -H "x-api-key: $SMSRAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "to": "+9779801234567", "purpose": "login", "ip": "203.0.113.7" }'

The reply comes back in milliseconds and the SMS arrives a moment later:

200 application/json
{ "success": true, "otpId": "9d5c0b7e-…", "messageId": "4f8a2c61-…", "expiresInSeconds": 300 }
4

Verify the code

Post the 6 digits from the SMS with the same to and purpose. A wrong code is a normal 200 answer with verified: false — always read verified.

curl https://api.smsray.com/api/sms/v1/sms/otp/verify \
  -H "x-api-key: $SMSRAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "to": "+9779801234567", "purpose": "login", "code": "482913" }'
200 application/json
{ "success": true, "verified": true }
5

Send an SMS and track it

Approved templates

Every custom message uses a template approved by SMSRay, which protects deliverability and keeps spam off the networks. Create one in the dashboard (or start from the template library); we aim to review it within one business day.
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." }'

You get a messageId back immediately. The status moves from queued to sent to delivered; look it up any time:

curl https://api.smsray.com/api/sms/v1/sms/messages/<messageId> \
  -H "x-api-key: $SMSRAY_API_KEY"
6

Add a webhook

Polling is fine for testing. In production, set a webhook URL (https://) on your API client and SMSRay POSTs a signed message.status event on every change, plus message.inbound when someone replies. Set up webhooks.

Next steps

OTP referenceCooldowns, attempt caps and per-number limits.Retry safelyNever double-send on a network error.Numbers & countriesE.164, national format and coverage.Handle errorsEvery code and what to do about it.