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 sms-handler
```

or:

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

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

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

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