📱 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) or the device-paired PublicKeyEncryptor (RSA-OAEP + AES-256-GCM). Covers messages (SMS, data, and MMS), inbox (refresh, attachments), devices, webhooks, settings, logs, health probes, and the JWT token lifecycle.
📚 Table of Contents
⭐ Features
- Synchronous
APIClientand asynchronousAsyncAPIClient(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: passphrase
Encryptor(AES-256-CBC) or device-pairedPublicKeyEncryptor(RSA-OAEP + AES-256-GCM, encrypt-only) - Webhooks, devices, settings, logs, and health probes (health, liveness, readiness, 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 (
APIErrorsubclasses)
📦 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
-
Install the library with your preferred HTTP backend:
pip install android-sms-gateway[requests]
-
Set environment variables:
export SMSGATE_LOGIN="your-login" export SMSGATE_PASSWORD="your-password"
-
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)
🔒 Encryption
Optional end-to-end encryption requires the encryption extra (pip install android-sms-gateway[encryption]). Pass an encryptor via encryptor= to APIClient or AsyncAPIClient; outgoing message content, phone numbers, and MMS attachments are then encrypted before send.
Two encryptors are available:
Encryptor(passphrase)— passphrase-based AES-256-CBC (PBKDF2-SHA1). Can both encrypt and decrypt, so encrypted recipient phone numbers in responses are decrypted automatically.PublicKeyEncryptor— device-paired RSA-OAEP + AES-256-GCM, built from the device's E2E public key. Encrypt-only: the private key never leaves the Android device, sodecrypt()raises and encrypted recipient numbers in responses are returned unchanged.
Device-paired encryption
import base64
import hashlib
from android_sms_gateway import PublicKeyEncryptor, client, domain
PINNED_DEVICE_ID = "your-device-id"
PINNED_FINGERPRINT = "A1B2:C3D4:E5F6:7890:ABCD:EF12:3456:7890:1111:2222:3333:4444:5555:6666:7777:8888"
def key_fingerprint(public_key: str) -> str:
digest = hashlib.sha256(base64.b64decode(public_key)).hexdigest().upper()
return ":".join(digest[i : i + 4] for i in range(0, 64, 4))
with client.APIClient(login, password) as c:
device = next((d for d in c.list_devices() if d.id == PINNED_DEVICE_ID), None)
if device is None:
raise RuntimeError("Pinned device not found")
if (
device.public_key is None
or key_fingerprint(device.public_key) != PINNED_FINGERPRINT
):
raise RuntimeError("Device key changed; re-verify it out of band before sending")
encryptor = PublicKeyEncryptor.from_device(device)
message = domain.Message(
device_id=device.id,
phone_numbers=["+12025550100"],
text_message=domain.TextMessage(text="Hello from Python"),
)
with client.APIClient(login, password, encryptor=encryptor) as c:
state = c.send(message)
The values pinned above come from the device itself (Settings → Device → Device Key): the key fingerprint, rendered as uppercase hex in 16 colon-separated groups of 4. The key returned by list_devices() is published through the server, so treat it as untrusted until verified: keep the pinned value stored outside the server and fail closed when changes. See the key verification procedure for details.
Rules enforced by the client:
from_deviceraisesValueErrorif the device has no E2E public key (public_key/key_versionunset).- If the encryptor has a
device_id,message.device_idmust match it, otherwisesendraisesValueError.from_devicesets this ID; direct construction defaults toNoneand disables the check. - Requesting state for an encrypted message without an encryptor set raises
ValueError.
💻 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
Metadata
Release files for android-sms-gateway 4.4.0
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 |
|---|---|---|---|---|
| android_sms_gateway-4.4.0.tar.gz | 46.4 kB | With provenance | Details for android_sms_gateway-4.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| android_sms_gateway-4.4.0-py3-none-any.whl | Python 3 | none | any | Details for android_sms_gateway-4.4.0-py3-none-any.whl |
Total release size: 76.9 kB
Release files / android_sms_gateway-4.4.0.tar.gz
| Download URL | android_sms_gateway-4.4.0.tar.gz |
|---|---|
| Size | 46.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4fa9ef70df6cf4b280d74c756f8fef47809df2a709cf289772f03d9a68ba602e
|
|
BLAKE2b-256 checksum How to use checksums |
a07f5845ff25fa7f1867fe05d19bf999a8818f0e0d96a407aa5074ffb0dc8bc5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / android_sms_gateway-4.4.0-py3-none-any.whl
| Download URL | android_sms_gateway-4.4.0-py3-none-any.whl |
|---|---|
| Size | 30.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aa99231236d82fdd8f9b20eafc385b5c8a71edff94100db8d257dd9b42045d07
|
|
BLAKE2b-256 checksum How to use checksums |
b78164a0a7f2da5b503e296a560e085f1f265f918043801da8578a0909edb448
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for android-sms-gateway 4.4.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for android_sms_gateway-4.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA 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.