httpSMS

httpSMS is a service that lets you use your Android phone as an SMS Gateway to send and receive SMS messages. You make a request to a simple HTTP API and it triggers your Android phone to send an SMS. SMS messages received on your android phone can also be forwarded to your webhook endpoint.

Quick Start Guide 👉 https://docs.httpsms.com

• Why?
• Web UI
• API
• Android App
• Chat/forum
• Features
  • End-to-end Encryption
  • Webhook
  • Back Pressure
  • Message Expiration
• API Clients
• Flows
  • Sending an SMS Message
• Self Host Setup - Docker
  • 1. Setup SMTP Email service
  • 2. Setup Cloudflare Turnstile
  • 3. Download the code
  • 4. Setup the environment variables
  • 5. Build and Run
  • 6. Create the System User
  • 7. Build the Android App.
• Integration Testing
• License

I'm originally from Cameroon and I wanted an automated way to send and receive SMS messages using an API. Unfortunately many countries don't support the ability to buy virtual phone numbers, and I could not find a good ready-made solution that could help me send/receive SMS messages using a mobile phone using an intuitive http API.

The web interface https://httpsms.com is built using Nuxt and Vuetify. It is a single page application (deployed to Cloudflare Pages). The source code is in the web directory

The API https://api.httpsms.com is built using Fiber, Go and CockroachDB for the database. It rus as a serverless application on Google Cloud Run. The API documentation can be found here https://api.httpsms.com/index.html

// Sending an SMS Message using Go
client := htpsms.New(htpsms.WithAPIKey(/* API Key from https://httpsms.com/settings */))

client.Messages.Send(context.Background(), &httpsms.MessageSendParams{
    Content: "This is a sample text message",
    From:    "+18005550199",
    To:      "+18005550100",
})

The Android App is a native application built using Kotlin with material design principles. This app must be installed on an Android phone before you can start sending and receiving SMS messages.

There are a few ways to get in touch with me and/or the rest of the community. Feel free to use any of these methods. Whatever works best for you:

• Discord server - direct chat with the community
• GitHub issues - questions, features, bugs

You can encrypt your messages end-to-end ysubg the military grade AES-256 encryption algorithm. Your encryption key is stored only on our mobile phone so the even the server won't have any way to view the content of your SMS messages which are sent and received on your Android phone.

If you want to build advanced integrations, we support webhooks. The httpSMS platform can forward SMS messages received on the android phone to your server using a callback URL which you provide.

In-order not to abuse the SMS API on android, you can set a rate limit e.g 3 messages per minute. Such that even if you call the API to send messages to 100 people, It will only send the messages at a rate of 3 messages per minute.

Sometimes it happens that the phone doesn't pick up the queued message in time and I can't send the SMS message. It is possible to set a timeout for which a message is valid and if a message becomes expired after the timeout elapses, you will be notified.

• Go: https://github.com/NdoleStudio/httpsms-go
• JavaScript/TypeScript: https://github.com/NdoleStudio/httpsms-node

sequenceDiagram
User->>+httpSMS API: Call /v1/messages/send API
httpSMS API-->>+Delivery Queue: Queue the message for the phone
httpSMS API-->>-User: Respond with 202 (Accepted)
Delivery Queue-->>+httpSMS API: [Async] Mark the phone's queue as having work
httpSMS API-->>-Android App: Hold the message (the phone long-polls)
Android App-->>httpSMS API: [Async] Fetch message
Android App-->>Android App: Send Message using Android SMS API
Android App-->>httpSMS API: [Async] Send result of sending SMS
Android App-->>httpSMS API: [Async] Send Delivery Report

The httpSMS application uses SMTP to send emails to users e.g. when your Android phone has been offline for a long period of time. You can use a service like mailtrap to create an SMTP server for development purposes.

The message search route (/v1/messages/search) is protected by a Cloudflare Turnstile captcha to prevent abuse. You need to set up a Turnstile widget for the search messages feature to work.

1. Go to the Cloudflare dashboard and navigate to Turnstile.
2. Add a new site and configure it for your self-hosted domain (e.g., localhost for local development).
3. Note down the Site Key and Secret Key — you will need them for the frontend and backend environment variables respectively.

Clone the httpSMS GitHub repository

git clone https://github.com/NdoleStudio/httpsms.git

• Copy the .env.docker file in the web directory into .env

cp web/.env.docker web/.env

• Update the environment variables in the .env file in the web directory (the SPA reads API_BASE_URL for the API endpoint)

# Cloudflare Turnstile site key from step 2
CLOUDFLARE_TURNSTILE_SITE_KEY=

• Copy the .env.docker file in the api directory into .env

cp api/.env.docker api/.env

• Update the environment variables in the .env file in the api directory with your SMTP server details and Cloudflare Turnstile secret key.

# SMTP email server settings
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_HOST=
SMTP_PORT=

# Cloudflare Turnstile secret key from step 2
CLOUDFLARE_TURNSTILE_SECRET_KEY=

• Don't bother about the EVENTS_QUEUE_USER_API_KEY and EVENTS_QUEUE_USER_ID settings. We will set that up later.

• Build and run the API, the web UI, database and cache using the docker-compose.yml file. It takes a while for build and download all the docker images. When it's finished, you'll be able to access the web UI at http://localhost:3000 and the API at http://localhost:8000

docker compose up --build

• The application uses the concept of a system user to process events async. You should manually create this user in users table in your database. Make sure you use the same id and api_key as the EVENTS_QUEUE_USER_ID, and EVENTS_QUEUE_USER_API_KEY in your .env file.

  INSERT INTO users (id, api_key, email ) VALUES ('your-system-user-id', 'your-system-api-key', 'system@domain.com');

• Open the android directory in Android Studio and build/run the app.
• No Google Play Services, Firebase or google-services.json is involved: the app long-polls your API for outbound messages through a foreground service, so it works on GMS-less devices (e.g. mainland China).

The project includes end-to-end integration tests that validate the complete SMS send/receive lifecycle. Tests run the full stack (API, PostgreSQL, Redis) in Docker alongside a phone emulator that simulates an Android device.

📖 Full documentation: tests/README.md

Quick run:

cd tests
docker compose up -d --build --wait
docker compose wait seed && sleep 2
go test -v -timeout 120s ./...
docker compose down -v

Integration tests also run automatically in CI on every push/PR to main.

Um Missbrauch vorzubeugen, gelten für alle Tarife mit SMS-Flat als Tarifkomponente oder als zubuchbare Option folgende zusätzliche Regelungen:

• Der automatisierte Versand von SMS ist unzulässig.
• Der Versand von SMS an mehr als 50 Empfänger gleichzeitig ist unzulässig.
• Die Nutzung der Zusatzdienstleistung mit einem SMS-Modemzugang und/oder mit SMS zu E-Mail oder Fax ist unzulässig.

1&1 geht weiterhin von einer missbräuchlichen Nutzung bei mehr als 3.000 SMS pro Monat aus. In diesem Fall behält sich 1&1 vor, das Vertragsverhältnis außerordentlich zu kündigen.

This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE Version 3 - see the LICENSE file for details