About sms-handler

sms-handler is a simple companion service of the SMS Forward app (available on FDroid) designed to send notification mails on reception of SMSes.

It is written in Python with FastAPI and BSD licensed.

For a more flexible way to use SMS Forward, it can be used with the ntfy pub/sub service, making it easy to integrate with other tools, for notification on various devices and automation.

Installation

PIP_EXTRA_INDEX_URL=https://pypi.org/simple/ pip install --index-url https://philo.ydns.eu/code/api/packages/Philome/pypi/simple/ sms-handler

Debian and other systems require using pipx pip:

sudo apt install -y pipx
PIP_EXTRA_INDEX_URL=https://pypi.org/simple/ pipx install --index-url https://philo.ydns.eu/code/api/packages/Philome/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_START_TLS: initiate mail server connection with TLS (default: no)
• SMS_HANDLER_MAIL_TEMLATE: 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.

SMS handler app configuration

Set the Webhook URL with as https://your.server.name:8025/sms-handle.

Note: the URI path /sms-handle is not configurable.

Run

In foreground

sms-handler

Set port and listen address:

sms-handler --port 80125 --host 192.168.100.55

As a daemon (Systemd)

Create a service as follows. Pass the settings for the web server (listen address, port) in the ExecStart statement, and the parameters as Environment=SMS_HANDLER_MAIL_SERVER_START_TLS=yes.

[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 behind a reverse proxy

sms-handler can run behind a reverse proxy (Nginx, Apache, etc) for HTTPs support. The URI (configured in the SMS Forward app) can be prefixed to dispatch different applications on the same server.

Example for Caddy:

handle /sms-handler/* {
    uri strip_prefix /sms-handler
    reverse_proxy 192.168.100.2:8025
}

Development and test

sms-handler is packaged with uv.

Download source code, create a Python virtual environment, install dependencies and run the tests:

git clone https://philo.ydns.eu/code/Philome/sms-handler.git
cd sms-handler
uv venv
uv sync
. .venv/bin/activate
pytest -s tests/basic.py