What SmsNova Is
SmsNova is an SMS gateway built and operated by Ullass. It gives businesses and developers a REST API for sending messages over the Bangladeshi mobile network: transactional notifications, one-time passwords, bulk campaigns, and operational alerts.
Under the hood it speaks to operator aggregators over the Short Message Peer-to-Peer protocol — the same family of interfaces described by the SMPP Forum that carriers and aggregators use to exchange messages — and exposes a much simpler HTTP surface to your application. You never handle SMPP binds, delivery receipts in PDU form, or operator routing tables. You POST JSON.
SmsNova is the native SMS provider for PosNova and is also available to external developers as a standalone service.
Authentication and API Keys
Every request carries a bearer token. Keys are prefixed by environment: sn_live_... for production traffic and sn_test_... for the sandbox, which accepts every payload shape and delivers nothing.
bash# Sandbox: no charge, no delivery curl -s https://sms.ullass.com/api/v1/messages/send \ -H "Authorization: Bearer sn_test_your_api_key" \ -H "Content-Type: application/json" \ -d '{"to":"+8801700000000","message":"test"}'
Two rules we do not bend on. Keep the live key in the server environment and never in client-side code — a key in a browser bundle is a key in your users' hands. And rotate on any suspicion of exposure; creating a new key is instant and the old one can be revoked without downtime. Storing and rotating secrets is the boring half of the OWASP input validation and secure handling guidance that applies to any third-party integration.
Sending a Message
The send endpoint is a single POST to /api/v1/messages/send. Numbers are accepted in international format with the country code and no spaces or symbols; +8801XXXXXXXXX is the safe shape, and 01XXXXXXXXX is normalised if you send the local form.
httpPOST /api/v1/messages/send HTTP/1.1 Host: sms.ullass.com Authorization: Bearer sn_live_your_api_key Content-Type: application/json { "to": "+8801712345678", "message": "Your order #4821 is ready for pickup at 4:30 PM.", "senderId": "YourBrand", "type": "transactional", "reference": "order-4821" }
json{ "success": true, "data": { "messageId": "msg_7f3c1a9e2b", "to": "+8801712345678", "segments": 2, "status": "queued", "acceptedAt": "2025-11-03T09:14:22Z", "estimatedCredits": 2 } }
Field by field:
to— a single destination. Send to many recipients by making many requests; do not loop inside one request.message— plain text or GSM-7 / UCS-2. Length matters: 160 GSM-7 characters is one segment, 153 for concatenated UCS-2, and each extra segment is billed again. The response reportssegmentsso you can log what it actually cost.senderId— your registered alphanumeric ID, or a numeric sender ID if you have one. Alphanumeric IDs are subject to operator and regulator rules in Bangladesh; confirm the rules that apply to your traffic with BTRC and your aggregator before you launch a campaign, since commercial routes commonly require prior approval.type—transactionalorpromotional. Getting this right matters both for route approval and for how carriers treat your traffic.reference— your own identifier, echoed back on the delivery receipt. Use it to reconcile.
Calling the API from curl and from Node
curl is fine for a smoke test and awkward for a queue. Production integrations want retries, timeouts, and an outbox.
javascriptconst SMS_ENDPOINT = 'https://sms.ullass.com/api/v1/messages/send'; export async function sendSms(apiKey, { to, message, senderId, type = 'transactional', reference }) { const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 8000); try { const res = await fetch(SMS_ENDPOINT, { method: 'POST', signal: controller.signal, headers: { Authorization: 'Bearer ' + apiKey, 'Content-Type': 'application/json', }, body: JSON.stringify({ to, message, senderId, type, reference }), }); const payload = await res.json(); if (!res.ok) { throw Object.assign(new Error(payload.error.code), { retryable: res.status >= 500 }); } return payload.data; } finally { clearTimeout(timeout); } }
Note the abort: an SMS API call that hangs holds a request handler open until the platform kills it. Eight seconds is long enough for a queue on a bad connection and short enough to fail over to your retry. The retryable flag is derived from the status code rather than hard-coded per call site, which is what keeps a retry loop from hammering a permanently invalid number. The mechanics of fetch itself — including its failure modes — are on MDN under using the Fetch API.
Delivery Receipts and Webhooks
A 2xx response means the message was accepted for delivery, not delivered. Carrier delivery arrives later as a signed webhook to the URL you register in the dashboard.
json{ "event": "message.delivered", "messageId": "msg_7f3c1a9e2b", "reference": "order-4821", "to": "+8801712345678", "status": "delivered", "segments": 2, "carrierCode": "GP", "timestamp": "2025-11-03T09:14:47Z" }
Status values are queued, sent, delivered, failed, and rejected, plus expired when a handset was unreachable for the validity window. rejected means we refused it — an unregistered sender ID or blocked content. failed means an operator refused it downstream.
Verify every receipt before trusting it. SmsNova signs the raw body with an HMAC and sends a timestamp; compare that timestamp against your own clock to reject replays, then compare signatures in constant time. Web crypto for that comparison is covered by MDN's SubtleCrypto documentation.
javascriptexport async function verifyWebhook(rawBody, signatureHeader, secret) { const key = await crypto.subtle.importKey( 'raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'], ); const mac = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(rawBody)); const expected = Buffer.from(mac).toString('hex'); return timingSafeEqualHex(expected, signatureHeader); }
The handler must be idempotent — carriers retry, so expect the same messageId twice. Key on messageId, return 2xx immediately, and process after the response.
Error Codes and What to Do About Each
Status semantics follow the usual HTTP conventions, documented on MDN at HTTP status codes.
| Status | error.code | Cause | What to do |
|---|---|---|---|
| 400 | invalid_number | Malformed destination | Fix the input. Do not retry. Normalise to +880.... |
| 400 | invalid_sender_id | Sender ID not registered to your account | Register it in the dashboard. Do not retry. |
| 400 | message_too_long | Over the per-part limit | Split or truncate. Do not retry. |
| 401 | invalid_api_key | Missing, wrong, or revoked key | Stop. Check the environment, not the request. |
| 402 | insufficient_credits | Balance below message cost | Top up, then re-queue. Alert on it before it happens. |
| 403 | route_not_enabled | Traffic type not approved for this sender ID | Regulatory action, not a retry. Talk to support. |
| 404 | not_found | Endpoint or message ID unknown | Usually a wrong base URL in sandbox. |
| 409 | duplicate_reference | reference already used | Treat as success if the previous send succeeded. |
| 422 | content_rejected | Blocked by carrier content rules | Rewrite the copy. Do not retry unchanged. |
| 429 | rate_limited | Over your throughput allowance | Back off exponentially with jitter. Retryable. |
| 500 | internal_error | Our fault | Retry with backoff, max three attempts. |
| 502 | upstream_unavailable | Operator route down | Retry, then fall back to another route. |
| 503 | service_unavailable | Maintenance or regional outage | Retry after the Retry-After header. |
The failure pattern to internalise: 4xx means your request is wrong and repeating it wastes credits; 429 and 5xx mean retrying is correct. Most integration bugs we see are a blanket retry loop sending an invalid number forty times.
javascriptasync function withBackoff(fn, { attempts = 3, baseMs = 250 } = {}) { let lastError; for (let i = 0; i < attempts; i++) { try { return await fn(); } catch (err) { if (!err.retryable) throw err; lastError = err; const wait = baseMs * 2 ** i + Math.random() * 100; await new Promise((resolve) => setTimeout(resolve, wait)); } } throw lastError; }
Building an OTP Flow on Top
OTP is where a good gateway meets a correct implementation. Send alone is not enough; the flow has four parts: generate a code that cannot be guessed, bind it to the destination, verify with a constant-time comparison, and burn it after a fixed number of attempts.
javascriptimport { randomInt, timingSafeEqual, createHash } from 'node:crypto'; const OTP_TTL_MS = 5 * 60 * 1000; const MAX_ATTEMPTS = 5; function newOtp() { return randomInt(0, 1000000).toString().padStart(6, '0'); } function otpDigest(otp, phone, salt) { return createHash('sha256').update(salt + phone + otp).digest('hex'); } export async function requestOtp(db, phone, send) { const salt = randomInt(0, 2 ** 30).toString(); const otp = newOtp(); const record = { digest: otpDigest(otp, phone, salt), expiresAt: Date.now() + OTP_TTL_MS, attempts: 0, consumed: false, }; await db.otp.insert(phone, record); await send({ to: phone, message: 'Your verification code is ' + otp + '. It expires in 5 minutes. Do not share it with anyone.', type: 'transactional', reference: 'otp-' + phone, }); } export async function verifyOtp(db, phone, submitted, salt) { const record = await db.otp.load(phone); if (!record || record.consumed || Date.now() > record.expiresAt) { return { ok: false, reason: 'expired_or_unknown' }; } if (record.attempts >= MAX_ATTEMPTS) { await db.otp.invalidate(phone); return { ok: false, reason: 'too_many_attempts' }; } const a = Buffer.from(otpDigest(submitted, phone, salt), 'hex'); const b = Buffer.from(record.digest, 'hex'); const ok = a.length === b.length && timingSafeEqual(a, b); await db.otp.recordAttempt(phone, ok); if (ok) await db.otp.invalidate(phone); return ok ? { ok: true } : { ok: false, reason: 'mismatch' }; }
Four details in there are not optional. The code comes from a CSPRNG, not Math.random. Comparison is constant-time so response timing cannot leak the code. Attempts are counted server-side, so a five-digit space cannot be brute-forced by retrying. And every failed attempt invalidates the record and triggers a rate limit on that number — otherwise your OTP endpoint becomes an SMS-billing attack against yourself.
Return the same generic error for "wrong code" and "no such code". Distinguishing them is free information for an attacker enumerating live numbers.
Bulk Campaigns, Encoding, and Throughput
Bulk sending is the same endpoint called many times, with three constraints. Throughput is capped per API key, and 429 with a Retry-After header is how the cap communicates itself. Cost is per segment, so encoding matters: GSM-7 covers Latin text and costs less per segment than UCS-2, which any Bengali message requires. Cost is also per message with no minimum commitment, so a large campaign should be paced to avoid paying for peak-rate throttling.
Send overnight, cap concurrent requests, and treat the delivery receipt as the only source of truth for "sent". A campaign that reports 92% delivered is a real number; one that reports 100% submitted is a guess.
PosNova Integration
SmsNova is the native provider for PosNova. In Settings → Messaging Providers, enter an SmsNova API key and sender ID, and PosNova sends order status notifications to customers, low-stock alerts to managers, and staff assignment notices — with no third-party SDK in the path, because we operate both ends.
Pricing, Limits, and Where to Start
SmsNova charges per message segment sent. There are no setup fees, no monthly minimum, and no monthly commitment — an account that sends twenty messages a month pays for twenty messages. Current rates and throughput tiers are published on the dashboard at sms.ullass.com.
Create an account, generate a sn_test_ key, and send one sandbox message before you integrate anything. If the integration is part of a larger product build rather than a side task, our web development service covers the surrounding work — and the broader service lineup is where to start if you are scoping the whole system. Questions about a specific integration? Send them over.