📱 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 (SMS, data, and MMS), 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
  • 🚀 Getting Started
    • Prerequisites
    • Quick Setup
  • 🔑 Authentication
    • Basic Authentication
    • JWT Authentication
  • 💻 Usage
  • 📖 API Reference
  • 🗺️ Roadmap
  • 🤝 Contributing
  • 📞 Contact
  • 📄 License
  • 🙏 Acknowledgments

⭐ 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)
• Outgoing MMS with subject, text, and base64 attachments via MmsMessage (E2E-encrypted when configured)
• 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)

🚀 Getting Started

Prerequisites

• Python 3.9 or higher
• An SMSGate account with API credentials
• An Android device running the SMSGate app

Quick Setup

1. Install the library with your preferred HTTP backend:

   pip install android-sms-gateway[requests]
   

2. Set environment variables:

   export SMSGATE_LOGIN="your-login"
   export SMSGATE_PASSWORD="your-password"
   

3. Send your first message:

   import os
   from android_sms_gateway import client, domain
   
   message = domain.Message(
       phone_numbers=["+12025550100"],
       text_message=domain.TextMessage(text="Hello from Python"),
   )
   
   with client.APIClient(os.getenv("SMSGATE_LOGIN"), os.getenv("SMSGATE_PASSWORD")) as c:
       state = c.send(message)
       print(f"Message ID: {state.id}")
   

🔑 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)

💻 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

🗺️ Roadmap

• Add support for batch message sending
• Implement message scheduling
• Add webhook signature verification
• Support for custom HTTP headers
• Async context manager improvements

See the open issues for a full list of proposed features and known issues.

🤝 Contributing

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

📞 Contact

Aleksandr Soloshenko - admin@sms-gate.app

Project Link: https://github.com/android-sms-gateway/client-py

📄 License

Distributed under the Apache License 2.0. See LICENSE.

🙏 Acknowledgments

• requests - HTTP library for sync requests
• aiohttp - Async HTTP client/server
• httpx - Modern HTTP client for sync and async
• pycryptodome - Cryptographic library for encryption
• Best README Template - README structure inspiration