aio-kavenegar
An asynchronous Python client for the Kavenegar REST API. It uses httpx and is designed for applications built with asyncio.
This is an independent, community-maintained client. It is not an official Kavenegar package and is not API-compatible with Kavenegar's official Python client.
Requirements
- Python 3.10 or later
- A Kavenegar account and API key
Create an account through the Kavenegar panel, then obtain an API key from your account settings.
Identity verification: You can use an API key for account-level operations, such as retrieving account information, before verification. Kavenegar requires identity verification before you can send SMS messages, verification messages, or voice calls.
Installation
pip install aio-kavenegar
Quick start
Send an SMS from an async function:
import asyncio
from aio_kavenegar import AIOKavenegarAPI, APIException, HTTPException
async def main():
api = AIOKavenegarAPI("YOUR_API_KEY")
try:
result = await api.sms_send(
{
"receptor": "09120000000",
"message": "Hello from aio-kavenegar!",
# "sender": "1000xxxx", # optional
}
)
print(result)
except APIException as exc:
# Kavenegar returned an application-level error.
print(f"Kavenegar error {exc.status}: {exc.message}")
except HTTPException as exc:
# A transport, HTTP-status, or invalid-response error occurred.
print(f"Request failed: {exc}")
asyncio.run(main())
Every API method is asynchronous and must be awaited. On a successful request, a method returns the API response's entries value.
Verification / OTP
Use a Kavenegar verification template to send a one-time password:
result = await api.verify_lookup(
{
"receptor": "09120000000",
"template": "verify-template",
"token": "123456",
"type": "sms", # or "call"
}
)
Refer to Kavenegar's documentation for template setup and the complete list of supported parameters.
Bulk SMS
sms_sendarray accepts Python lists, tuples, and dictionaries; the client serializes them as JSON form values where required by Kavenegar.
result = await api.sms_sendarray(
{
"sender": ["1000xxxx", "1000xxxx"],
"receptor": ["09120000000", "09120000001"],
"message": ["First message", "Second message"],
}
)
Configuration
api = AIOKavenegarAPI(
"YOUR_API_KEY",
timeout=20, # seconds; defaults to 10
proxies={
"http": "http://127.0.0.1:3128",
"https": "http://127.0.0.1:3129",
},
headers={"X-Request-ID": "request-123"},
)
Custom headers are merged with the client's default form-encoding headers. Proxy URLs may be supplied for either http, https, or both.
Available methods
All methods accept an optional params dictionary unless otherwise noted. Parameter names and requirements are defined by the Kavenegar REST API documentation.
| Area | Methods |
|---|---|
| SMS | sms_send, sms_sendarray, sms_status, sms_statuslocalmessageid, sms_select, sms_selectoutbox, sms_latestoutbox, sms_countoutbox, sms_cancel, sms_receive, sms_countinbox, sms_countpostalcode, sms_sendbypostalcode |
| Verification | verify_lookup |
| Voice | call_maketts, call_status |
| Account | account_info() and account_config |
For example, retrieve account information without parameters:
account = await api.account_info()
Error handling
The package exposes two exception types:
APIException: Kavenegar returned a non-success application status. Itsstatusandmessageattributes contain the API error details.HTTPException: a network failure, non-success HTTP response, or invalid JSON response prevented the request from completing.
The client masks the API key in HTTP error messages and in its string representation.
Development
Install the development dependencies, then run the tests and lint checks:
uv sync --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check --line-length 88 tests
Contributing
Bug reports, documentation improvements, and pull requests are welcome. Please include tests for behavior changes where practical.
License
This project is released under the MIT License.
Metadata
Release files for aio-kavenegar 3.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aio_kavenegar-3.2.2.tar.gz | 6.4 kB | Without provenance | Details for aio_kavenegar-3.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aio_kavenegar-3.2.2-py3-none-any.whl | Python 3 | none | any | Details for aio_kavenegar-3.2.2-py3-none-any.whl |
Total release size: 13.7 kB
Release files / aio_kavenegar-3.2.2.tar.gz
| Download URL | aio_kavenegar-3.2.2.tar.gz |
|---|---|
| Size | 6.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d3eea6487cf9024c72ccee4b87fedab6b1865a54a8359e6119b165d98f1c2f1e
|
|
BLAKE2b-256 checksum How to use checksums |
dc47191773a261ebb97b35531e2aae8e16f7c7b6dfd0c8655204c36a4a6b72c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.0 {"installer":{"name":"uv","version":"0.12.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / aio_kavenegar-3.2.2-py3-none-any.whl
| Download URL | aio_kavenegar-3.2.2-py3-none-any.whl |
|---|---|
| Size | 7.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bdad2a19becc5c8d3c8b1ba415f165ee73dd43cd1c1dd454e35ae31460b34441
|
|
BLAKE2b-256 checksum How to use checksums |
8255af2b498ef9ad877912c7ab4fccc19882cacc8e8b6720edecf8355fecbb22
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.0 {"installer":{"name":"uv","version":"0.12.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for aio-kavenegar 3.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.