VerifiedSMS Python SDK

Installation

pip install verifiedsms-python

# Or from source
pip install git+https://github.com/verifiedsms/verifiedsms-python.git

Quick Start

from verifiedsms import VerifiedSMS

client = VerifiedSMS("YOUR_API_KEY")

# Send SMS
result = client.send("98XXXXXXXX", "Your OTP is 123456")
print(result.message_id)  # UUID

# Check status
status = client.status(result.message_id)
print(status.delivery_status)  # pending, accepted, delivered, failed

# Check balance
balance = client.balance()
print(balance.balance)  # "100.00"

Configuration

from verifiedsms import VerifiedSMS

client = VerifiedSMS(
    api_key="YOUR_API_KEY",
    base_url="https://your-testing-server.com/api/v2",  # optional
    timeout=30,  # optional, default 30
)

Async Support

import asyncio
from verifiedsms import AsyncVerifiedSMS

async def main():
    client = AsyncVerifiedSMS("YOUR_API_KEY")

    # Send SMS
    result = await client.send("98XXXXXXXX", "Hello!")

    # Check status
    status = await client.status(result.message_id)
    print(status.delivery_status)

    await client.close()

asyncio.run(main())

Methods

send(destination, message, type=1, sensitive=False)

result = client.send(
    destination="98XXXXXXXX,97798YYYYYYYY",
    message="Hello!",
    type=1,           # 1=Normal, 2=Unicode
    sensitive=False,  # Don't store message content
)

# Returns: SendResponse
#   .message_id    str
#   .sms_count     int
#   .cost          str
#   .new_balance   str

status(message_id)

status = client.status("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

# Returns: StatusResponse
#   .message_id       str
#   .destination      str
#   .message          str | None
#   .status           str
#   .delivery_status  str
#   .cost             str
#   .created_at       str
#   .accepted_at      str | None
#   .delivered_at     str | None

balance()

balance = client.balance()
print(balance.balance)  # "100.00"

history(page=1, limit=50, date_from=None, date_to=None, status=None, search=None)

history = client.history(page=1, limit=25, status="sent")
for msg in history.history:
    print(f"{msg['destination']} - {msg['status']}")
print(f"Page {history.pagination['page']}/{history.pagination['total_pages']}")

validate(destination)

result = client.validate("98XXXXXXXX,12345,abc")
print(result.valid)    # ["97798XXXXXXXX"]
print(result.invalid)  # ["12345", "abc"]

usage(period="daily")

usage = client.usage("monthly")
print(f"Total SMS: {usage.total_sms}, Cost: Rs. {usage.total_cost}")

validate_key()

result = client.validate_key()
print(f"Key valid, balance: Rs. {result.balance}")

Error Handling

from verifiedsms import VerifiedSMS
from verifiedsms.exceptions import (
    VerifiedSMSError,
    ValidationError,
    AuthenticationError,
    InsufficientBalanceError,
    IPWhitelistError,
    RateLimitError,
    GatewayError,
    ServerError,
)

try:
    result = client.send("98XXXXXXXX", "Hello")
except InsufficientBalanceError as e:
    print(f"Need more credit: {e}")
except AuthenticationError as e:
    print(f"Bad API key: {e}")
except IPWhitelistError as e:
    print(f"IP not allowed: {e}")
except RateLimitError as e:
    print(f"Slow down: {e}")
except GatewayError as e:
    print(f"Gateway failed: {e}")
    print(f"Message ID: {e.message_id}")
except VerifiedSMSError as e:
    print(f"API error: {e} (HTTP {e.status_code})")

Webhook Verification

from flask import Flask, request
from verifiedsms import VerifiedSMS

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def webhook():
    payload = request.get_data(as_text=True)
    signature = request.headers.get("X-VerifiedSMS-Signature", "")

    if not VerifiedSMS.verify_webhook(payload, signature, "YOUR_WEBHOOK_SECRET"):
        return "Unauthorized", 401

    data = request.get_json()
    print(f"Delivery update: {data['message_id']} -> {data['status']}")

    return "OK", 200

Django Integration

# settings.py
VERIFIEDSMS_API_KEY = "YOUR_API_KEY"

# views.py
from verifiedsms import VerifiedSMS
from django.conf import settings

client = VerifiedSMS(settings.VERIFIEDSMS_API_KEY)

def send_otp(request, phone):
    result = client.send(phone, f"Your OTP is {otp_code}", sensitive=True)
    return JsonResponse({"message_id": result.message_id})

Flask Integration

from flask import Flask, request, jsonify
from verifiedsms import VerifiedSMS

app = Flask(__name__)
client = VerifiedSMS("YOUR_API_KEY")

@app.route("/send-sms", methods=["POST"])
def send_sms():
    data = request.get_json()
    result = client.send(data["phone"], data["message"])
    return jsonify(result.to_dict())