Pre-Release 0.5 - Dashboard

🎉 What's New in 0.5 (Pre-Release)

The main feature of version 0.5 is the new UI Dashboard!

New Features

• UI Dashboard: Introducing the new UI Dashboard (Still Closed Source) which lives within the same Docker image.
• MMS Support: The routing for GET /adb/list-messages now supports MMS Messages.
• Update Notifications: Added a latest_version fetch to /auth/@me to notify users automatically of updates when available via the Dashboard.
• Password Reset: Added a new password-reset route.

Improvements & Fixes

• Message Retention: Core database change in the messages table - messages are no longer deleted from the table at the monthly reset date, so they continue to show up in the chat history.
• Asynchronous Utils: utils/database.py and utils/adb.py now serve their functions as asynchronous.
• Code Pairing Fix: Fixed an issue where code pairing did not connect to the device automatically after the pairing process.
• Cleanup: Partial leftovers cleanup for the deprecated user feature.

Pre-Release 0.4 - API Tokens

🎉 What's New in 0.4 (Pre-release)

Token-Based Authentication & System Overhaul

Version 0.4 introduces a major overhaul to the authentication system, replacing traditional user accounts with a more robust API Token system.

Critical Changes

• Database Migration: You MUST set MIGRATE_DATABASE=True in your environment variables to upgrade your database schema. The application will not start without this if a migration is pending. (only applies for database created with version 0.3 and lower)
• User System: "Standard Users" have been replaced by API Tokens.

Features & Improvements

• API Tokens: New endpoints to create, list, manage, and refresh API tokens with specific message limits.
• Unified Auth: Support for both Authorization: Bearer <TOKEN> and X-API-Key: <TOKEN>.
• Token Refresh: Ability to rotate a token's secret while keeping the same ID and history.
• Expanded Access: API Tokens can now access /adb/list-devices.
• Status Info: GET /auth/@me now returns detailed quota information.

Android-SMS-API 0.3 (Pre-Release) - UI Preparations and minor bug fixes

🎉 What's New in 0.3 (Pre-release)

Features & Improvements

• Added a route to get and list all conversations on the device

• Added a route to list all users

• GET /auth/@me now returns how many messages are left for the current month

P.S. Parts of this release are preperations for the UI Interface which is coming VERY soon!

Bug Fixes

• Timeout handling for ADB POST /adb/connect-device - trace back to client
• device_id was limited to 35 characters (raised to 99) - code pairing devices have longer names than 35 characters

Android-SMS-API 0.2 (Pre-Release)

🎉 What's New in 0.2 (Pre-release)

Features & Improvements

• Added a new API route to support pairing devices via a 6-digit code, offering an alternative to QR code scanning.

• Replaced the embedded ADB binary with the system-level android-tools-adb package. This improves stability and compatibility across different container environments.

Bug Fixes

• Fixed major bugs that made delete-account endpoint not to work

• Resolved connectivity issues preventing successful wireless device pairing in Dockerized environments.

• Fixed an issue where remember_me tokens were not persisting correctly; tokens now utilize a 10-year expiration for long-term sessions.

• Corrected username validator logic and pattern. Usernames can now be 3–32 characters long, include numbers and hyphens (previously restricted to 10 characters maximum and no numbers were allowed).

Android-SMS-API 0.1 (Pre-Release)

Android SMS API Gateway 0.1 (Pre-Release)

Turn your Android device into a professional SMS Server

This application transforms any Android device into a dedicated, self-hosted SMS Gateway. It provides a robust RESTful API that allows you to programmatically send SMS messages over your cellular network, manage device connections via ADB, and enforce secure, role-based access control for multiple users or services.

Table of Contents

• Features & Capabilities
• System Architecture
  • The User Concept
• Deployment
  • Docker
  • Docker Compose
• Environment Configuration
• User Management System
  • The Hardcoded Administrator
  • Administrator Roles
  • Standard User Roles
• ADB Connection & Hardware Setup
  • Hardware Recommendations
  • Device Configuration
    • Enabling Developer Options
    • Essential Settings
  • Wireless ADB Pairing (QR-Code)
    • Trigger the QR Code
    • Pairing Instructions
    • Verify Connection

---

Features & Capabilities

• Turn Key SMS Gateway: Send SMS messages programmatically via simple HTTP requests.
• Device Management: Seamlessly connect and manage Android devices via ADB (Android Debug Bridge) over Wi-Fi or USB.
• Role-Based Access Control (RBAC): Distinct permission levels for Administrators (infrastructure management) and Standard Users (message dispatch).
• Quota Management: Automatic tracking of SMS usage per user with monthly resets on a configurable billing day.
• Remote Shell Execution: Administrators can execute raw ADB SHELL commands directly on the device for advanced debugging or automation.
• Simple Authentication: Secure access via JWT-based tokens.

Note on Message Content: Currently, the send-message endpoint supports ASCII/Plain text only. Emoji support is in development and is not supported (YET).

---

System Architecture

The "User" Concept

In this API, a "Standard User" is not limited to a human operator. A user entity functions effectively as a Service Account or API Key.

• Example Use Case: You can create a user named alert-system with a 500-message limit and a separate user named marketing-bot with a 5,000-message limit.
• This allows multiple external applications to share the same physical Android hardware while maintaining isolated quotas and credentials.

---

Deployment

The application is available as a Docker image. For data persistence (logs and database), you must mount the /data volume.

Docker

Run the container directly using Docker. This method is useful for quick setups, testing, or when you don’t need Docker Compose.

Important: Make sure you are running this command from the directory where you want the data folder to be created, as it will be mounted into the container for persistent storage.

To start the container, run:

docker run \
  --restart unless-stopped \
  -p 8080:8000 \
  -v "$(pwd)/data:/app/data" \
  --name android-sms-api \
  agamsol/android-sms-api:latest

This command will:

• Pull the image if it’s not already available locally
• Start a single container named android-sms-api
• Expose the API on port 8080 (host) mapped to 8000 (container)
• Persist application data in the local ./data directory
• Automatically restart the container unless it is explicitly stopped

If you need to perform device QR pairing or any other interactive setup, run the container in the foreground (as shown above) so you can see the terminal output.

To stop the container:

docker stop android-sms-api

To remove the container:

docker rm android-sms-api

For more information about Docker commands and options, see the official Docker documentation:
https://docs.docker.com/engine/reference/run/

Docker Compose

For a persistent, server-ready deployment, use the provided docker-compose.yml file. This setup is recommended for long-running or production-like environments, as it simplifies service management, networking, and restarts.

Important: Make sure you are in the same directory as the docker-compose.yml file before running any Docker Compose commands.

Starting the service

To start the service in detached (background) mode, run:

docker compose up -d

This will start the container in the background. Use this mode once everything is already configured.

If you need to perform device QR pairing or any other interactive setup, start Docker Compose without the -d flag so you can see the terminal output and interact when needed:

docker compose up

You can stop the service at any time by pressing Ctrl + C when running in the foreground.

Managing the service

Check the status of the running service:

docker compose ps

View logs for the service (useful for debugging):

docker compose logs -f

Stop the service without removing the container:

docker compose stop

Stop and remove the container, network, and volumes created by Docker Compose:

docker compose down -v

For a full list of available commands, configuration options, and advanced usage, see the official Docker Compose documentation:
https://docs.docker.com/compose/

---

Environment Configuration

Create a .env file in the root directory using the keys below. You can copy .env.sample to get started.

Key	Description	Default
VERSION	The current version of the application meta info.	Unknown
ADMIN_USERNAME	The username for the immutable hardcoded administrator.	admin
ADMIN_PASSWORD	The password for the hardcoded administrator. If not specified, a secure random string is automatically generated on startup.	<Auto-Generated>
LOGGER_LEVEL	Logging verbosity level.	INFO
LOGGER_PATH	Directory path where logs will be stored.	data/logs
PLAN_RESET_DAY_OF_MONTH	The day of the month (1-31) when user message limits are reset. Set to 0 to disable the monthly reset.	23
DATABASE_PATH	File path for the SQLite3 database.	data/Android-SMS-API.db
ADB_QR_DEVICE_PAIRING	Set to True to enable the QR code pairing endpoint.	True
ADB_AUTO_CONNECT	If True, the server attempts to auto-connect to the specific device identifier defined in ADB_DEFAULT_DEVICE on startup.	False
ADB_DEFAULT_DEVICE	(Optional) Pre-define a specific device identifier to connect to (Required if Auto-Connect is enabled).	Empty
ADB_SHELL_EXECUTION_ROUTE_ENABLED	Enables the endpoint allowing admins to run raw ADB shell commands.	True
JWT_ALGORITHM	Algorithm used for signing JSON Web Tokens.	HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES	Token validity duration in minutes.	60
JWT_SECRET	Secret key used to sign the JWT. If not specified, a secure random string is automatically generated on startup.	<Auto-Generated>

---

User Management System

The server manages a tiered user system. Message limits are reset automatically based on the PLAN_RESET_DAY_OF_MONTH defined in your environment variables.

The Hardcoded Administrator

The Hardcoded User is a fallback super-admin defined at the code-level within the .env file.

• Persistence: This user does not exist in the SQLite database and persists through database wipes.
• Immutability: This user cannot be deleted or modified via the API.
• Purpose: Ensures administrative access is always available for system recovery or initial setup.

Administrator Roles

Administrators (Hardcoded or Database-created) have elevated privileges:

• User Management: Create/Delete users and adjust monthly quotas.
• Security: Reset passwords for any user in the system.
• Device Ops: Manage ADB pairing, connections, and view device lists.
• Code Execution: Permission to execute ADB SHELL commands.
• Unlimited Limits: Administrators are NOT subject to monthly message caps.

Standard User Roles

Standard users are designed for operational use (apps or humans):

• Message Dispatch: Can send SMS messages via the API (Strictly Text/ASCII).
• Quota Enforcement: Message sending is rejected if the monthly limit is exceeded.
• Self-Management: Can only reset or change their own password.

---

ADB Connection & Hardware Setup

Reliability relies on correct hardware setup and persistent ADB connections. The system supports Standard Connection (IP/Port or USB) and Wireless QR-Pairing (Android 11+).

Hardware Recommendations

Power Source

The Android device must be connected to a power source 24/7 to ensure uninterrupted availabil...