sms-handler/README.md

# About sms-handler

[sms-handler](https://philo.ydns.eu/code/Philome/sms-handler) is a simple companion service of the
[SMS Forward](https://gitlab.com/pierreduchemin/smsforward) 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

```sh
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`:

```sh
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

```sh
sms-handler
```

Set port and listen address:

```sh
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`.

```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 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](https://caddyserver.com/):

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

## 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://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](https://forgejo.org/).

## Alternatives

For a more flexible way to use *SMS Forward*
(available on [FDroid](https://f-droid.org/packages/com.pierreduchemin.smsforward/)),
use the [ntfy](https://ntfy.sh/) 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.

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