About sms-handler

sms-handler is a simple companion service of the SMS Forward app 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

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 prefer using pipx instead of 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

The sms-handler source has a CI test workflow for Forgejo.

Alternatives

For a more flexible way to use SMS Forward (available on FDroid), use the ntfy pub/sub service. It makes it easy to integrate with other tools, for notification on various devices and automation.

License, etc

sms-handler is BSD licensed. Suggestions and contributions are welcome.