documentation/howto/mail_all.md

# Envoyer un mail à tou·te·s les adhérent·e·s

> [!warning] Avant de lire ce qui suit, vérifie auprès de plusieurs personnes, en
> particulier auprès du CA et du ou de la présidence du Cr@ns
> que tu as _vraiment_ envie d'envoyer un `mail_all`.

Afin de contourner les mesures antispam du Crans pour cet usage légitime
et aussi afin de t'épargner l'envoi manuel de centaines de mails
tout en permettant de les personnaliser,
des anciens membres du Crans ont écrit un script pour
envoyer des mails à l'ensemble des adhérent·e·s.
On trouve le script (pour pouvoir l'exécuter) et les templates
sur la VM Re2o (`re2o.adm.crans.org`) dans `/usr/scripts/mail`.

Ce script utilise le moteur de templates Jinja pour personnaliser les mails
et nécessite une instance de Re2o.

Pour le faire fonctionner, c'est assez simple.
Tout d'abord, allons lire le menu d'aide.

```bash
---> ./mail_all.py --help
usage: mail_all.py [-h] [-t TEMPLATE] [-s SENDER] [--doit]
                   (-f RECIPIENTFILE | --to {adherent,access,club,everyone})

Mail all générique. Prend un template en argument.

optional arguments:
  -h, --help            show this help message and exit
  -t TEMPLATE, --template TEMPLATE
                        Un template de mail. Fournir le chemin du dossier
                        principal du mail.
  -s SENDER, --sender SENDER
                        Spécifier un expéditeur particulier. Par défaut
                        respbats@crans.org.
  --doit                Lance effectivement le mail.
  -f RECIPIENTFILE, --recipientfile RECIPIENTFILE
                        Un fichier contenant un destinataire par ligne au
                        format `Prenom;Nom;Email;Params`, avec params au
                        format json.
  --to {adherent,access,club,everyone}
                        Sélectionne les destinataires du mails parmi un filtre
                        prédéfini.
  -A, --alladh          Envoie un mail à tou·te·s les adhérent·e·s.

```

## Envoyer un mail à une liste prédéfinie

Tu peux envoyer un mail à une liste de destinataires précise.
Pour cela rien de plus simple, il te suffit de remplir les destinaires
dans un fichier, une ligne par destinataire et de le donner comme option à `-f`.
Comme le précise le menu d'aide, trois formats sont disponibles. Par exemple :

```bash
Prénom;Nom;<pseudo>@crans.org
```

Tu peux aussi préciser des paramètres supplémentaires qui
vont être fournis au template du mail.
Il te suffit de rajouter un JSON contenant dans ses clés
les nouvelles variables, cf l'exemple ci-dessous.

```bash
Prénom;Nom;<pseudo>@crans.org;{"pseudo":"<pseudo>","humeur":"bonne"}
```

Les variables supplémentaires "pseudo" et "humeur" seront disponibles
pour être utilisées dans le mail.
Cas d'usage : on peut de cette manière indiquer le pseudo
dans le sujet du mail, utile pour trier les bounces.

Ce format permet de récupérer le prénom dans la variable `Prénom`,
le nom dans `Nom` et l'email dans `To`.
Ces variables sont utilisables dans le remplissage du template,
en les insérant entre double accolades.
Par exemple, {{prenom}}.
Si un autre format est utilisé qui ne permet pas de récupérer le nom
ou le prénom du destinataire,
mais que l'email est bien accessible, le script fonctionnera quand même.
Attention tout de même à avoir un mail cohérent.

## Envoyer un mail général aux adhérent·e·s

Pour envoyer un mail à l'intégralité des adhérent·e·s
et ancien·ne·s adhérent·e·s,
utile si une coupure des services est prévue,
c'est très simple.
Soit tu récupères toi même cette liste et la colles
dans un fichier de destinataires,
soit tu utilises l'option `--to everyone`.
De même tu peux envoyer un mail aux adhérent·e·s à jour de cotisation
avec l'option `--to adherent`.

## Template de mail

Il est nécessaire de spécifier un template de mail,
via un chemin relatif au dossier courant.
L'architecture d'un dossier template ressemble à ceci.

```bash
Dossier_Template
├── body
│   ├── en
│   └── fr
├── From
│   └── fr
├── Subject
│   └── fr
├── To
│   └── fr
└── X-Mailer
└── fr
```

Dans le sous-dossier body, tu peux spécifier deux langues : `en` et `fr`.
Pour rajouter des langues, il faut changer un peu le script coeur, `mail.py`.
Tous les fichiers sont des templates Jinja
et ont accès aux variables définies dans `mail_all`.

* `Prénom` : Le prénom du ou de la destinataire (ou la chaîne vide).
* `Nom` : Le nom du ou de la destinataire (ou la chaîne vide).
* `To` : L'email du ou de la destinatire.
* `mailer` : L'user agent.
  Par défaut il vaut "Les membres du Crans
  ont personnalisé ce message pour toi"
* Toute autre variable que tu aurais envie de définir.

Voici un peu plus de détails
sur ce dossier de templates.

* A priori, `X-mailer` n'est pas à modifier
  et devrait juste
  contenir un fichier `fr` contenant `{{mailer}}`.
* De même, `To` ne devrait pas être modifié et contient `{{To}}`.
* `From` contient le champ `From` du mail à envoyer. Tu peux mettre ce que tu veux.
* `Subject/fr` est, comme son nom l'indique, le fichier définissant le sujet du mail.
  Il est aussi personnalisable à l'aide de variables
  comme tous les autres fichiers Jinja.
  Tu peux par exemple mettre le pseudo pour trier les bounces.
* `body` est le dossier le plus important
  C'est lui le coeur du mail. Il contient
  deux fichiers `en` et `fr`, qui
  vont chacun former une version du mail
  (en anglais, et en français respectivement).

Il n'est pas obligatoire d'avoir un mail en anglais,
il suffit tout simplement de ne pas mettre le fichier `en`.
Ce sont là aussi des template Jinja, personalisables
à l'aide des variables susmentionnées.

## Exemple

Pour envoyer un `mail_all` en vue
de la tenue de l'assemblée générale,
crée un dossier `AGO_$année` avec l'architecture précédente,
dans le dossier `template`.
Puis lance le script avec les options suivantes.

```bash
./mail_all.py -s 'bureau@crans.org' --to adherent -t AGO_$année
```

* L'option `-s` permet de préciser une adresse qui va
  recevoir les bounces.
  Tu veux ici une mailing list privée,
  comme `respbats` (par défaut) ou `bureau`.
* L'option `--to adherent` active l'envoi du mail à l'ensemble des adhérent·e·s
  à jour de cotisation.
* L'option `-t` est pour préciser le
  template du mail.
* Sans autre option, le script va
  permettre de simuler l'envoi des mails.

> [!warning]
> Les consignes sont répétées pour une bonne raison.
> Prends bien le temps de lire et de faire relire le mail
> avant qu'il ne parte.
> Vérifie, revérifie et fais re-revérifier la date, le jour,
> l'année et l'heure,
> aussi bien dans la version française qu'anglaise,
> dans le corps du mail comme dans son sujet.
> Il est fortement recommandé de l'envoyer d'abord à une liste
> restreinte de cobayes presque volontaires
> (à commencer par toi) pour vérifier que le mail rend bien.

> [!warning]
> Lance le script dans un `screen` ou un `tmux` pour qu'il s'exécute
> sans erreur jusqu'au bout.
> Le script va faire la petite centaine d'envois un par un,
> avec un délai de quelques secondes entre chaque envoi afin de
> ne pas être pris pour un serveur de spam.
> Au total, il faut prévoir plusieurs heures pour l'ensemble des envois,
> le risque d'interruption au milieu n'est donc jamais négligeable.

Une fois que le mail est satisfaisant et que tu as bien vérifié
la liste des destinataires concernés
(tous ceux que tu visais et seulement eux), tu peux utiliser l'option `--doit`.

```bash
./mail_all.py -s 'bureau@crans.org' --to adherent -t AGO_$annee --doit
```

Le `mail_all` part alors vivre sa vie de `mail_all`.

_Documentation très largement reprise de contributions du Wiki,_
_avec quelques mises à jour par bleizi._