/android-sms-gateway

An Android SMS Gateway app that enables sending SMS messages via a local or cloud server API

Primary LanguageKotlinApache License 2.0Apache-2.0

Contributors Forks Stargazers Issues Apache 2.0 License


Logo

Android SMS Gateway

Turns your smartphone into an SMS gateway for sending messages via API.
Explore the docs »

Report Bug · Request Feature

About The Project

Android SMS Gateway turns your Android smartphone into an SMS gateway. It's a lightweight application allowing you to send SMS messages programmatically via API. This makes it ideal for integrating SMS functionality into your own applications or services.

Features

  • No registration: No registration or email is required to create an account. In local mode you don't need an account at all!
  • Send SMS by API: Use our API to send messages directly from your own applications or services.
  • Supports Android 5.0 and above: The application is compatible with Android 5.0 and later versions.
  • Message status tracking: Monitor the status of your sent messages in real-time.
  • Starts at boot: The application starts running as soon as your device boots up.
  • Multiple SIM cards: The application supports multiple SIM cards.
  • Multipart messages: The application supports sending long messages with auto-partitioning.
  • End-to-end encryption: No one in the middle can access the content and recipients of the messages.

Ideal For

  • Notifications
  • Alerts
  • Two-factor authentication codes

Android SMS Gateway provides a convenient and reliable solution, whether you need to send notifications, alerts, or two-factor authentication codes.

(back to top)

Built With

  • Kotlin
  • Ktor
  • Room
  • Firebase

(back to top)

Installation

You can install app to your device from prebuilt APK or by building from sources.

Prerequisites

You need an Android device with Android 5.0 (Lollipop) or above for using the application.

Permissions

To use the application, you need to grant the following permissions:

  • SEND_SMS: This permission is required to send SMS messages.
  • READ_PHONE_STATE: This permission is required to select the SIM card. Optional, if you don't want to select the SIM card.

Installation from APK

  1. Navigate to the Releases page.
  2. Download the latest APK file from the list of available releases.
  3. Transfer the APK file to your Android device.
  4. On your Android device, go to Settings > Security (or Privacy on some devices).
  5. Enable the Unknown sources option to allow installation of apps from sources other than the Play Store.
  6. Use a file manager app to navigate to the location of the downloaded APK file.
  7. Tap on the APK file to start the installation process.
  8. Follow the on-screen prompts to complete the installation.

(back to top)

Getting Started

The Android SMS Gateway can work in two modes: with a local server started on the device or with a cloud server at sms.capcom.me. The basic API is the same for both modes and is documented on the Android SMS Gateway API Documentation.

Local server

Local server example settings

This mode is recommended for sending messages from local network.

  1. Start the app on the device.

  2. Activate the Local server switch.

  3. Tap the Offline button at the bottom of the screen.

  4. In the Local server section, the local and public addresses of the device, along with the credentials for basic authentication, will be displayed. Please note that the public address is only usable if you have a "white" IP address and have correctly configured your firewall.

  5. Make a curl call from the local network using a command like the following, replacing <username>, <password>, and <device_local_ip> with the values obtained in step 4:

    curl -X POST -u <username>:<password> \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' \
  http://<device_local_ip>:8080/message

Cloud server

Cloud server example settings

If you need to send messages with dynamic or shared device IP, you can use the cloud server. The best part? No registration, email, or phone number is required to start using it.

  1. Start the app on the device.

  2. Activate the Cloud server switch.

  3. Tap the Offline button at the bottom of the screen.

  4. In the Cloud server section, the credentials for basic authentication will be displayed.

  5. Make a curl call using a command like the following, replacing <username> and <password> with the values obtained in step 4:

    curl -X POST -u <username>:<password> \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' \
  https://sms.capcom.me/api/3rdparty/v1/message

For more examples, please refer to the API Documentation

(back to top)

Roadmap

  • Add functionality to modify user credentials.
  • Introduce option to adjust the local server port.
  • Send notifications to an external server when the status of a message changes.
  • Incorporate scheduling capabilities for dispatching messages at specific times.
  • Implement region-based restrictions to prevent international SMS.
  • Provide an API endpoint to retrieve the list of available SIM cards on the device.
  • Include detailed error messages in responses and logs.

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

(back to top)

License

Distributed under the Apache-2.0 license. See LICENSE for more information.

(back to top)

Contact

Project Link: https://github.com/capcom6/android-sms-gateway

(back to top)