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.
- 🚀 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
- 📱 SMS Gateway for Android™ Python API Client
- 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 |
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 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 or ahttp.HttpClient 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: support@sms-gate.app
- 💬 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.