Configuration des e-mails

Fonctionnement de la file d'attente

Paheko utilise une file d'attente pour envoyer les e-mails, sauf les e-mails "système" (rappel de mot de passe, notification de changement d'identifiant, etc.).

Cela veut dire qu'un message n'est pas envoyé immédiatement, mais est d'abord ajouté dans une liste de messages à envoyer.

Ensuite l'envoi réel est effectué soit :

toutes les minutes, si vous avez activé le cron (voir configuration du cron)
à la fin de l'ajout à la file d'attente sinon. Dans ce cas si l'envoi est long, une erreur peut se produire (dépassement du temps autorisé d'exécution). Dans ce cas il faudra relancer l'envoi (voir ci-dessous).

Dépassement du temps d'exécution en cas d'envoi à plusieurs centaines/milliers de destinataires

Si vous n'utilisez pas l'envoi par cron et quune erreur se produit indiquant que le temps d'exécution du script a été dépassé (par exemple "Maximum execution time of 30 seconds exceeded"), alors il faudra reprendre l'envoi dans le menu Messages collectifs, onglet Adresses rejetées. Et dans ce cas il est préférable d'activer l'utilisation du cron, comme décrit ci-dessus.

Configuration du serveur d'envoi SMTP

Par défaut, les e-mails sont envoyés avec la fonction mail() de PHP, qui envoie des mails sur le serveur local. Si celle-ci n'est pas disponible ou que vous voulez utiliser un autre serveur, il faut alors configurer les constantes SMTP_* pour passer par un serveur SMTP externe. Consultez config.dist.php pour les détails.

const SMTP_HOST = 'mail.monhebergeur.org';
const SMTP_PORT = 587;
const SMTP_USER = 'paheko@monserveur.com';
const SMTP_PASSWORD = 'abcd';
const SMTP_SECURITY = 'TLS';
const SMTP_HELO_HOSTNAME = 'paheko.monserveur.com';
const MAIL_RETURN_PATH = 'bounces@monserveur.com';

Adresse e-mail d'expéditeur

Par défaut Paheko utilise l'adresse de l'association comme expéditeur (From) des messages envoyés.

Si vous envoyez des mails pour plusieurs associations, il est souhaitable de forcer l'adresse d'expéditeur des messages pour une adresse locale, ceci pour passer les règles SPF et DKIM des serveurs destinataires.

C'est possible en utilisant les constantes MAIL_SENDER et MAIL_RETURN_PATH :

const MAIL_SENDER = 'associations@monserveur.com';
const MAIL_RETURN_PATH = 'retours@monserveur.com';

La constante MAIL_SENDER définit l'adresse qui sera utilisée dans le From, à la place de l'adresse de l'association, qui elle sera placée dans l'entête Reply-To.

La constante MAIL_RETURN_PATH définit l'adresse d'enveloppe ("Envelope from", correspondant à la commande SMTP MAIL FROM), qui sera utilisée pour recevoir les erreurs de livraison de messages (bounces) via l'entête Return-Path. Le message expédié correspondra à ceci :

From: "Nom Association" <associations@monserveur.com>
Reply-To: <nom-association@zaclys.net>
Return-Path: <retours@monserveur.com>

Il est conseillé de votre côté de mettre en place une redirection de l'adresse locale associations@monserveur.com vers celle de l'association. Et de configurer l'adresse de retours pour traiter les retours (voir ci-dessous).

Il faut que l'adresse Return-Path soit également valide au niveau SPF/DKIM de votre côté.

E-mails de retour (bounces)

Pour savoir si une adresse e-mail est invalide, parfois il faut attendre que le serveur SMTP destinataire vous réponde en vous renvoyant un message d'erreur. Paheko sait reconnaître et interpréter automatiquement ces messages d'erreur.

Pour cela il est possible de configurer une adresse Return-Path dans le fichier config.local.php (constante MAIL_RETURN_PATH).

Pour que les messages envoyés à cette adresse soient renvoyés à Paheko il existe trois méthodes différentes, voir ci-dessous pour les détails.

Si Paheko identifie un motif de retour dans le message de bounce reçu, l'adresse e-mail sera notée comme invalide ou en erreur temporaire. Les messages de réponse automatisée (répondeur) sont ignorés par convenance. Sinon, si Paheko ne parvient pas à identifier le type de message, le message est transmis (forwardé) à l'adresse e-mail de l'association.

Avec le webhook

Vous pouvez utiliser un webhook, par exemple si vous avez un fournisseur de mail qui permet de recevoir les bounces sous la forme de webhook. Ou si vous pouvez configurer votre serveur mail pour appeler une URL HTTP en cas de bounce.

Pour cela il faut envoyer une requête HTTP de type POST à l'adresse http://bounce:MOTDEPASSE@.../admin/handle_bounce.php, avec le contenu complet du message de bounce dans le champ message.

Avec curl cela donnerait par exemple :

curl -F 'message=@/tmp/message.eml' https://bounce:abcd@monasso.com/admin/handle_bounce.php

Le mot de passe est définit dans config.local.php dans la constante MAIL_BOUNCE_PASSWORD.

Avec un script en ligne de commande

Il existe la commande bin/paheko queue bounce qui peut recevoir en STDIN le message entier (avec entêtes).

Il faut configurer votre MTA pour qu'il renvoie les messages à ce script.

Exemple avec Exim4

Exemple de configuration Exim pour une adresse bounces@monasso.example.tld :

narragoon_script_router:
  driver = accept
  domains = "monasso.example.tld"
  verify_sender = false
  transport = paheko_script_transport
  local_parts = "bounces"
…

paheko_script_transport:
  driver = pipe
  command = php /var/www/paheko/bin/paheko queue bounce
  user = paheko
  group = paheko
  current_directory = /var/www/paheko
  home_directory = /var/www/paheko
  log_fail_output
  log_defer_output
  timeout = 60s

Avec une boîte mail indépendante en POP3 et un script

Si vous ne gérez pas votre propre serveur de mail, c'est la solution la plus simple. Il faut créer une boîte mail de type POP3 chez n'importe quel fournisseur et d'utiliser curl pour lire les messages en POP3 et les transmettre à Paheko.

Exemple de script :

#!/bin/sh

set -euo pipefail

SERVER="pop3s://mail.monasso.lautre.net/"
LOGIN="returns@monasso.lautre.net"
PASSWORD="motdepasse42"

# Récupérer l'ID du dernier mail de la boîte mail
LAST_ID=$(curl -s -u $LOGIN:$PASSWORD ${SERVER} | tail -n1 | awk '{print $1}')

if [ "$LAST_ID" = "" ] then
    echo "Cannot fetch last email ID"
    exit 1
fi

# Récupérer le contenu du mail et le transmettre au script
curl -s -u $LOGIN:$PASSWORD ${SERVER}/${LAST_ID} | php /var/www/paheko/bin/paheko queue bounce

# Supprimer le dernier mail
curl --head --request DELE -s -u $LOGIN:$PASSWORD ${SERVER}/${LAST_ID}

Ce script est à placer en cron, par exemple quelques fois par jour.