Skip to content

Latest commit

 

History

History
70 lines (51 loc) · 2.92 KB

README.md

File metadata and controls

70 lines (51 loc) · 2.92 KB

PSM API Server (Android)

Full-featured SMS/MMS HTTP API server that runs entirely on an Android device.

Highlights

  • Works on Android 4.3 (API 18) – last version that still allows 3rd-party MMS access.
  • HTTP server (NanoHTTPD) exposed on the device IP (default port 8080).
  • Send / receive SMS & MMS, statistics, contact import, live uptime counter.
  • Auto-start at boot, background service with ongoing notification.
  • Built with Kotlin + AndroidX, but trimmed to stay compatible with API 18.

Core API Endpoints

Method Path Description
GET /health Quick health-check JSON {status:"healthy"}
GET /docs HTML documentation page (device browser)
GET /statistics JSON with server + usage stats
GET /uptime {uptime_minutes:123}
GET /messages?phoneNumber=&type=&limit= List messages, optional filters
GET /phone-numbers List phone numbers that have message history
GET /contacts List phone numbers imported from device contacts
POST /sms/send Body {phoneNumber:"+123", message:"hi"}
POST /mms/send Multipart form: phoneNumber, message, attachment

See /docs while the server is running for examples.

Building the App

Tool Version
Android Studio Hedgehog / Electric Eel+
Gradle 7.6.1 wrapper (bundled)
Android Gradle Plugin 7.4.2
compileSdk / targetSdk 33
minSdk 18
JDK 11 (set in Android Studio: Preferences ▶ Build Tools ▶ Gradle JDK)

Steps:

  1. Open project in Android Studio.
  2. When prompted, allow it to download SDK Platform 33 (build only).
  3. Ensure File ▶ Project Structure ▶ JDK points to a JDK 11 install.
  4. Run ▶ app – the APK installs on any device/emulator running API 18 +.

Runtime Permissions

On first launch the app requests SMS / MMS / storage / network permissions. After granting once they are remembered; the prompt is suppressed on subsequent launches.

UI Overview

  • Main screen – server status, uptime, IP address, quick nav buttons.
  • Settings – change port, toggle auto-start, scan contacts, restart server.
  • Chat Overview – list conversations; tap to see message history.

Customising

  • HTTP port is saved in Settings. All endpoints automatically use the new port after restart.
  • Colors / typography live in res/values/colors.xml and layout card styles.

Limitations & Notes

  • MMS sending on API 18 is best-effort; attachment support depends on the device.
  • On very old devices vector drawables aren't supported; notification icon uses PNG.
  • OpenGL/EGL warnings seen in logcat on emulators are harmless.

Released under MIT license. Enjoy hacking your retro Android SMS gateway!
Please star the repo if you find it useful.