sms-handler/README.md

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

<a href="https://liberapay.com/Philo/donate"><img alt="Donate using Liberapay" src="https://liberapay.com/assets/widgets/donate.svg"></a>