{"id":13532616,"url":"https://github.com/ndolestudio/httpsms","last_synced_at":"2026-04-14T09:03:10.000Z","repository":{"id":38278521,"uuid":"497607901","full_name":"NdoleStudio/httpsms","owner":"NdoleStudio","description":"Send and receive SMS messages using your Android phone programmatically via a simple HTTP API","archived":false,"fork":false,"pushed_at":"2024-05-01T00:54:44.000Z","size":37861,"stargazers_count":306,"open_issues_count":27,"forks_count":62,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-05-01T11:27:13.789Z","etag":null,"topics":["android-sms","android-sms-sender","httpsms","sms","sms-api","sms-gateway","sms-manager","sms-manager-api"],"latest_commit_sha":null,"homepage":"https://httpsms.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NdoleStudio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["NdoleStudio"]}},"created_at":"2022-05-29T14:02:55.000Z","updated_at":"2024-05-02T16:26:53.091Z","dependencies_parsed_at":"2023-09-24T09:12:47.449Z","dependency_job_id":"7bc572fc-33e5-4ad2-9ff3-f67c92244afd","html_url":"https://github.com/NdoleStudio/httpsms","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NdoleStudio%2Fhttpsms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NdoleStudio%2Fhttpsms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NdoleStudio%2Fhttpsms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NdoleStudio%2Fhttpsms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NdoleStudio","download_url":"https://codeload.github.com/NdoleStudio/httpsms/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419860,"owners_count":20936012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android-sms","android-sms-sender","httpsms","sms","sms-api","sms-gateway","sms-manager","sms-manager-api"],"created_at":"2024-08-01T07:01:12.318Z","updated_at":"2026-04-14T09:03:09.994Z","avatar_url":"https://github.com/NdoleStudio.png","language":"Go","funding_links":["https://github.com/sponsors/NdoleStudio","https://github.com/sponsors/ndolestudio"],"categories":["🙌 Projects using Vuetify \u003ca name=\"projects\"\u003e\u003c/a\u003e"],"sub_categories":["🏢 Open source solutions \u003ca name=\"open-source\"\u003e\u003c/a\u003e"],"readme":"# httpSMS\n\n[![Build](https://github.com/NdoleStudio/httpsms/actions/workflows/ci.yml/badge.svg)](https://github.com/NdoleStudio/httpsms/actions/workflows/ci.yml)\n[![GitHub contributors](https://img.shields.io/github/contributors/NdoleStudio/httpsms)](https://github.com/NdoleStudio/httpsms/graphs/contributors)\n[![GitHub license](https://img.shields.io/github/license/NdoleStudio/httpsms?color=brightgreen)](https://github.com/NdoleStudio/httpsms/blob/master/LICENSE)\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/NdoleStudio/httpsms/badges/quality-score.png?b=main)](https://scrutinizer-ci.com/g/NdoleStudio/httpsms/?branch=main)\n[![Better Stack Badge](https://uptime.betterstack.com/status-badges/v1/monitor/ldl5.svg)](https://uptime.betterstack.com/?utm_source=status_badge)\n[![Sponsors](https://img.shields.io/github/sponsors/ndolestudio?logo=github)](https://github.com/sponsors/ndolestudio)\n[![Discord](https://img.shields.io/discord/1095778291488653372?label=Discord)](https://discord.gg/kGk8HVqeEZ)\n\n[httpSMS](https://httpsms.com) is a service that lets you use your Android phone as an SMS Gateway to send and receive SMS messages.\nYou 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.\n\nQuick Start Guide 👉 [https://docs.httpsms.com](https://docs.httpsms.com)\n\n\u003cimg width=\"1115\" alt=\"header\" src=\"https://user-images.githubusercontent.com/4196457/194767449-f12d84a0-22f1-4787-afb2-17398fb459f6.png\"\u003e\n\n## Table Of Contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Why?](#why)\n- [Web UI](#web-ui)\n- [API](#api)\n- [Android App](#android-app)\n- [Chat/forum](#chatforum)\n- [Features](#features)\n  - [End-to-end Encryption](#end-to-end-encryption)\n  - [Webhook](#webhook)\n  - [Back Pressure](#back-pressure)\n  - [Message Expiration](#message-expiration)\n- [API Clients](#api-clients)\n- [Flows](#flows)\n  - [Sending an SMS Message](#sending-an-sms-message)\n- [Self Host Setup - Docker](#self-host-setup---docker)\n  - [1. Setup Firebase](#1-setup-firebase)\n  - [2. Setup SMTP Email service](#2-setup-smtp-email-service)\n  - [3. Setup Cloudflare Turnstile](#3-setup-cloudflare-turnstile)\n  - [4. Download the code](#4-download-the-code)\n  - [5. Setup the environment variables](#5-setup-the-environment-variables)\n  - [6. Build and Run](#6-build-and-run)\n  - [7. Create the System User](#7-create-the-system-user)\n  - [8. Build the Android App.](#8-build-the-android-app)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Why?\n\nI'm originally from Cameroon and I wanted an automated way to send and receive SMS messages using an API.\nUnfortunately many countries don't support the ability to buy virtual phone numbers, and I could not find a good ready-made\nsolution that could help me send/receive SMS messages using a mobile phone using an intuitive http API.\n\n## Web UI\n\nThe web interface https://httpsms.com is built using [Nuxt](https://nuxtjs.org/) and [Vuetify](https://vuetifyjs.com/en/).\nIt is hosted as a single page application on firebase. The source code is in the [web](./web) directory\n\n## API\n\nThe API https://api.httpsms.com is built using [Fiber](https://gofiber.io/), Go and [CockroachDB](https://www.cockroachlabs.com/) for the database.\nIt rus as a serverless application on Google Cloud Run. The API documentation can be found here https://api.httpsms.com/index.html\n\n```go\n// Sending an SMS Message using Go\nclient := htpsms.New(htpsms.WithAPIKey(/* API Key from https://httpsms.com/settings */))\n\nclient.Messages.Send(context.Background(), \u0026httpsms.MessageSendParams{\n    Content: \"This is a sample text message\",\n    From:    \"+18005550199\",\n    To:      \"+18005550100\",\n})\n```\n\n## Android App\n\n[The Android App](https://apk.httpsms.com/HttpSms.apk) is a native application built using Kotlin with material design principles.\nThis app must be installed on an Android phone before you can start sending and receiving SMS messages.\n\n[\u003cimg src=\".github/ghbadge.png\" alt=\"Get it on GitHub\" height=\"80\"\u003e](https://github.com/NdoleStudio/httpsms/releases/)\n\n## Chat/forum\n\nThere 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\nworks best for you:\n\n- [Discord server](https://discord.gg/kGk8HVqeEZ) - direct chat with the community\n- [GitHub issues](https://github.com/NdoleStudio/httpsms/issues) - questions, features, bugs\n\n## Features\n\n### End-to-end Encryption\n\nYou can encrypt your messages end-to-end ysubg the military grade [AES-256 encryption](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)\nalgorithm. Your encryption key is stored only on our mobile phone so the even the server won't have any way to view the\ncontent of your SMS messages which are sent and received on your Android phone.\n\n### Webhook\n\nIf you want to build advanced integrations, we support webhooks. The httpSMS platform can forward SMS messages received\non the android phone to your server using a callback URL which you provide.\n\n### Back Pressure\n\nIn-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\ncall the API to send messages to 100 people, It will only send the messages at a rate of 3 messages per minute.\n\n### Message Expiration\n\nSometimes it happens that the phone doesn't get the push notification in time and I can't send the SMS message. It is\npossible to set a timeout for which a message is valid and if a message becomes expired after the timeout elapses, you\nwill be notified.\n\n## API Clients\n\n- [x] Go: https://github.com/NdoleStudio/httpsms-go\n- [x] JavaScript/TypeScript: https://github.com/NdoleStudio/httpsms-node\n\n## Flows\n\n### Sending an SMS Message\n\n```mermaid\nsequenceDiagram\nUser-\u003e\u003e+httpSMS API: Call /v1/messages/send API\nhttpSMS API--\u003e\u003e+Push Queue: Schedule notification about new message\nhttpSMS API--\u003e\u003e-User: Respond with 202 (Accepted)\nPush Queue--\u003e\u003e+httpSMS API: [Async] Send notification request\nhttpSMS API--\u003e\u003e-Android App: Send push notification about new message\nAndroid App--\u003e\u003ehttpSMS API: [Async] Fetch message\nAndroid App--\u003e\u003eAndroid App: Send Message using Android SMS API\nAndroid App--\u003e\u003ehttpSMS API: [Async] Send result of sending SMS\nAndroid App--\u003e\u003ehttpSMS API: [Async] Send Delivery Report\n```\n\n## Self Host Setup - Docker\n\n### 1. Setup Firebase\n\n- The httpSMS application uses [firebase cloud messaging](https://firebase.google.com/docs/cloud-messaging) for sending push notifications to your Android phone to trigger an SMS message to be sent out.\n  Visit the [firebase console](https://console.firebase.google.com/) and create a new project and follow the [steps here](https://firebase.google.com/docs/web/setup#register-app) to get your firebase web SDK config credentials.\n  For example, I created a firebase project called `httpsms-docker` and this is my web SDK configuration\n\n```js\nconst firebaseConfig = {\n  apiKey: \"AIzaSyAKqPvj51igvvNNcRtxxxxx\",\n  authDomain: \"httpsms-docker.firebaseapp.com\",\n  projectId: \"httpsms-docker\",\n  storageBucket: \"httpsms-docker.appspot.com\",\n  messagingSenderId: \"668063041624\",\n  appId: \"1:668063041624:web:29b9e3b702796xxxx\",\n  measurementId: \"G-18VRYL2xxxx\",\n};\n```\n\n- Enable `Email/Password` sign-in in the [Firebase console](https://console.firebase.google.com/u/0/), open the **Authentication** section. On the Sign in method tab, enable the `Email/password` sign-in method and click `Save`.\n  - The firebase `email/password` sign-in method has [a bug](https://github.com/firebase/firebaseui-web/issues/1040) which prevents you from signing in. The work around right now is to [disable email enumeration protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection#disable) on the firebase console.\n- Generate your firebase service account credentials by following the [steps here](https://firebase.google.com/docs/admin/setup#initialize_the_sdk_in_non-google_environments) and save the credentials in a file called `firebase-credentials.json` we will use this file to authenticate with the firebase admin SDK.\n- Generate your Android `google-services.json` file using [the instructions here](https://support.google.com/firebase/answer/7015592?hl=en#android\u0026zippy=%2Cin-this-article) we will use it letter to configure the android app.\n\n### 2. Setup SMTP Email service\n\nThe httpSMS application uses [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol) to send emails to users e.g. when your Android phone has been offline for a long period of time.\nYou can use a service like [mailtrap](https://mailtrap.io/) to create an SMTP server for development purposes.\n\n### 3. Setup Cloudflare Turnstile\n\nThe message search route (`/v1/messages/search`) is protected by a [Cloudflare Turnstile](https://developers.cloudflare.com/turnstile/get-started/) captcha to prevent abuse. You need to set up a Turnstile widget for the search messages feature to work.\n\n1. Go to the [Cloudflare dashboard](https://dash.cloudflare.com/) and navigate to **Turnstile**.\n2. Add a new site and configure it for your self-hosted domain (e.g., `localhost` for local development).\n3. Note down the **Site Key** and **Secret Key** — you will need them for the frontend and backend environment variables respectively.\n\n### 4. Download the code\n\nClone the httpSMS GitHub repository\n\n```bash\ngit clone https://github.com/NdoleStudio/httpsms.git\n```\n\n### 5. Setup the environment variables\n\n- Copy the `.env.docker` file in the `web` directory into `.env`\n\n```bash\ncp web/.env.docker web/.env\n```\n\n- Update the environment variables in the `.env` file in the `web` directory with your firebase web SDK configuration in step 1 above\n\n```dotenv\nFIREBASE_API_KEY=\nFIREBASE_AUTH_DOMAIN=\nFIREBASE_PROJECT_ID=\nFIREBASE_STORAGE_BUCKET=\nFIREBASE_MESSAGING_SENDER_ID=\nFIREBASE_APP_ID=\nFIREBASE_MEASUREMENT_ID=\n\n# Cloudflare Turnstile site key from step 3\nCLOUDFLARE_TURNSTILE_SITE_KEY=\n```\n\n- Copy the `.env.docker` file in the `api` directory into `.env`\n\n```bash\ncp api/.env.docker api/.env\n```\n\n- Update the environment variables in the `.env` file in the `api` directory with your firebase service account credentials, SMTP server details, and Cloudflare Turnstile secret key.\n\n```dotenv\n# SMTP email server settings\nSMTP_USERNAME=\nSMTP_PASSWORD=\nSMTP_HOST=\nSMTP_PORT=\n\n# Firebase service account credentials\nFIREBASE_CREDENTIALS=\n\n# This is the `projectId` from your firebase web config\nGCP_PROJECT_ID=\n\n# Cloudflare Turnstile secret key from step 3\nCLOUDFLARE_TURNSTILE_SECRET_KEY=\n```\n\n- Don't bother about the `EVENTS_QUEUE_USER_API_KEY` and `EVENTS_QUEUE_USER_ID` settings. We will set that up later.\n\n### 6. Build and Run\n\n- 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.\n  When it's finished, you'll be able to access the web UI at http://localhost:3000 and the API at http://localhost:8000\n\n```bash\ndocker compose up --build\n```\n\n### 7. Create the System User\n\n- 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.\n\n  ```SQL\n  INSERT INTO users (id, api_key, email ) VALUES ('your-system-user-id', 'your-system-api-key', 'system@domain.com');\n  ```\n\n\u003e [!IMPORTANT]\n\u003e Restart your API docker container after modifying `EVENTS_QUEUE_USER_ID`, and `EVENTS_QUEUE_USER_API_KEY` in your `.env` file so that the httpSMS API can pick up the changes.\n\n### 8. Build the Android App.\n\n- Before building the Android app in [Android Studio](https://developer.android.com/studio), you need to replace the `google-services.json` file in the `android/app` directory with the file which you got from step 1. You need to do this for the firebase FCM messages to work properly.\n\n## License\n\nThis project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE Version 3 - see the [LICENSE](LICENSE) file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndolestudio%2Fhttpsms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fndolestudio%2Fhttpsms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndolestudio%2Fhttpsms/lists"}