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 --index-url https://code.philo.ydns.eu/api/packages/philorg/pypi/simple sms-handler

or:

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. See for example here 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}
---
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).

[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.

In foreground

A service like sms-handler is designed to run as a background service (daemon).

However it is possible to run it manually:

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:

sms-handler --port 80125 --host 192.168.100.55

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.