crans
/
documentation
mirror of https://gitlab.crans.org/nounous/documentation.git
19
0
Fork 0
Code Issues Projects Releases Wiki Activity

Linting une fois

merge-requests/22/merge
glevy 2025-06-28 19:28:39 +02:00 committed by bleizi
parent fac72e5eca
commit 0822e5fd43
1 changed files with 58 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
howto/mail_all.md
View File

@ -1,18 +1,19 @@
# Envoyer un mail à tous les adhérents # Envoyer un mail à tous les adhérents
:warning: Avant de lire ce qui suit, vérifie auprès de plusieurs personnes, en :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. 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 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, et aussi afin de t'épargner l'envoi manuel de centaines de mails
des anciens membres du Crans ont écrit un script pour envoyer des mails à tous les adhérents. 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`). 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 Ce script utilise le moteur de templates Jinja pour personnaliser les mails
et nécessite une instance de Re2o. et nécessite une instance de Re2o.
Pour le faire fonctionner, c'est assez simple. Pour le faire fonctionner, c'est assez simple.
Tout d'abord, allons lire le menu d'aide. Tout d'abord, allons lire le menu d'aide.
@ -46,44 +47,51 @@ Filtres:
-A, --alladh Envoie un mail à tous les adhérents. -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. 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`. 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 : Comme le précise le menu d'aide, trois formats sont disponibles. Par exemple :
``` ```
Prénom;Nom;<pseudo>@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. Tu peux aussi préciser des paramètres supplémentaires qui
Il te suffit de rajouter un JSON contenant dans ses clés les nouvelles variables, cf l'exemple ci-dessous. 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.
``` ```
Prénom;Nom;<pseudo>@crans.org;{"pseudo":"<pseudo>","humeur":"bonne"} 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. Les variables supplémentaires "pseudo" et "humeur" seront disponibles
Cas d'usage : on peut de cette manière indiquer le pseudo dans le sujet du mail, utile pour trier les bounces. 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`,
Ce format permet de récupérer le prénom dans la variable `Prénom`, le nom dans `Nom` et l'email dans `To`. le nom dans `Nom` et l'email dans `To`.
Ces variables sont utilisables dans le remplissage du template. 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, Si un autre format est utilisé qui ne permet pas de récupérer le nom
mais que l'email est bien accessible, le script fonctionnera quand même. Attention tout de même à avoir un mail cohérent. 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. 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`. Soit tu récupères toi même cette liste et la colle dans un fichier de destinataires,
De même tu peux envoyer un mail à tous les adhérents à jour de cotisation avec l'option `-a`. 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. 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 : L'architecture d'un dossier template ressemble à ça :
``` ```
Dossier_Template Dossier_Template
@ -101,51 +109,58 @@ Dossier_Template
``` ```
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`. 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. Tous les fichiers sont des templates Jinja
* `Prénom` : Le prénom du destinataire, ou la chaîne vide. 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.
* Toute autre variable que tu aurais envie de définir. * `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étails sur ce dossier de templates. 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). * `body` est le dossier le plus important. C'est lui le coeur du mail.
Tu n'es pas obligé d'avoir un mail en Anglais, il suffit tout simplement de ne pas mettre le fichier `en`. Il contient deux fichiers `en` et `fr`, qui vont chacun former une version du mail
Ce sont là aussi des template Jinja, personalisables à l'aide des variables susmentionnées. (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 ## 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_2026` 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,
crée un dossier `AGO_2026` avec l'architecture précédente, dans le dossier `template`.
Puis lance le script avec les options suivantes.
``` ```
./mail_all.py -s 'bureau@crans.org' -A -t AGO_2020 -p ./mail_all.py -s 'bureau@crans.org' -A -t AGO_2020 -p
``` ```
* 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 `-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'envoi 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).
:warning: :warning:
Les consignes sont répétées pour une bonne raison. 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. 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 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. (à commencer par toi) pour vérifier que le mail rend bien.
:warning: :warning:
Lance le script dans un screen pour que son exécution se passe bien jusqu'au bout. 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 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. 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é
Une fois que le mail est satisfaisant et que tu as bien vérifié la liste des destinaires concernés la liste des destinataires concernés
(tous ceux que tu visais, seulement eux), tu peux utiliser l'option `--doit`. (tous ceux que tu visais, seulement eux), tu peux utiliser l'option `--doit`.
``` ```