Eduji SMS

SMS API

Send SMS to Ghanaian numbers from any language with one HTTPS request. JSON in, JSON out.

Base URL: https://sms.edujilabs.com/api/v1

Getting started

  1. Create an account and buy SMS credit (MoMo or card).
  2. Request a sender ID. Until it's approved you can send with the shared one.
  3. Create an API key on API keys & webhooks. Start with a test key - it never sends or charges.
  4. Call POST /sms/send.

Authentication

Send your key in the Authorization header:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

The X-API-Key header or a ?key= query parameter also work, for tools that can't set headers - but headers are safer, since URLs end up in logs.

  • sk_live_… keys send real messages and are charged.
  • sk_test_… keys run every check (sender ID, numbers, balance) and return a realistic response, but nothing is sent and nothing is charged. Every message comes back delivered.

Send SMS

POST /sms/send

FieldTypeDescription
toarray or stringRequired. Up to 1,000 numbers. Local (0241234567) or international (233241234567, +233…). A string may separate numbers with commas. Duplicates are sent once.
messagestringRequired. Up to 10 SMS long (1,530 plain characters, or 670 with emoji/Unicode).
senderstringOne of your approved sender IDs. Omitted: your default.
schedule_atstringSend later. 2026-12-01T09:30, in UTC (Ghana time).
referencestringYour own id (order number, user id). Returned in responses and webhooks.
curl -X POST https://sms.edujilabs.com/api/v1/sms/send \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"to": ["0241234567", "0551234567"], "message": "Your code is 4821", "sender": "MyShop", "reference": "login-77"}'

Response 201 Created:

{
  "data": {
    "id": "msg_3f9a1c0b7e2d4a6f8c10",
    "status": "sent",
    "test": false,
    "sender": "MyShop",
    "message": "Your code is 4821",
    "segments": 1,
    "recipients": 2,
    "units_charged": 2,
    "client_reference": "login-77",
    "delivery": {"submitted": 2},
    "invalid_recipients": [],
    "balance": 4998,
    "created_at": "2026-11-17T10:21:04"
  }
}

Keep id to check delivery later. If the network refuses a number at submission it is refunded immediately and appears under delivery.rejected.

Estimate cost

POST /sms/estimate

Same to and message as a send. Nothing is sent.

{"data": {"segments": 2, "encoding": "gsm", "characters": 172, "valid_recipients": 3,
          "invalid_recipients": 0, "units": 6, "balance": 4998, "can_afford": true}}

Delivery status

GET /sms/{id}

Returns the batch with a status per recipient:

{"data": {"id": "msg_3f9a…", "status": "sent", "delivery": {"delivered": 1, "undelivered": 1},
  "messages": [
    {"recipient": "233241234567", "status": "delivered", "units": 1, "delivered_at": "2026-11-17T10:21:40"},
    {"recipient": "233551234567", "status": "undelivered", "units": 1, "delivered_at": null}
  ]}}
submittedAccepted by the network, not yet confirmed.
deliveredOn the handset.
undelivered / expiredThe network tried and gave up (phone off for too long, number inactive). Charged - the network was paid to try.
rejectedRefused at submission. Refunded.
failedWe couldn't hand it to the network at all. Refunded.

List messages

GET /sms?page=1&limit=20

Your most recent batches, newest first. limit up to 100.

Balance

GET /balance

{"data": {"sms": 4998, "label": "4,998 SMS", "mode": "live"}}

Sender IDs

The name a message appears to come from. 3-11 letters or numbers, matching your business. Approval by the networks usually takes 1-3 working days; we email you the outcome.

GET /sender-ids

POST /sender-ids

{"name": "MyShop", "purpose": "Order and delivery updates to our customers", "otp_url": null}

Set otp_url (the page where codes are entered) if you'll send one-time passwords - the networks reject OTP traffic from sender IDs registered without one. Status moves queued → pending → approved (or rejected). If a registration fee applies, the status is awaiting_payment until it's paid from the dashboard.

Webhooks

Set a URL on API keys & webhooks and we'll POST each batch's final statuses to it:

POST https://yourapp.com/sms/webhook
X-Signature: 5d41402abc4b2a76b9719d911017c592…
Content-Type: application/json

{"event": "sms.status",
 "data": {"batch_id": "msg_3f9a…", "client_reference": "login-77", "sender": "MyShop", "test": false,
          "messages": [{"recipient": "233241234567", "status": "delivered", "units": 1,
                        "delivered_at": "2026-11-17T10:21:40", "error": null}]}}

Verify X-Signature - the hex HMAC-SHA256 of the raw body using your signing secret - before trusting it:

import hmac, hashlib

def is_genuine(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Answer with any 2xx. Anything else is retried for 24 hours. Each message is reported once.

Errors

{"error": {"code": "insufficient_balance", "message": "needs 120 SMS but only 40 SMS available",
           "needed": 120, "balance": 40}}
HTTPcodeMeaning
400message_required, recipients_required, invalid_recipients, message_too_long, too_many_recipients, invalid_scheduleFix the request.
401unauthorizedMissing, wrong or revoked key.
402insufficient_balanceTop up. Nothing was sent or charged.
403account_suspendedContact support.
422sender_not_found, sender_not_approvedUse one of your approved sender IDs, or omit sender.
429rate_limitedOver 120 requests a minute per key. Wait and retry.
502provider_errorThe network couldn't be reached. Fully refunded - safe to retry.

Limits & billing

  • One SMS is 160 plain characters, or 153 per part once a message is split. Emoji and some accented characters switch the whole message to Unicode: 70 characters, or 67 per part.
  • Each recipient is charged segments SMS. Credit is taken when you send and refunded for anything rejected or failed.
  • 1,000 recipients per request; 120 requests per minute per key.
  • Local delivery only for now (Ghana). Numbers from elsewhere are listed in invalid_recipients and never charged.
  • Credit never expires.