How to Send SMS from Node.js in Eswatini

If you're building an app that needs to reach real phone numbers in Eswatini (order confirmations, payment reminders, appointment alerts), this is the complete, working path from an empty Node.js project to a delivered SMS.

No SDK to install. The Lunyazi API is a plain REST endpoint that returns JSON, so fetch() (built into Node 18+) is all you need.

1. Get an API key

Sign up at lunyazi.com/dashboard. It's free, no credit card required. Your API key is on the dashboard home screen once you're in. Keep it server-side; never ship it in client-side JavaScript.

2. Send your first message

Store the key as an environment variable, then make the request:

// send-sms.js
const response = await fetch("https://api.lunyazi.com/sms/send", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.LUNYAZI_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    to: "+26876001234",
    message: "Your order is ready for collection."
  })
});

const result = await response.json();
console.log(result);

Run it with node --env-file=.env send-sms.js (Node 20.6+) or load your .env however your project already does.

What comes back

On success, the API responds with the real cost and routing info for that specific message, not just a generic "ok":

{
  "success": true,
  "message": "SMS sent",
  "cost": 1,
  "segments": 1,
  "destination": "Eswatini",
  "pool": "sz"
}

cost is how many credits that message used. Long messages that span multiple SMS segments cost more, which is why segments is returned alongside it. pool tells you which of your two credit balances was charged: sz for Eswatini numbers, international for everything else.

3. Handle errors properly

A production integration needs to handle the request failing, not just assume it always succeeds. The two most common real failure cases:

if (!response.ok) {
  if (response.status === 402) {
    // out of credits, result.error explains which pool (sz or international)
    console.error("Top up needed:", result.error);
  } else {
    // missing/invalid fields, bad phone number, etc.
    console.error("Send failed:", result.error);
  }
  return;
}

A 402 specifically means insufficient credits. Worth catching separately from a generic 400, since the fix (top up) is different from a code bug (fix the request).

4. Wrap it in a reusable function

For anything beyond a one-off script, wrap the call so the rest of your app doesn't need to know about HTTP status codes:

// lib/sms.js
export async function sendSms(to, message) {
  const res = await fetch("https://api.lunyazi.com/sms/send", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.LUNYAZI_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ to, message })
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error || `SMS send failed (${res.status})`);
  return data;
}

// elsewhere in your app
await sendSms(customer.phone, `Hi ${customer.name}, your order #${order.id} is confirmed.`);

Production considerations

Phone number format: both +26876001234 and 26876001234 work; the API strips formatting characters internally. Store numbers however's natural for your app.
Rate limits: the API applies a per-account rate limit. If you're sending to a large list at once, use the bulk-send endpoint rather than looping individual requests.
Test before going live: Lunyazi provides fixed test numbers that don't charge real credits or hit a real carrier, so you can wire up your integration and verify the request/response shape before spending anything.
Never trust client input for message content that affects billing: if the message text or recipient comes from user input in your app, validate it server-side before calling the API, the same way you'd validate any external write.

Destination	Cost per segment
Eswatini & South Africa	1 credit
UK & Namibia	3 credits

Frequently Asked Questions

Do I need an SDK to send SMS from Node.js?

No. The Lunyazi API is a plain REST endpoint: fetch(), which ships with Node 18 and later, is all you need. No package to install, no version to keep updated.

What Node.js version do I need?

Node 18+ for built-in fetch(). On older versions, any HTTP client (axios, node-fetch, undici) works identically, since the request is just a standard JSON POST.

How do I send SMS to multiple recipients at once?

Use the bulk-send endpoint rather than calling /sms/send in a loop. It's built for exactly this and won't trip the per-account rate limit the way rapid individual calls would.

What happens if I run out of credits mid-send?

The request returns a 402 status with an error field naming which credit pool (Eswatini or international) is empty. No partial charge happens: a failed send never deducts credits.

Ready to send your first message?

Free to start, no credit card required. Get an API key and send a real SMS in the next five minutes.

Get your API key →