Send Your First SMS in Python with MojaWave

DEV Community

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

Get your key

If you skipped ahead — here's where you start:

👉 Get your free MojaWave API key

Building something with SMS in East Africa? Drop a comment with what you're working on.