axedz 2.0.0

Production-grade Python SDK for the AxeDz CPaaS API (SMS, Email, Wallet)

AxeDz Python SDK

Production-grade Python SDK for the AxeDz CPaaS platform. Send SMS and email, manage wallet balances, and inspect usage transactions with a clean, typed API inspired by Stripe and Twilio SDKs.

Features

• SMS and email sending
• Wallet balance and transaction history
• API key authentication via x-api-key header
• Automatic retries with exponential backoff (network and 5xx errors)
• Rich, typed exception hierarchy
• Standardized response envelope (success, data, meta)
• Optional async client via httpx
• Environment variable configuration

Installation

pip install axedz

For async support:

pip install axedz[async]

Authentication

All requests are authenticated with your AxeDz API key via the x-api-key header:

x-api-key: <API_KEY>

You can pass the key directly or via environment variable:

export AXEDZ_API_KEY="your_api_key"
export AXEDZ_BASE_URL="https://your-api.example.com/api"  # optional

Quick Start

from axedz import AxeDz

client = AxeDz("API_KEY")

# Send SMS
client.sms.send("+213xxxxxxxx", "Hello")

# Send email
client.email.send(
    "[e-mail]",
    "Welcome",
    text="Hello from AxeDz",
)

# Wallet balance
print(client.wallet.balance())

# Usage transactions
print(client.wallet.transactions(limit=20, offset=0))

Usage

Initialize the client

from axedz import AxeDz

client = AxeDz(
    api_key="your_api_key",
    base_url="http://localhost:3000/api",  # default
    timeout=10,                             # seconds
    max_retries=2,                          # retry network/5xx failures
    debug=False,                            # enable request logging
)

Or use environment variables:

client = AxeDz()  # reads AXEDZ_API_KEY and AXEDZ_BASE_URL

Use as a context manager to ensure the HTTP session is closed:

with AxeDz("API_KEY") as client:
    client.sms.send("[phone]", "Hello")

SMS

response = client.sms.send(
    to="[phone]",
    message="Your verification code is 123456",
)

print(response["success"])  # True
print(response["data"])     # {"id": "...", "status": "queued"}
print(response["meta"])     # {"status_code": 202, ...}

Optional provider override:

client.sms.send("[phone]", "Hello", provider="twilio")

Email

Send plain text:

client.email.send(
    "[e-mail]",
    "Welcome to AxeDz",
    text="Thanks for signing up!",
)

Send HTML:

client.email.send(
    "[e-mail]",
    "Invoice",
    html="<h1>Your invoice</h1><p>Thank you.</p>",
)

Send to multiple recipients and include callback metadata:

client.email.send(
    to=["[e-mail]", "[e-mail]"],
    subject="Welcome",
    body="<h1>Hello World</h1>",
    body_type="html",
    sender_name="AxeDz",
    callback_url="https://webhook.site/129b1309-5626-4a61-ac52-60f73fe4aa6b",
    callback_data={"user_id": 123},
)

Wallet

Fetch balance:

balance = client.wallet.balance()
print(balance["data"]["balance"])
print(balance["data"]["currency"])

List usage transactions:

transactions = client.wallet.transactions(limit=20, offset=0)

for event in transactions["data"]["records"]:
    print(event)

pagination = transactions["data"]["pagination"]
print(pagination["total"], pagination["hasMore"])

Response format

Every SDK method returns a normalized envelope:

{
    "success": True,
    "data": { ... },   # API payload
    "meta": { ... },   # status code, headers, pagination, etc.
}

Raw HTTP responses are never exposed.

Error handling

The SDK raises typed exceptions with full context:

Exception	When
ValidationError	Invalid input or 400/422 API responses
AuthenticationError	Missing/invalid API key (401/403)
RateLimitError	Rate limit exceeded (429)
ServerError	Server-side failures (5xx)
NetworkError	Timeouts and connectivity issues
AxeDzError	Base class for all SDK errors

Example:

from axedz import AxeDz, AuthenticationError, ValidationError

client = AxeDz("API_KEY")

try:
    client.sms.send("", "Hello")
except ValidationError as error:
    print(error.message)
    print(error.status_code)
    print(error.response_body)
    print(error.request)
except AuthenticationError as error:
    print("Check your API key:", error.message)

Retries

The SDK automatically retries failed requests when:

• A network error occurs (timeout, connection failure)
• The API returns a 5xx server error

It does not retry validation, authentication, or rate-limit errors. Retries use exponential backoff (default: 2 attempts).

Async client (optional)

import asyncio
from axedz.async_client import AsyncAxeDz

async def main():
    async with AsyncAxeDz("API_KEY") as client:
        result = await client.sms.send("[phone]", "Hello")
        print(result)

asyncio.run(main())

Install async dependencies first:

pip install axedz[async]

Development

git clone https://github.com/axedz/axedz-python.git
cd axedz-python
pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.