🐍

pip install

One command gets you the SDK with full type hints and zero external dependencies beyond requests.

🔄

Async Ready

Native asyncio support via aiohttp for high-throughput applications.

🧩

Framework Helpers

Pre-built integrations for Django, Flask, and FastAPI — plug in and go.

Quick Start

Install & Send Your First SMS

pip install onlinesmsservice

import os
from onlinesmsservice import SMSClient

client = SMSClient(api_key=os.environ["SMS_API_KEY"])

# Send a single SMS
result = client.send(
    to="919876543210",
    message="Your OTP is 482910. Valid for 5 minutes.",
    sender="YOURID",
    msg_type="transactional"
)

print(f"Message ID: {result.message_id}")
print(f"Status:     {result.status}")       # "queued"
print(f"Credits:    {result.credits_used}")

Bulk Sending

Send Bulk SMS

from onlinesmsservice import SMSClient

client = SMSClient(api_key="YOUR_API_KEY")

phones = ["919876543210", "919876543211", "919876543212"]

result = client.send_bulk(
    to=phones,
    message="Flash sale! 40% off everything today only.",
    sender="YOURID",
    msg_type="promotional"
)

print(f"Sent: {result.success_count}/{result.total_count}")

for r in result.results:
    if r.status == "failed":
        print(f"  Failed: {r.phone} — {r.error}")

Django

Django Integration

Add SMS to your Django app with our ready-made backend and management commands.

# settings.py
INSTALLED_APPS = [
    ...
    "onlinesmsservice.django",
]

SMS_API_KEY = os.environ["SMS_API_KEY"]
SMS_DEFAULT_SENDER = "YOURID"
SMS_DEFAULT_TYPE = "transactional"

from django.http import JsonResponse
from onlinesmsservice.django import send_sms

def send_otp(request):
    phone = request.POST["phone"]
    otp = generate_otp()    # your OTP generator

    result = send_sms(
        to=phone,
        message=f"Your verification code is {otp}",
    )

    return JsonResponse({
        "success": True,
        "message_id": result.message_id,
    })

Flask

Flask Integration

from flask import Flask, request, jsonify
from onlinesmsservice import SMSClient

app = Flask(__name__)
sms = SMSClient(api_key=app.config["SMS_API_KEY"])

@app.route("/api/send-otp", methods=["POST"])
def send_otp():
    phone = request.json["phone"]
    otp = generate_otp()

    result = sms.send(
        to=phone,
        message=f"Your OTP is {otp}. Valid 5 min.",
        msg_type="transactional"
    )

    return jsonify(success=True, message_id=result.message_id)

Async

Async / FastAPI Support

For high-throughput applications, use the async client powered by aiohttp.

import asyncio
from onlinesmsservice import AsyncSMSClient

async def main():
    client = AsyncSMSClient(api_key="YOUR_API_KEY")

    # Send multiple SMS concurrently
    tasks = [
        client.send(to=phone, message="Your OTP is 123456", msg_type="transactional")
        for phone in ["919876543210", "919876543211"]
    ]

    results = await asyncio.gather(*tasks)
    for r in results:
        print(f"{r.to} → {r.status}")

    await client.close()

asyncio.run(main())

Reference

Error Handling & Response Codes

from onlinesmsservice.exceptions import (
    AuthError,
    BalanceError,
    RateLimitError,
    ValidationError,
)

try:
    result = client.send(to="919876543210", message="Hello!")
except AuthError:
    print("Invalid API key — check SMS_API_KEY")
except BalanceError:
    print("Insufficient credits — top up your account")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Bad request: {e.errors}")

HTTP Code	Exception	Action
`200`	—	Message queued successfully
`400`	ValidationError	Fix parameters
`401`	AuthError	Check API key
`402`	BalanceError	Top up account
`429`	RateLimitError	Auto-retried by SDK
`500`	ServerError	Auto-retried (3 attempts)