Python Quickstart

Get your first SMS out in under 5 minutes using Python 3.8+ and the official castbrick SDK.

1. Install the SDK

pip install castbrick

2. Get your API key

Go to CastBrick Dashboard → API Keys and create a key. Store it in your environment:

export CASTBRICK_API_KEY=cb_live_xxxxxxxxxxxx

Or add it to a .env file and load with python-dotenv.

3. Send your first SMS

import os
from castbrick import CastBrick

cb = CastBrick(api_key=os.environ["CASTBRICK_API_KEY"])

result = cb.sms.send(
    to=["+244923000000"],
    content="Hello from CastBrick!",
    sender_id="MyApp",
)

print(f"Sent! Message ID: {result.message_id}")

Using with Flask

A typical pattern is sending an OTP when a user signs up:

import os
import random
from flask import Flask, request, jsonify
from castbrick import CastBrick, CastBrickApiError

app = Flask(__name__)
cb = CastBrick(api_key=os.environ["CASTBRICK_API_KEY"])

@app.post("/auth/send-otp")
def send_otp():
    phone = request.json.get("phone")
    code = random.randint(100_000, 999_999)

    try:
        cb.sms.send(
            to=[phone],
            content=f"Your verification code is {code}. Expires in 10 minutes.",
            sender_id="MyApp",
        )
        return jsonify({"ok": True})
    except CastBrickApiError as e:
        return jsonify({"error": str(e)}), e.status_code

Using with Django

# views.py
import os
from django.http import JsonResponse
from django.views.decorators.http import require_POST
from django.views.decorators.csrf import csrf_exempt
import json
from castbrick import CastBrick, CastBrickApiError

cb = CastBrick(api_key=os.environ["CASTBRICK_API_KEY"])

@csrf_exempt
@require_POST
def send_notification(request):
    data = json.loads(request.body)
    try:
        cb.sms.send(
            to=[data["phone"]],
            content=data["message"],
        )
        return JsonResponse({"ok": True})
    except CastBrickApiError as e:
        return JsonResponse({"error": str(e)}, status=e.status_code)

Async usage

The SDK provides an AsyncCastBrick client for asyncio environments:

import asyncio
import os
from castbrick import AsyncCastBrick

async def main():
    cb = AsyncCastBrick(api_key=os.environ["CASTBRICK_API_KEY"])
    result = await cb.sms.send(
        to=["+244923000000"],
        content="Async SMS from CastBrick!",
    )
    print(result.message_id)

asyncio.run(main())

Environment variables

Variable	Description
`CASTBRICK_API_KEY`	Your API key (starts with `cb_live_` for production)

Use cb_test_... keys in development — messages are intercepted in the Sandbox and never reach real phones.

Next steps

Full Python SDK reference — all methods and options
Error handling — handle exceptions properly
Broadcasts — bulk messaging

Python Quickstart

On this page