tinysteady-mailer/README.md

# Tinysteady mailer

CLI tool to send mails (campaigns) to lists of addresses.

Mail campaigns are organized in yaml configuration yaml files,
and given in the environment variable `CONFIG`.

The intention is to be able to send mails using mail servers with time limitations
with all free accounts in standard mail services.
The tool keeps track of failures: a next run
with the same config file will process only the failures, so all recipients
will eventually be reached.

## Installation

`tinysteady-mailer` is provided as:

* a standard Python package
* a container

See the Packages section on the project's home page: <https://code.philo.ydns.eu/philorg/tinysteady-mailer>.

## Organisation and workflow

Create a yaml config file per mail campaign.
Some example (for different kind of mail servers) are given in the `configs` directory.

There are 2 sources of address:

* embedded in the config file
* with an external json file

Run `tinysteady-mailer` with:

```~~
CONFIG=configs/my-first-campaign.yaml tinysteady-mailer
```

For example, given the local.yaml config file:

```sh
CONFIG=configs/local.yaml tinysteady-mailer
INFO     - Using configs/local.yaml
INFO     - Mail sent to root@localhost.localdomain
INFO     - 1 mails sent successfully
```

A `results/<config_name>` directory is created, with 2 files named
with a timestamp: a `.success` and a `.err` files.

If some mails could not be delivered, the `.err` file contains
records (in json format) of the failures.

A subsequent run with the same config will process only those.
(that this can be overridden in the config file).

For example:

```sh
CONFIG=configs/local.yaml tinysteady-mailer
INFO     - Using configs/local.yaml
INFO     - Using a file with 1 failed attempts for this config (/home/phil/dev/tinysteady-mailer/results/local/2024-12-12 03:24:38.err)
INFO     - Mail sent to root@localhost.localdomain
INFO     - 1 mails sent successfully
```