# About sms-handler [sms-handler](https://code.philo.ydns.eu/philorg/sms-handler) is a simple companion service of the *SMS to URL Forwarder* app available on [F-Droid](https://f-droid.org/en/packages/tech.bogomolov.incomingsmsgateway/), to send notification mails on reception of SMSes. Main audience: people who run a server on the public internet, configured with an email server or configured as a relay. ## Installation ```sh PIP_EXTRA_INDEX_URL=https://pypi.org/simple/ pip install --index-url https://code.philo.ydns.eu/api/packages/philorg/pypi/simple/ sms-handler ``` Debian and other systems prefer using `pipx` instead of `pip`: ```sh sudo apt install -y pipx PIP_EXTRA_INDEX_URL=https://pypi.org/simple/ pipx install --index-url https://code.philo.ydns.eu/api/packages/philorg/pypi/simple/ sms-handler ``` *sms-handler* can be run with any unprivileged user. However due to standard security schemes, opening a port in the range 1-1024 is allowed to privileged users only (such as *root*). Use `sudo` to install as root if *sms-handler* is to be configured with a reserved port. ### Upgrade ```sh pip upgrade --index-url https://code.philo.ydns.eu/api/packages/philorg/pypi/simple sms-handler ``` or: ```sh pipx upgrade --index-url https://code.philo.ydns.eu/api/packages/philorg/pypi/simple sms-handler ``` ## Configuration Configuration is done by environment variables, prefixed by `SMS_HANDLER_`: * `SMS_HANDLER_MAIL_SENDER`: origin email address (default: *username*@localhost) * `SMS_HANDLER_MAIL_TO`: destination email address (default: *username*@localhost) * `SMS_HANDLER_MAIL_SERVER`: address of the mail server (default: localhost) * `SMS_HANDLER_MAIL_SERVER_PORT`: port of the mail server (default: 25) * `SMS_HANDLER_MAIL_SERVER_USERNAME`: username of the mail server (default: None) * `SMS_HANDLER_MAIL_SERVER_PASSWORD`: port of the mail server (default: None) * `SMS_HANDLER_MAIL_SERVER_START_TLS`: initiate mail server connection with TLS, eg. when using port 587 (default: no) * `SMS_HANDLER_MAIL_SERVER_USE_TLS`: use mail server connection TLS, eg when using prot 465 (default: no) * `SMS_HANDLER_MAIL_SUBJECT`: used to format the subject of the mails * `SMS_HANDLER_MAIL_TEMPLATE`: used to format the body of the mails * `SMS_HANDLER_MAIL_ENABLE`: no or false to disable mails (default: yes) The default settings work with a mail server runs on the localhost, and mails are sent to the user that owns the process. ### Templates The `SMS_HANDLER_MAIL_TEMPLATE` and `SMS_HANDLER_MAIL_SUBJECT` variable use the standard Python [string formatting](https://peps.python.org/pep-3101/). See for example [here](https://www.w3schools.com/python/python_string_formatting.asp) for simple examples. The field names are the same as the default JSON setting in the *SMS to URL Forwarder* app. Additionally, a `pretty_from` variable can be used in the templates, which combines the phone number of the sender with its name if found in the SMS record in the `fromName` field. The default setting formats emails as below: ```text {text} --- From: {pretty_from} Sent: {sentStamp:%c} Received: {receivedStamp:%c} Sim: {sim} ``` ### SMS handler app configuration Set the *Webhook URL* to `http://your.server.name:8025/handle-sms`. Adjust with the public name (`your.server.name`) and the port where the service is exposed. This corresponds to the `--port` option of `sms-handler`. See also the *Reverse proxy* note below. *Note*: the URI path `/handle-sms` is not configurable. ## Run ### As a daemon (Systemd) Create a service as below, adapt the email addresses (`snoopy@peanuts.com` in this example). Settings for the web server (listen address and port) can be given in the ExecStart statement if the default values need to be adapted. Other parameters are given as environment variables (see above). ```systemd [Unit] Description=SMS handler [Service] ExecStart=/home/snoopy/.local/bin/sms-handler Environment=SMS_HANDLER_MAIL_SENDER=snoopy@peanuts.com Environment=SMS_HANDLER_MAIL_TO=snoopy@peanuts.com Restart=on-failure [Install] WantedBy=default.target ``` ### Run in a container *Sms-handler* is also packaged as a container for running with *docker*, *podman*, or *Kunernetes*. See `CONTAINER.md` for the details. ## Run behind a reverse proxy *sms-handler* can run behind a reverse proxy (Nginx, Apache, Lighttpd, HAProxy, Caddy, Traefik, etc), eg. for HTTPs support. The URI (configured in the *SMS to URL Forwarder* app) can be prefixed to dispatch different applications on the same server. [Caddy](https://caddyserver.com/) is suggested as it is straightforward to set up, with this Caddyfile extract: ```text my.example.com { handle /sms-handler/* { uri strip_prefix /sms-handler reverse_proxy 127.0.0.1:8025 } } ``` Replace the public host name `my.example.com` and the destination IP:port `127.0.0.1:8025` for your setup. ### In foreground A service like `sms-handler` is designed to run as a background service (daemon). However it is possible to run it manually: ```sh sms-handler ``` Note that the default port is 8025, as it is not a restricted port so does not need privileged permissions, aka root/sudo. Set port and listen address: ```sh sms-handler --port 80125 --host 192.168.100.55 ``` ## Development and test *sms-handler* is packaged with [uv](https://docs.astral.sh/uv/). Download source code, create a Python virtual environment, install dependencies and run the tests: ```sh git clone https://code.philo.ydns.eu/philorg/sms-handler.git cd sms-handler uv venv uv sync . .venv/bin/activate # for bash. For fish: . .venv/bin/activate.fish pytest -s tests/basic.py ``` The *sms-handler* source includes a CI test workflow for [Forgejo](https://forgejo.org/). ## Compatibility *sms-handler* is also compatible with [this fork of *SMS to URL Forwarder*](https://github.com/scottmconway/android_income_sms_gateway_webhook) which includes also the sender's name. ## Alternatives For a more flexible way to use a tool like *SMS to URL Forwarder*, a pub/sub service like [ntfy](https://ntfy.sh/) should be considered. It makes it easy to integrate with other components for notification on various devices and automation. ## License, etc *sms-handler* is BSD licensed. Suggestions and contributions are welcome. Donate using Liberapay