eskiz-sms

Modern Python SDK for the Eskiz.uz SMS gateway. Sync and async clients, full type hints, Pydantic v2 models.

Discussion group: https://t.me/+xFkMROBeFp45ZmQ0

v1.0 is a ground-up rewrite. The import path and public API changed. See Migrating from v0.x below. v0.x is preserved on the master branch.

Installation

Requires Python 3.11+.

pip install eskiz-sms

Optional extras:

pip install "eskiz-sms[dotenv]"   # for DotenvTokenStorage

Quickstart

from eskiz import EskizSMS

with EskizSMS(email="you@example.com", password="your-password") as client:
    result = client.sms.send(
        mobile_phone="998901234567",
        message="Hello from Eskiz!",
        from_whom="4546",
    )
    print(result.id, result.status)

Async

import asyncio
from eskiz import AsyncEskizSMS

async def main() -> None:
    async with AsyncEskizSMS(email="you@example.com", password="your-password") as client:
        result = await client.sms.send(
            mobile_phone="998901234567",
            message="Hello!",
        )
        print(result.id, result.status)

asyncio.run(main())

Resources

The client exposes four resource namespaces. Every method has the same signature on the sync and async clients.

client.auth

client.sms

client.templates

client.reports

Sending a batch

from eskiz import EskizSMS
from eskiz.models import BatchMessage

with EskizSMS(email=..., password=...) as client:
    result = client.sms.send_batch(
        dispatch_id=42,
        messages=[
            BatchMessage(user_sms_id="s1", to="998990000001", text="Hi A"),
            BatchMessage(user_sms_id="s2", to="998990000002", text="Hi B"),
        ],
    )

Plain dicts work too — to is normalized (+, spaces, dashes stripped) and ints are coerced:

client.sms.send_batch(
    dispatch_id=42,
    messages=[{"user_sms_id": "s1", "to": 998990000001, "text": "Hi"}],
)

Token storage

Tokens are cached in memory by default. To persist across runs, pass a TokenStorage to the client:

from eskiz import DotenvTokenStorage, EskizSMS

with EskizSMS(
    email="you@example.com",
    password="your-password",
    token_storage=DotenvTokenStorage(env_path=".env"),
) as client:
    client.sms.send(mobile_phone="998901234567", message="Hi")
# Token written to .env; next run reuses it without re-logging in.

DotenvTokenStorage requires pip install "eskiz-sms[dotenv]". You can also implement your own storage (Redis, DB, etc.) by conforming to the TokenStorage Protocol:

class TokenStorage(Protocol):
    def get(self) -> str | None: ...
    def set(self, token: str) -> None: ...
    def clear(self) -> None: ...

Token refresh

The SDK automatically refreshes expired tokens via PATCH /auth/refresh. If refresh fails (revoked token, etc.), it falls back to a fresh POST /auth/login. Concurrent callers share a single in-flight refresh — under load you'll never hammer /auth/login even if 100 requests hit a 401 simultaneously.

Default callback URL

Pass callback_url= to the client and every send uses it unless overridden per-call:

client = EskizSMS(
    email="you@example.com",
    password="your-password",
    callback_url="https://your-app.com/eskiz/callback",
)

Errors

All errors derive from EskizError:

EskizError
├── EskizHTTPError         network / TLS / transport failure
├── AuthError
│   ├── InvalidCredentials login email or password is wrong
│   ├── TokenExpired       (rarely surfaced; auto-handled)
│   └── TokenInvalid       token revoked or refresh failed
├── EskizBadRequest        API rejected the request (validation, etc.)
└── EskizValidationError   local input failed validation (bad URL, ...)

The Eskiz* prefix on the exception names is deliberate — BadRequest, HTTPError, and ValidationError collide with web frameworks, urllib, and pydantic respectively.

from eskiz import EskizBadRequest, EskizSMS, InvalidCredentials

try:
    client.sms.send(mobile_phone="998901234567", message="Hi")
except InvalidCredentials:
    print("check your email/password")
except EskizBadRequest as e:
    print(f"API error: {e.message} (status={e.status_code})")

Migrating from v0.x

Other notable changes:

• Python 3.11+ required (was 3.8+).
• All endpoint methods take keyword-only arguments.
• All return values are typed Pydantic models, not raw dicts.
• Contact endpoints (add_contact, get_contact, etc.) are no longer exposed — they were not in the official Postman collection.
• client.token.set(...) removed; use a custom TokenStorage instead.

Integration tests

The unit suite uses respx to mock the HTTP layer. A separate, opt-in integration suite under tests/integration/ exercises the SDK against the real Eskiz API. It is skipped by default — pass --run-integration to run it.

Set credentials in .env.integration (see .env.integration.example):

cp .env.integration.example .env.integration
# fill in ESKIZ_EMAIL / ESKIZ_PASSWORD

Run only the read-only smokes (no SMS sent, no credits used):

pytest --run-integration tests/integration/test_readonly.py tests/integration/test_async.py

Run the live send test as well — set ESKIZ_TEST_PHONE to a number you control. Eskiz moderates SMS bodies per-account; if the default Eskiz Test body isn't approved on yours, set ESKIZ_TEST_BODY to one that is:

ESKIZ_TEST_PHONE=998901234567 pytest --run-integration tests/integration

License

MIT