Send Your First SMS in Python with MojaWave

#sms #python #mojawave #api

If you build software in Tanzania or anywhere in East Africa, sending an SMS shouldn't be the hard part of your project. MojaWave gives you one REST endpoint that delivers straight to Vodacom, Tigo, Airtel, and Halotel.

In this post we'll send a single "Hello World" SMS in Python — no SDK required, just the requests library. Total time: about two minutes.

What you'll need

Python 3.8+
A MojaWave API key — grab one free here →
A phone number to text yourself When you sign up you get two kinds of keys:

Prefix	Environment	Use it for
`sk_test_mw_`	Sandbox	Development. No real SMS, no charges.
`mw_`	Live	Real messages to real phones.

Start with the sandbox key so you can run this with zero cost, then swap to your live key when you're ready.

Step 1 — Install requests

pip install requests

Step 2 — Write the script

Create a file called hello_sms.py:

import os
import requests

# Load your key from an environment variable — never hardcode it
API_KEY = os.environ["MOJAWAVE_API_KEY"]

response = requests.post(
    "https://api.mojawave.com/v1/sms/send",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "to": "+255712345678",      # your number in E.164 format
        "from": "MojaWave",          # sender ID (or an approved one on your account)
        "message": "Hello World from MojaWave 🌊",
    },
)

data = response.json()

if response.ok:
    sms = data["data"]
    print(f"Sent ✅  id={sms['id']}  status={sms['status']}")
else:
    print(f"Failed ❌  {response.status_code}: {data}")

Security note: Your API key controls real spending. Keep it in an environment variable or secrets manager — never commit it to Git or ship it in client-side code.

Step 3 — Run it

Set your key and run:

export MOJAWAVE_API_KEY="sk_test_mw_your_key_here"
python hello_sms.py

You'll see something like:

Sent ✅  id=89b82624-f1a2-4f5e-85b5-102e79a06779  status=sent

That's it — your first SMS is on the wire.

What the API sends back

A successful call returns 201 Created with a JSON envelope:

{
  "success": true,
  "data": {
    "id": "89b82624-f1a2-4f5e-85b5-102e79a06779",
    "type": "sms",
    "to": "+255712345678",
    "status": "sent",
    "segments": 1,
    "credits_cost": 1,
    "queued_at": "2026-04-05T12:03:04.485Z",
    "sent_at": "2026-04-05T12:04:04.393Z"
  }
}

A few fields worth knowing:

status moves through queued → sent → delivered (or failed).
segments — messages over 160 characters are split automatically; each segment costs a credit.
credits_cost — how many credits this send used. ## Prefer the SDK?

If you'd rather not handle raw HTTP, the official Python SDK wraps the same call:

import mojawave

client = mojawave.Client(api_key="mw_your_key")
sms = client.sms.send(
    to="+255712345678",
    from_="MojaWave",
    message="Hello World from MojaWave 🌊",
)
print(sms.id, sms.status)

Where to go next

Once your Hello World lands, these are the natural next steps:

Delivery receipts — add a webhook_url to get real-time message.delivered callbacks (verified with HMAC-SHA256).
Bulk send — POST /v1/sms/bulk blasts one message to up to 10,000 recipients with per-recipient personalization.
Check your balance — GET /v1/credits returns your remaining SMS and email credits.
AI integration — the mojawave-mcp package exposes every endpoint as a tool for Claude, ChatGPT, Gemini, Cursor, and any MCP client, so you can send SMS in plain English. Full reference: mojawave.com/docs