📱 SMSGate Python Client

A modern Python client for the SMSGate 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 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
  • 📖 About
  • 📚 Table of Contents
  • ⭐ Features
  • 📦 Installation
  • 🔑 Authentication
    • Basic Authentication
    • JWT Authentication
  • 🚀 Quickstart
  • 💻 Usage
  • 📖 API Reference
  • 🤝 Contributing
  • 📄 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

pip install android-sms-gateway

Requires Python 3.9+. Optional extras:

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

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

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

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 for the complete method list with signatures and android_sms_gateway/domain.py for the domain models.

📖 API Reference

• Official API Reference - endpoints, payloads, and error codes
• Authentication Guide - scopes and token management
• Client libraries overview
• Client source - 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.