Reprise de la doc du Wiki pour le mail_all.

howto/mail_all.md

@@ -1,18 +1,22 @@
-#acl +All:read
+# Envoyer un mail à tous les adhérents
-
-= Envoyer un mail à tous les adhérents =
-
-[!WARNING]
-Avant de lire ce qui suit, fais bien attention de vérifier auprès de plusieurs personnes, en particulier auprès du CA et du ou de la président.e du Cr@ns, que tu veux vraiment 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, on a écrit un script pour envoyer des mails à tous les adhérents : Il se trouve [[ https://gitlab.crans.org/nounous/scripts/-/blob/master/mail/mail_all.py | ici ]] (en principe cloné dans {{{/usr/scripts/mail}}}).
-
-Ce script utilise le moteur de templates Jinja pour personnaliser les mailse et nécessite une instance de Re2o.
 
 
-Pour le faire fonctionner, c'est assez simple. Tout d'abord, je t'invite à lire le menu d'aide
+: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 à tous les adhérents.
+Il se trouve [ici](https://gitlab.crans.org/nounous/scripts/-/blob/master/mail/mail_all.py) (en principe cloné 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.
+
+```
 ---> ./mail_all.py --help
 usage: mail_all.py [-h] [-f RECIPIENTFILE] [-t TEMPLATE] [-s SENDER] [-a] [-A]
                    (--doit | -p)
@@ -40,39 +44,48 @@ Filtres:
   -a, --allaccess       Envoie un mail à toutes les personnes bénéficiant
                         d'une connexion valide.
   -A, --alladh          Envoie un mail à tous les adhérents.
-}}}
+```
 
 
-== Envoyer un mail à une liste prédéfinie ==
+## 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 stipule le menu d'aide, trois formats sont disponibles. Par exemple : 
+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 :
 
-{{{
+```
-Maxime;Bombar;bombar@crans.org
+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 en clé la nouvelle variable. Par exemple :
+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.
 
-{{{
+```
-Maxime;Bombar;bombar@crans.org;{"pseudo":"bombar","humeur":"bonne"}
+Prénom;Nom;<pseudo>@crans.org;{"pseudo":"<pseudo>","humeur":"bonne"}
-}}}
+```
 
-Alors les variables supplémentaires "pseudo" et "humeur" seront disponibles pour être utilisées dans le mail (Comme par exemple pour stipuler le pseudo dans le sujet du mail, utile pour trier les bounces).
+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 Prenom, le nom dans Nom et l'email dans To. Ces variables sont utilisables dans le remplissage du template. 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.
+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.
+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 à tous les adhérents ==
+## Envoyer un mail à tous les adhérents
 
-Pour envoyer un mail à tous les adhérents c'est très simple. Soit tu récupères toi même cette liste et la colle dans un fichier de destinataires, soit tu utilises l'option {{{-A}}}. De même tu peux envoyer un mail à tous les adhérents à jour de cotisation avec l'option {{{-a}}}.
+Pour envoyer un mail à tous les adhérents c'est très simple.
+Soit tu récupères toi même cette liste et la colle dans un fichier de destinataires, soit tu utilises l'option `-A`.
+De même tu peux envoyer un mail à tous les adhérents à jour de cotisation avec l'option `-a`.
 
 
-== Template de mail ==
+## 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 à ça :
+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 à ça :
-{{{
+```
 Dossier_Template
 ├── body
 │   ├── en
@@ -84,48 +97,61 @@ Dossier_Template
 ├── To
 │   └── fr
 └── X-Mailer
-    └── fr
+└── fr
-}}}
+```
-
+Dans le sous-dossier body, tu peux spécifier deux langues : `en` et `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 :
+Pour rajouter des langues, il faut changer un peu le script coeur, `mail.py`.
- * Prenom --> Le prénom du destinataire, ou la chaîne vide.
+Tous les fichiers sont des templates Jinja, et ont accès aux variables définies dans mail_all.
- * Nom --> Le nom du destinataire, ou la chaîne vide.
+ * `Prénom` : Le prénom du destinataire, ou la chaîne vide.
- * To --> L'email du destinatire.
+ * `Nom` : Le nom du destinataire, ou la chaîne vide.
- * mailer --> L'user agent. Par défaut il vaut "Un MA du crans a personalisé ce message à la main pour toi"
+ * `To` : L'email du destinatire.
+ * `mailer` : L'user agent. Par défaut il vaut "Un MA du crans a personalisé ce message à la main pour toi"
  * Toute autre variable que tu aurais envie de définir.
 
-Voici un peu plus de détail sur ce dossier template :
+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}} }}}.
+ * 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}} }}}.
+ * 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.
+ * `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.
+ * `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.
- * ``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). Tu n'es pas obligé 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 sus-mentionnées.
+ * `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).
+Tu n'es pas obligé 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 ==
+## Exemple
 
-Pour envoyer un mail_all à tous les adhérents pour les prévenir de la tenue de l'assemblée générale, je crée un dossier {{{AGO_2020}}} avec l'architecture précédente, dans le dossier {{{template}}}. Puis je lance le script avec les options suivantes :
+Pour envoyer un mail_all à tous les adhérents pour les prévenir de la tenue de l'assemblée générale, je crée un dossier `AGO_2026` avec l'architecture précédente, dans le dossier `template`. Puis je lance le script avec les options suivantes :
 
-{{{
+```
 ./mail_all.py -s 'bureau@crans.org' -A -t AGO_2020 -p
-}}}
+```
 
- * L'option -s permet de préciser une addresse qui va recevoir les bounces. Tu veux ici une mailing list privée, comme respbats (par défaut) ou bureau.
+ * 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 -A permet de dire que je veux envoyer ce mail à tous les adhérents.
+ * L'option `-A` permet de dire que je veux envoyer ce mail à tous les adhérents.
- * L'option -t est pour préciser le template du mail.
+ * L'option `-t` est pour préciser le template du mail.
- * L'option -p me permet de faire une prévisualisation et de simuler l'envoi des mails. Cette option est de toute façon nécessaire (sauf si tu forces l'envoie du mail).
+ * L'option `-p` me permet de faire une prévisualisation et de simuler l'envoi des mails. Cette option est de toute façon nécessaire (sauf si tu forces l'envoi du mail).
 
-{{{#!wiki caution 
+:warning:
-Je ne fais que me répéter, mais c'est nécessaire. Prends bien le temps de lire et de faire relire le mail avant qu'il ne parte. Tu peux aussi tenter de te l'envoyer d'abord en te mettant seul dans la liste des destinataires pour vérifier que le mail rend bien.
+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.
+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.
 
-{{{#!wiki warning
-Lance le script dans un screen pour que son exécution se passe bien jusqu'au bout, il va faire tous les envois un par un pour le millier d'adhérents, et ça prend du temps !
-}}}
 
-Une fois que tu es satisfait.e de la tête de ton mail_all, et que tu es sûr.e que tu l'envoies bien à tous les destinaires concernés, et seulement à eux, tu peux utiliser l'option --doit :
+:warning:
+Lance le script dans un screen pour que son exécution se passe bien jusqu'au bout.
+Le script va faire tous les envois un par un pour le millier d'adhérents, c'est long
+et le risque d'interruption au milieu n'est pas négligeable.
 
-{{{
+
+Une fois que le mail est satisfaisant et que tu as bien vérifié la liste des destinaires concernés
+(tous ceux que tu visais, seulement eux), tu peux utiliser l'option `--doit`.
+
+```
 ./mail_all.py -s 'bureau@crans.org' -A -t AGO_2020 --doit
-}}}
+```
+
+Le mail_all part alors vivre sa vie de mail_all.
+
+_Documentation très largement reprise de contributions du Wiki._