API reference¶

Everything below is importable from the top-level onesms package.

Clients¶

Client¶

The synchronous client.

Client(
    api_key: str,
    *,
    sender_name: str = "1sms.az",
    base_url: str = "https://1sms.az/api/v1",
    timeout: float = 30.0,
    max_retries: int = 3,
    http_transport: httpx.BaseTransport | None = None,
)

Argument	Meaning
`api_key`	Your 1sms.az API key. Required.
`sender_name`	Default sender for every send. Override it per call.
`base_url`	API root. Change it only for testing or a proxy.
`timeout`	Per-request timeout in seconds.
`max_retries`	Maximum retry attempts. `0` disables retries.
`http_transport`	A custom `httpx` transport, mainly for tests.

Methods:

client.balance() -> Balance
client.send_otp(to, text, *, sender_name=None, idempotency_key=None) -> OtpResult
client.send_notification(recipients, text, *, sender_name=None, idempotency_key=None) -> SendResult
client.send_advertising(recipients, text, *, sender_name=None, idempotency_key=None) -> SendResult
client.message_status(message_id) -> MessageStatus
client.task_status(task_id, *, channel=Channel.NOTIFICATION) -> TaskStatus
client.close() -> None

to is a single phone number, and recipients is a sequence of numbers. Client is a context manager, so with Client(...) as client: closes it for you.

AsyncClient¶

The asynchronous client. It has the same constructor and method names as Client, except the methods are coroutines and http_transport is an httpx.AsyncBaseTransport. Use it with async with, and await client.close() if you build it without a context manager.

async with AsyncClient(api_key) as client:
    balance = await client.balance()

Enums¶

DeliveryStatus¶

An IntEnum of every delivery state.

Member	Value	`is_final`
`PENDING`	0	False
`SENT_TO_OPERATOR`	1	False
`DELIVERED`	2	True
`EXPIRED`	3	True
`UNDELIVERED`	5	True
`REJECTED`	8	True
`OPERATOR_UNREACHABLE`	9	True

Each member has an is_final property. Two helpers work on raw integers:

delivery_status(code: int) -> DeliveryStatus | None
is_final_status(code: int) -> bool

delivery_status returns None for a code it does not recognise.

Channel¶

A string enum for the task-status channel.

Member	Value
`NOTIFICATION`	`"notification"`
`ADVERTISING`	`"advertising"`

Result models¶

All result models are frozen dataclasses.

Balance¶

Field	Type
`balance`	`int`
`apis`	`ApiPermissions`

ApiPermissions¶

Field	Type
`otp`	`bool`
`bulk`	`bool`
`advertising`	`bool`

OtpResult¶

Field	Type
`success`	`bool`
`message_id`	`str`
`cost`	`int`
`balance`	`int`

SendResult¶

Returned by send_notification and send_advertising.

Field	Type	Notes
`success`	`bool`
`requested_count`	`int`
`sent_count`	`int`
`failed_count`	`int`
`cost`	`int`
`balance`	`int`
`rejected`	`tuple[RejectedRecipient, ...]`	Numbers the API would not send to
`message_ids`	`tuple[str, ...]`	Set for single sends
`task_id`	`str \| None`	Set for bulk sends
`refunded`	`int \| None`	Amount refunded for failed bulk recipients

RejectedRecipient¶

Field	Type
`number`	`str`
`reason`	`str`

MessageStatus¶

Returned by message_status.

Member	Type	Notes
`message_id`	`str`
`status_code`	`int`
`status_text`	`str`
`date`	`datetime \| None`
`status`	`DeliveryStatus \| None`	Property
`is_final`	`bool`	Property

RecipientStatus¶

One entry in TaskStatus.messages.

Member	Type	Notes
`message_id`	`str`
`phone`	`str`
`status_code`	`int`
`status_text`	`str`
`date`	`datetime \| None`
`status`	`DeliveryStatus \| None`	Property
`is_final`	`bool`	Property

TaskStatus¶

Returned by task_status.

Field	Type
`task_id`	`str`
`channel`	`str`
`requested_count`	`int`
`sent_count`	`int`
`failed_count`	`int`
`messages`	`tuple[RecipientStatus, ...]`

Webhooks¶

verify_signature(
    secret: str,
    timestamp: str,
    body: bytes,
    signature: str,
    *,
    tolerance_seconds: int = 300,
) -> bool

compute_signature(secret: str, timestamp: str, body: bytes) -> str

verify_signature returns True only when the signature matches and the timestamp is within tolerance_seconds of now. compute_signature is the building block it uses, exposed for testing and for signing your own requests.

WebhookEvent¶

A frozen dataclass built from a webhook payload with WebhookEvent.from_payload(data).

Member	Type	Notes
`event`	`str`
`message_id`	`str`
`status_code`	`int`
`status_text`	`str`
`phone`	`str`
`timestamp`	`datetime \| None`
`status`	`DeliveryStatus \| None`	Property
`is_final`	`bool`	Property

Exceptions¶

See Errors for handling patterns.

Exception	Raised for
`OneSmsError`	Base class for everything in the library
`OneSmsValidationError`	Local checks before a request is sent
`OneSmsConnectionError`	Network failures that could not be retried
`OneSmsAPIError`	Base for any API error; has `status_code`, `error_code`, `message`, `payload`
`BadRequestError`	`400`
`AuthenticationError`	`401`
`InsufficientBalanceError`	`402`; adds `required`, `balance`
`PermissionDeniedError`	`403`
`NotFoundError`	`404`
`ConflictError`	`409`
`RateLimitError`	`429`; adds `retry_after`
`ServerError`	`5xx`; adds `msm_errno`, `msm_err_text`, `hint`