KiboNet Python SDK

Simple, secure Python SDK for the KiboNet SMS Gateway.
Supports both synchronous and async usage via httpx.

Features

• Send SMS to one or multiple recipients (comma-separated contacts)
• Delivery reports retrieved by shootId
• Balance check for your SMS credits
• Health check — is_healthy() never raises, perfect for monitoring probes
• Async support — full async/await via AsyncKiboNetClient
• httpx under the hood — connection pooling, automatic retries, TLS verification
• Phone number validation — auto-converts 0XXXXXXXXX → 255XXXXXXXXX
• Typed exceptions — catch exactly what you need
• Context manager support (both sync and async)
• No credentials in code — load from environment variables

Installation

pip install kibonet-python-sdk

Quick Start

Synchronous

from kibonet_sdk import KiboNetClient

with KiboNetClient(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET") as client:
    # Health check
    if client.is_healthy():
        print("API is up!")

    # Send SMS
    resp = client.send_sms(
        sender_id="MyBrand",
        message="Hello from KiboNet!",
        contacts=["255712345678", "255798765432"],
        delivery_report_url="https://myserver.com/delivery-callback",  # optional
    )
    print(f"Shoot ID: {resp['data']['shootId']}")
    print(f"Valid: {resp['data']['validContacts']}")

Asynchronous

import asyncio
from kibonet_sdk import AsyncKiboNetClient

async def main():
    async with AsyncKiboNetClient(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET") as client:
        if await client.is_healthy():
            resp = await client.send_sms(
                sender_id="MyBrand",
                message="Hello async!",
                contacts="255712345678",
            )
            print(resp["data"]["shootId"])

asyncio.run(main())

All Methods

Both KiboNetClient and AsyncKiboNetClient expose the same interface:

send_sms

resp = client.send_sms(
    sender_id="MyBrand",        # Sender name shown to recipient
    message="Your OTP is 1234", # SMS text
    contacts=[                  # Single string, list, or CSV string
        "255712345678",
        "255798765432",
    ],
    delivery_report_url="https://myserver.com/callback",  # optional
    message_type="text",        # currently only "text" is supported
)

# Response
print(resp["data"]["shootId"])          # Use this for delivery reports
print(resp["data"]["validContacts"])    # int
print(resp["data"]["invalidContacts"])  # int
print(resp["data"]["duplicatedContacts"])
print(resp["data"]["messageSize"])      # character count

get_delivery_report

report = client.get_delivery_report("abcd1234-5678-efgh-9012-ijklmnopqrst")

for record in report["data"]:
    print(record["mobile"])      # 255712345678
    print(record["status"])      # Delivered / Failed / Buffered
    print(record["statusCode"])  # 000
    print(record["sentAt"])      # "07-02-2024 07:35:08"

get_balance

result = client.get_balance()
print(result["data"]["totalSms"])  # e.g. 30

is_healthy

if client.is_healthy():
    print("API is reachable and credentials are valid")

Phone Number Formats

The SDK automatically normalises phone numbers:

Error Handling

from kibonet_sdk import KiboNetClient
from kibonet_sdk.exceptions import (
    KiboNetAuthenticationError,
    KiboNetValidationError,
    KiboNetRateLimitError,
    KiboNetInsufficientBalanceError,
    KiboNetConnectionError,
    KiboNetServerError,
    KiboNetAPIError,
    KiboNetError,        # base — catch everything SDK-related
)

client = KiboNetClient(api_key="...", api_secret="...")

try:
    client.send_sms(sender_id="X", message="Hi", contacts="255712345678")
except KiboNetAuthenticationError:
    print("Bad credentials")
except KiboNetValidationError as e:
    print(f"Input error: {e}")
except KiboNetRateLimitError:
    print("Slow down — rate limited")
except KiboNetConnectionError as e:
    print(f"Network error: {e}")
except KiboNetServerError as e:
    print(f"KiboNet server problem: {e}")
except KiboNetAPIError as e:
    print(f"API error (code={e.code}): {e}")

Environment Variables

Keep credentials out of source code:

export KIBONET_API_KEY="your_api_key"
export KIBONET_API_SECRET="your_api_secret"

import os
from kibonet_sdk import KiboNetClient

client = KiboNetClient(
    api_key=os.environ["KIBONET_API_KEY"],
    api_secret=os.environ["KIBONET_API_SECRET"],
)

Constructor Options

KiboNetClient(
    api_key: str,          # Required — from KiboNet portal
    api_secret: str,       # Required — from KiboNet portal
    timeout: float = 30.0, # Per-request timeout in seconds
    max_retries: int = 3,  # Automatic retries on transient failures
    logger=None,           # Optional logging.Logger
)

AsyncKiboNetClient takes the same parameters.

Logging

import logging
logging.basicConfig(level=logging.DEBUG)

client = KiboNetClient(api_key="...", api_secret="...")
# All HTTP calls are logged at DEBUG level

Development

git clone https://github.com/JAXPARROW/kibonet-python-sdk.git
cd kibonet-python-sdk
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=kibonet_sdk --cov-report=term-missing

# Build
python -m build

License

MIT — see LICENSE.

Contributors

• Jackson Linus — Creator and maintainer