About sms-handler

sms-handler is a simple companion service of the SMS to URL Forwarder app available on F-Droid, 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://code.philo.ydns.eu/api/packages/philorg/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://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

pip upgrade sms-handler

or:

pipx upgrade 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_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.

The SMS_HANDLER_MAIL_TEMPLATE variable is used with Python str.format(). The field names are the same as the default JSON setting in the SMS to URL Forwarder app.

The default setting formats emails as below:

{text}
---
From: {from} {fromName}
Sent: {sentStamp:%c}
Received: {receivedStamp:%c}
Sim: {sim}

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 below, adapt the email addresses (snoopy@peanuts.com in this example).

Settings for the web server (listen address and port) are given in the ExecStart statement. Other parameters are given as environment variables (see above).

[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 is suggested as it is straightforward to set up, with this Caddyfile extract:

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.

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://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.

Compatibility

sms-handler is also compatible with this fork of SMS to URL Forwarder 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 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.