Baguette
/
mailer
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

README: add some explanations.

master
Philippe Pittoli 2023-02-04 03:44:32 +01:00
parent a0ace685e2
commit aff4272baa
1 changed files with 49 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
README.md
View File

@ -1,24 +1,58 @@
# USAGE
# What
As all programs from `Baguette` repositories, a `-h` option is available for the program.
`mailer` is an application to send templated emails.
Templates are in the [Crinja format][crinja] (a Jinja derivative).
```Bash
# Get some help.
mailer -h
```
### Sending a mail
# Sending a mail
```Bash
# One-shot email transfer.
# One-shot email transfer. "login" and "token" are template parameters.
# mailer send <template> <email>
login=mypseudo token=aabbccdd mailer send activation-email test@example.com
FROM=no-reply@example.com \
SUBJECT="Activate your email" \
login=mypseudo \
token=aabbccdd \
mailer send activation-email user@home.com
```
### Configuration
By default, configuration is:
As all programs from `Baguette` repositories, a configuration file either in the `$XDG_CONFIG_HOME/baguette/` (first guess) or in the `/etc/baguette/` directory can be used.
- smtp deamon host is '127.0.0.1', port 25
- template directory is `/etc/mailer/templates/`
- FROM and SUBJECT (mail object) are retrieved from environment variables
Here an exhaustive example:
So, in the previous example, without any configuration, the template *activation-email* refers to the file `/etc/mailer/templates/activation-email.j2` (the `j2` extension is for Jinja).
The `/etc/mailer/templates/activation-email.j2` template could look like this:
```
Hello and welcome to example.com!
To activate your account, please follow the link bellow:
https://example.com/user-activation/{{ login }}/{{ token }}
Thanks for trusting us!
Have a good day,
--
Staff of example.com.
```
# Configuration
As most programs from `Baguette` repositories, a configuration file can be used.
The configuration file should be either in `$XDG_CONFIG_HOME/baguette/` (first guess) or in `/etc/baguette/`.
In `mailer`, this file is used to configure:
- how to contact the smtp deamon (host and port)
- what directory should be used for templates
- *FROM* and *SUBJECT* email fields
An exhaustive example:
```YAML
# ~/.config/baguette/mailer.yml
@ -27,24 +61,21 @@ Here an exhaustive example:
smtpd_host: localhost
smtpd_port: 25
# Where to find templates, if not in the defaut directory (/etc/baguette/mailer/templates/).
templates_directory: /path/to/mailer/templates
# Where to find templates, if not in the defaut directory (/etc/mailer/templates/).
templates_directory: /etc/mailer/templates
# Configuration for each template.
templates:
# Template name, associated to the mail configuration: "from" and "subject" headers.
mail-activation-fr:
# Template names match the template file name in the template directory.
# In this example, the following template file is:
# /etc/mailer/templates/example.com-mail-activation-en.j2
example.com-mail-activation-en:
from: no-reply@example.com
subject: Account activation on the example.com website
mail-recovery-fr:
example.com-mail-recovery-en:
from: no-reply@example.com
subject: Mail recovery for the example.com website
```
### Templates
Templates:
- are in the [Crinja format][crinja] (a Jinja derivative)
- located by default in `/etc/baguette/mailer/templates`
[crinja]: https://github.com/straight-shoota/crinja