A modern Python client for seamless integration with the SMS Gateway for Android API. Send SMS messages programmatically through your Android devices with this powerful yet simple-to-use library.
The Python client for SMSGate provides a clean, type-safe interface to interact with the SMSGate API. It's designed specifically for Python developers who need to integrate SMS functionality into their applications with minimal setup and maximum reliability.
Key value propositions:
- 🐍 Pythonic API - Designed with Python conventions and best practices in mind
- 🛡️ Robust Security - Guidance for secure credential handling and optional end‑to‑end encryption
- 🔄 Flexible Architecture - Supports both synchronous and asynchronous programming patterns
- 💻 Type Safety - Full type hinting for better developer experience and fewer runtime errors
- 🔗 Webhook Integration - Simplified webhook management for event-driven architectures
This client abstracts away the complexities of the underlying HTTP API while providing all the necessary functionality to send and track SMS messages through Android devices.
- 📱 SMS Gateway for Android™ Python API Client
- 🔄 Dual Client: Supports both synchronous (
APIClient) and asynchronous (AsyncAPIClient) interfaces - 🔒 End-to-End Encryption: Optional message encryption using AES-256-CBC
- 🌐 Multiple HTTP Backends: Native support for
requests,aiohttp, andhttpx - 🔗 Webhook Management: Programmatically create, query, and delete webhooks
- ⚙️ Customizable Base URL: Point to different API endpoints
- 💻 Full Type Hinting: Fully typed for better development experience
⚠️ Robust Error Handling: Specific exceptions and clear error messages- 📈 Delivery Reports: Track your message delivery status
- Python: 3.9 or higher
- HTTP Client (choose one):
Optional Dependencies:
- 🔒 pycryptodome - For end-to-end encryption support
pip install android-sms-gateway# Choose an HTTP client:
pip install android-sms-gateway[requests] # For synchronous use
pip install android-sms-gateway[aiohttp] # For asynchronous use
pip install android-sms-gateway[httpx] # For both synchronous and asynchronous use# For encrypted messages:
pip install android-sms-gateway[encryption]
# Or install everything:
pip install android-sms-gateway[requests,encryption]-
Configure your credentials:
export ANDROID_SMS_GATEWAY_LOGIN="your_username" export ANDROID_SMS_GATEWAY_PASSWORD="your_password"
-
Basic usage example:
import asyncio
import os
from android_sms_gateway import client, domain
# Configuration
login = os.getenv("ANDROID_SMS_GATEWAY_LOGIN")
password = os.getenv("ANDROID_SMS_GATEWAY_PASSWORD")
# Create message
message = domain.Message(
"Hello! This is a test message.",
["+1234567890"],
with_delivery_report=True
)
# Synchronous Client
def sync_example():
with client.APIClient(login, password) as c:
# Send message
state = c.send(message)
print(f"Message sent with ID: {state.id}")
# Check status
status = c.get_state(state.id)
print(f"Status: {status.state}")
# Asynchronous Client
async def async_example():
async with client.AsyncAPIClient(login, password) as c:
# Send message
state = await c.send(message)
print(f"Message sent with ID: {state.id}")
# Check status
status = await c.get_state(state.id)
print(f"Status: {status.state}")
if __name__ == "__main__":
print("=== Synchronous Example ===")
sync_example()
print("\n=== Asynchronous Example ===")
asyncio.run(async_example())from android_sms_gateway import client, domain, Encryptor
# Encryption setup
encryptor = Encryptor("my-super-secure-secret-passphrase")
# Encrypted message
message = domain.Message(
"This message will be encrypted!",
["+1234567890"],
is_encrypted=True
)
# Client with encryption
with client.APIClient(login, password, encryptor=encryptor) as c:
state = c.send(message)
print(f"Encrypted message sent: {state.id}")Both clients (APIClient and AsyncAPIClient) support these parameters:
| Parameter | Type | Description | Default |
|---|---|---|---|
login |
str |
API username | Required |
password |
str |
API password | Required |
base_url |
str |
API base URL | "https://api.sms-gate.app/3rdparty/v1" |
encryptor |
Encryptor |
Encryption instance | None |
http |
HttpClient/AsyncHttpClient |
Custom HTTP client | Auto-detected |
| Method | Description | Return Type |
|---|---|---|
send(message: domain.Message) |
Send SMS message | domain.MessageState |
get_state(id: str) |
Check message status | domain.MessageState |
create_webhook(webhook: domain.Webhook) |
Create new webhook | domain.Webhook |
get_webhooks() |
List all webhooks | List[domain.Webhook] |
delete_webhook(id: str) |
Delete webhook | None |
class Message:
message: str # Message text
phone_numbers: List[str] # List of phone numbers
with_delivery_report: bool = True # Delivery report
is_encrypted: bool = False # Whether message is encrypted
# Optional fields
id: Optional[str] = None # Message ID
ttl: Optional[int] = None # Time-to-live in seconds
sim_number: Optional[int] = None # SIM numberclass MessageState:
id: str # Unique message ID
state: ProcessState # Current state (SENT, DELIVERED, etc.)
recipients: List[RecipientState] # Per-recipient status
is_hashed: bool # Whether message was hashed
is_encrypted: bool # Whether message was encryptedclass Webhook:
id: Optional[str] # Webhook ID
url: str # Callback URL
event: WebhookEvent # Event typeFor more details, see domain.py.
The library automatically detects installed HTTP clients with this priority:
| Client | Sync | Async |
|---|---|---|
| aiohttp | ❌ | 1️⃣ |
| requests | 1️⃣ | ❌ |
| httpx | 2️⃣ | 2️⃣ |
from android_sms_gateway import client, http
# Force httpx usage
client.APIClient(..., http=http.HttpxHttpClient())
# Force requests usage
client.APIClient(..., http=http.RequestsHttpClient())
# Force aiohttp (async only)
async with client.AsyncAPIClient(..., http=http.AiohttpHttpClient()) as c:
# ...Implement your own HTTP client following the http.HttpClient (sync) or ahttp.AsyncHttpClient (async) protocols.
- 🔐 Credentials: Store credentials in environment variables
- 🚫 Code: Never expose credentials in client-side code
- 🔒 HTTPS: Use HTTPS for all production communications
- 🔑 Encryption: Use end-to-end encryption for sensitive messages
- 🔄 Rotation: Regularly rotate your credentials
import os
from dotenv import load_dotenv
# Load environment variables
load_dotenv()
# Secure configuration
login = os.getenv("ANDROID_SMS_GATEWAY_LOGIN")
password = os.getenv("ANDROID_SMS_GATEWAY_PASSWORD")
if not login or not password:
raise ValueError("Credentials not configured!")For complete API documentation including all available methods, request/response schemas, and error codes, visit: 📘 Official API Documentation
Contributions are very welcome! 🎉
- 🍴 Fork the repository
- 🌿 Create your feature branch (
git checkout -b feature/NewFeature) - 💾 Commit your changes (
git commit -m 'feat: add new feature') - 📤 Push to branch (
git push origin feature/NewFeature) - 🔄 Open a Pull Request
# Clone repository
git clone https://github.com/android-sms-gateway/client-py.git
cd client-py
# Create virtual environment
pipenv install --dev --categories encryption,requests
pipenv shell- Code follows style standards (black, isort, flake8)
- Tests pass locally
- Documentation updated
- Test coverage maintained or improved
This project is licensed under the Apache License 2.0 - see LICENSE for details.
- 📧 Email: [email protected]
- 💬 Discord: SMS Gateway Community
- 📖 Documentation: docs.sms-gate.app
- 🐛 Issues: GitHub Issues
Note: Android is a trademark of Google LLC. This project is not affiliated with or endorsed by Google.