Quickstart

Get an API key

Sign in at 1sms.az, create an API key, and keep it somewhere safe. Keys start with 1sk_. Read it from the environment instead of hard-coding it:

import os

from onesms import Client

client = Client(os.environ["ONESMS_API_KEY"], sender_name="YourSender")

Send your first message

from onesms import Client

with Client("1sk_your_api_key", sender_name="YourSender") as client:
    result = client.send_otp("994501234567", "Your code is 123456")
    print(result.message_id, result.cost, result.balance)

The client is a context manager, so the with block closes the underlying HTTP connection when the block ends. You can also call client.close() yourself.

Check the balance

balance = client.balance()
print(balance.balance)

Handle a failure

Every problem raises a typed error, so you react only to the ones you care about:

from onesms import Client, InsufficientBalanceError

with Client("1sk_your_api_key") as client:
    try:
        client.send_notification(["994501234567"], "Order shipped")
    except InsufficientBalanceError as exc:
        print("Top up needed:", exc.required, "current balance:", exc.balance)

Prefer async?

The async client works the same way with await:

import asyncio

from onesms import AsyncClient


async def main() -> None:
    async with AsyncClient("1sk_your_api_key") as client:
        result = await client.send_otp("994501234567", "Your code is 123456")
        print(result.message_id)


asyncio.run(main())

From here the guide covers each part in more detail, starting with Sending messages.