Skip to main content

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. Its status and message attributes 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)

Source distribution for aio-kavenegar 3.2.2
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)

Table of built distributions (wheels) for aio-kavenegar 3.2.2
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

3.2.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page