Skip to main content

📱 SMSGate Python Client

Contributors Forks Stars Issues License PyPI Version

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 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: passphrase Encryptor (AES-256-CBC) or device-paired PublicKeyEncryptor (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 (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)

🔒 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, so decrypt() 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_device raises ValueError if the device has no E2E public key (public_key / key_version unset).
  • If the encryptor has a device_id, message.device_id must match it, otherwise send raises ValueError. from_device sets this ID; direct construction defaults to None and 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

🗺️ 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

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)

Source distribution for android-sms-gateway 4.4.0
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)

Table of built distributions (wheels) for android-sms-gateway 4.4.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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.

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