Metadata-Version: 2.4
Name: android-sms-gateway
Version: 4.2.1
Summary: A client library for sending and managing SMS messages via the SMS Gateway for Android API
Author-email: Aleksandr Soloshenko <admin@sms-gate.app>
Maintainer-email: Aleksandr Soloshenko <support@sms-gate.app>
License: Apache-2.0
Project-URL: Homepage, https://sms-gate.app
Project-URL: Repository, https://github.com/android-sms-gateway/client-py
Keywords: android,sms,gateway
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Provides-Extra: requests
Requires-Dist: requests; extra == "requests"
Provides-Extra: httpx
Requires-Dist: httpx; extra == "httpx"
Provides-Extra: aiohttp
Requires-Dist: aiohttp; extra == "aiohttp"
Provides-Extra: encryption
Requires-Dist: pycryptodome; extra == "encryption"
Dynamic: license-file

# 📱 SMSGate Python Client

[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stars][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![License][license-shield]][license-url]
[![PyPI Version][version-shield]][version-url]

A modern Python client for the [SMSGate](https://sms-gate.app) API: send SMS messages through your Android devices with synchronous and asynchronous interfaces, Basic or JWT authentication, and optional end-to-end encryption. See the [client libraries overview](https://docs.sms-gate.app/integration/client-libraries/) for the full ecosystem.

## 📖 About

`android-sms-gateway` is a typed Python library for the SMSGate 3rd-party API, with fully type-hinted domain models. It ships a synchronous `APIClient` and an asynchronous `AsyncAPIClient`, auto-detects the installed HTTP backend (`requests`, `aiohttp`, or `httpx`), and supports optional end-to-end message encryption via `Encryptor` (AES-256-CBC). Covers messages, inbox (refresh, attachments), devices, webhooks, settings, logs, health probes, and the JWT token lifecycle.

## 📚 Table of Contents

- [📱 SMSGate Python Client](#-smsgate-python-client)
  - [📖 About](#-about)
  - [📚 Table of Contents](#-table-of-contents)
  - [⭐ Features](#-features)
  - [📦 Installation](#-installation)
  - [🔑 Authentication](#-authentication)
    - [Basic Authentication](#basic-authentication)
    - [JWT Authentication](#jwt-authentication)
  - [🚀 Quickstart](#-quickstart)
  - [💻 Usage](#-usage)
  - [📖 API Reference](#-api-reference)
  - [🤝 Contributing](#-contributing)
  - [📄 License](#-license)

## ⭐ Features

- Synchronous `APIClient` and asynchronous `AsyncAPIClient` (context managers)
- Basic and JWT authentication; token generate, refresh, and revoke
- HTTP backends: `requests` (sync), `aiohttp` (async), `httpx` (both), auto-detected
- Optional end-to-end encryption via `Encryptor` (AES-256-CBC)
- Webhooks, devices, settings, logs, and health probes (live, ready, startup)
- Inbox refresh with webhook delivery and MMS attachment download
- Full type hints and typed exceptions (`APIError` subclasses)

## 📦 Installation

```bash
pip install android-sms-gateway
```

Requires Python 3.9+. Optional extras:
```bash
pip install android-sms-gateway[requests]    # sync requests backend
pip install android-sms-gateway[aiohttp]     # async aiohttp backend
pip install android-sms-gateway[httpx]       # httpx backend (sync + async)
pip install android-sms-gateway[encryption]  # end-to-end encryption (pycryptodome)
```

## 🔑 Authentication

Two methods are supported: Basic authentication with account credentials, and JWT bearer tokens with scoped permissions. Pass `login=None` with a token to switch to JWT.

### Basic Authentication

```python
import os

from android_sms_gateway import client, domain

login = os.getenv("SMSGATE_LOGIN")
password = os.getenv("SMSGATE_PASSWORD")
message = domain.Message(
    phone_numbers=["+12025550100"],
    text_message=domain.TextMessage(text="Hello from Python"),
)

with client.APIClient(login, password) as c:
    state = c.send(message)
```

### JWT Authentication

```python
from android_sms_gateway import client, domain

with client.APIClient(login, password) as c:
    token = c.generate_token(
        domain.TokenRequest(scopes=["messages:send", "messages:read"], ttl=3600)
    )

jwt_client = client.APIClient(None, token.access_token)
```

## 🚀 Quickstart

```python
import os

from android_sms_gateway import client, domain

message = domain.Message(
    phone_numbers=["+12025550100"],
    text_message=domain.TextMessage(text="Hello from Python"),
    with_delivery_report=True,
)

with client.APIClient(os.getenv("SMSGATE_LOGIN"), os.getenv("SMSGATE_PASSWORD")) as c:
    state = c.send(message)
    print(f"Message ID: {state.id}")
```

## 💻 Usage

Beyond sending, the client covers message listing and cancellation, inbox listing and refresh, device management, health checks, logs, settings (get, update, patch), webhooks, and the token lifecycle. See [android_sms_gateway/client.py](https://github.com/android-sms-gateway/client-py/blob/master/android_sms_gateway/client.py) for the complete method list with signatures and [android_sms_gateway/domain.py](https://github.com/android-sms-gateway/client-py/blob/master/android_sms_gateway/domain.py) for the domain models.

## 📖 API Reference

- [Official API Reference](https://docs.sms-gate.app/integration/api/) - endpoints, payloads, and error codes
- [Authentication Guide](https://docs.sms-gate.app/integration/authentication/) - scopes and token management
- [Client libraries overview](https://docs.sms-gate.app/integration/client-libraries/)
- [Client source](https://github.com/android-sms-gateway/client-py/blob/master/android_sms_gateway/client.py) - full method reference and examples

## 🤝 Contributing

Contributions are welcome. Open an issue to discuss major changes before submitting a pull request; PRs target the `master` branch.

## 📄 License

Distributed under the Apache License 2.0. See [LICENSE](https://github.com/android-sms-gateway/client-py/blob/master/LICENSE).

<!-- Badge references: Shields.io style=for-the-badge is mandatory -->
[contributors-shield]: https://img.shields.io/github/contributors/android-sms-gateway/client-py?style=for-the-badge
[contributors-url]: https://github.com/android-sms-gateway/client-py/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/android-sms-gateway/client-py?style=for-the-badge
[forks-url]: https://github.com/android-sms-gateway/client-py/network/members
[stars-shield]: https://img.shields.io/github/stars/android-sms-gateway/client-py?style=for-the-badge
[stars-url]: https://github.com/android-sms-gateway/client-py/stargazers
[issues-shield]: https://img.shields.io/github/issues/android-sms-gateway/client-py?style=for-the-badge
[issues-url]: https://github.com/android-sms-gateway/client-py/issues
[license-shield]: https://img.shields.io/github/license/android-sms-gateway/client-py?style=for-the-badge
[license-url]: https://github.com/android-sms-gateway/client-py/blob/master/LICENSE
[version-shield]: https://img.shields.io/pypi/v/android-sms-gateway?style=for-the-badge
[version-url]: https://pypi.org/project/android-sms-gateway/
