FAQ – Wanewsletter

Vous pouvez utiliser pour cela le script options/extra.php. Insérez simplement cette ligne de code à l’endroit où vous voulez afficher le nombre d’inscrits (prenez soin de mettre la bonne adresse vers le fichier extra.php) :

<script type="text/javascript" src="http://www.yourdomaine.com/rep/options/extra.php?liste=[ID]"></script>

Vous devez remplacer [ID] par le numéro identifiant de la liste de diffusion dont vous voulez afficher le nombre d’inscrits. Vous pouvez également indiquer plusieurs identifiants de liste en les séparant par un signe plus.

Le nombre d’inscrits sera affiché tel quel (appel à document.write()).

Alternativement, vous pouvez indiquer le nom d’une variable destinée à recevoir l’information. Pour cela, ajoutez par exemple &use-variable=myObject.myVariable dans l’URL d’appel. Le script renverra alors le code Javascript myObject.myVariable = X;.

Troisième solution, faites un appel AJAX sur le script extra.php en ajoutant &output=json dans l’URL d’appel. Le script renvoie alors {"numSubscribe":"X"}.

À partir de la version 2.4-beta2, le script peut vérifier si une mise à jour est disponible. Un lien "Vérifier les mises à jour" est présent sur la page d’accueil.

Un utilitaire d’importation d’emails est disponible dans la rubrique "outils" de Wanewsletter. Il vous permettra, si vous avez les droits suffisants, d’importer des emails directement via un champ texte, en spécifiant l’adresse du fichier sur le serveur, ou via l’upload d’un fichier contenant les emails, si votre hébergeur autorise l’upload de fichiers.

L’utilitaire accepte également les fichiers au format XML tels que générés par l’outil d’exportation. Un tel fichier a la structure suivante :

<?xml version="1.0"?>
<!-- Date : [la date] GMT - Format : [le format] -->
<Wanliste>
	<email>address1@example.tld</email>
	<email>address2@example.tld</email>
	<email>…</email>
</Wanliste>

L’utilitaire d’importation peut importer jusqu’à 10000 emails en une opération. Si vous souhaitez importer un plus gros volume d’emails sans avoir à réaliser l’opération en plusieurs fois, vous pouvez modifier la valeur de la constante MAX_IMPORT dans le fichier includes/constantes.php mais ce n’est pas recommandé si vous êtes en hébergement mutualisé ou que vous utilisez SQLite.

Le script contrib/wanewsletter, dédié à une utilisation en ligne de commande, permet également de réaliser des importations d’emails. Les limitations de durée des scripts php dans le cadre d’un serveur web ne s’appliquent pas dans ce cas.

Les adresses emails sont vérifiées syntaxiquement et les doublons sont éliminés. Si des emails sont refusés, le script génèrera un rapport dans le répertoire data/tmp/ du script et vous proposera également de le visualiser.

Wanewsletter peut être géré par plusieurs utilisateurs. Vous pouvez modifier les permissions des utilisateurs via le profil de l’utilisateur en question.

Il y a deux niveaux généraux : administrateur et utilisateur. Les administateurs ont automatiquement tous les droits, quelques que soient les réglages sur les droits individuels. Un utilisateur pourra faire tout ce qui lui aura été permis (voir, editer, supprimer, envoyer des newsletter, importer, exporter, bannir, et joindre des fichiers) et ce, pour chaque liste.

Pour ajouter un utilisateur, rendez-vous dans la section "Utilisateurs" puis "ajouter un utilisateur"

Vous disposez d’un formulaire par défaut, le fichier subscribe.php. Ce fichier affiche un formulaire classique, et une liste de sélection affichant les noms de toutes les listes de diffusion publiques créées.

Le script dispose également d’un générateur de formulaire dans la section "outils". Celui-ci vous permettra, pour une liste donnée, de générer le formulaire adéquat. Il ne vous restera qu’à placer ce formulaire où vous voulez sur le site, de placer le code d’inclusion de newsletter.php (code également fourni par le form. generator) et d’indiquer dans les réglages de la liste de diffusion en question l’adresse de traitement formulaire (en principe, la même que celle de l’attribut action de la balise form).

Notez que vous pouvez ajouter la variable $textCharset dans le code PHP d’inclusion de newsletter.php. Cela influera sur le codage de caractères du message de réponse renvoyé par newsletter.php.

Une dernière solution (disponible à partir de la version 2.2.0) consiste pour le visiteur à envoyer un email à l’adresse email d’une liste, avec comme sujet de l’email "Inscription" (insensible à la casse). Dans ce cas, vous devez avoir accès à cron (serveurs unix et équivalents) ou faire appel aux services gratuits de webcron.org pour automatiser l’appel au fichier cron.php qui se trouve dans le répertoire options/ du script. Ce script se chargera d’effectuer les tâches nécessaires (inscription, désinscription, changement de format, confirmation d’inscription..) selon les emails reçus.

Pour une désinscription, l’abonné devra envoyer un email avec pour sujet "Desinscription", il recevra alors un email lui demandant de renvoyer un autre email avec le meme sujet, et le code de son compte, qui lui aura été fourni (par sécurité). Pour la confirmation d’inscription (si la liste le demande), ce devra être un email avec pour sujet "confirmation", et pour le changement de format, le sujet devra être "setformat".

Si plusieurs de vos listes de diffusion utilisent la même adresse email, il risque d’y avoir conflit, le script ne sachant pas à quelle liste seront adressés les emails du compte POP. Dans ce cas, il vous faudra créer un alias de l’adresse en question avec le panneau de gestion de votre hébergement, si vous en avez la possibilité. Exemple :

Vous avez deux listes utilisant l’adresse email mailing@domaine.com. Il vous faudra créer deux alias renvoyant sur mailing@domaine.com et indiquer ces alias dans les réglages des listes concernées. Par exemple : mailing-1@domaine.com et mailing-2@domaine.com

Une alternative aux alias est d'utiliser le signe plus dans vos adresses email utilisées comme alias, si votre hébergeur le permet. Par exemple : mailing+liste1@domain.tld et mailing+liste2@domain.tld permettent de recevoir des emails sur la boîte mailing@domain.tld.
L’avantage est de ne pas avoir d’alias à créer. Ça marche tout de suite.

Dans le cas de l’option "cron", vous devrez indiquer les paramètres d’accès au compte POP de l’adresse email de la liste en question, et indiquer l’utilisation de l’option "cron" avec le bouton radio adéquat (section "listes" de l’administration).

Enfin, cron devra appeller une adresse de ce type :
http://www.yourdomain.com/rep/newsletter/options/cron.php?mode=validate&liste=[ID_de_la_liste]

Wanewsletter dispose de deux méthodes d’envoi pour pouvoir être utilisé par le plus grand nombre. En effet, certains hébergeurs limitent le nombre d’emails envoyés par jour, ou n’acceptent qu’un destinataire par email.

Il est recommandé d’utiliser la méthode d’envoi par défaut, c’est à dire l’envoi d’un email à chaque abonné.

Le répertoire data/ sert à stocker toute sorte de données utilisées par Wanewsletter :

• Données transitoires dans data/tmp
• Les fichiers joints dans data/uploads
• Les bases SQLite, par défaut dans data/db, si Wanewsletter est utilisé avec ce type de base de données
• Le journal d’erreurs dans data/logs lorsque activé
• Les fichiers config.inc.php et, éventuellement, tags.inc.php, ainsi que leurs modèles *.sample.php à la racine de data/

Aucune donnée présente dans le répertoire data/ n’a vocation à être accédé au travers du serveur HTTP. Il est donc important (et carrément critique si vous utilisez une base SQLite) de restreindre l’accès à ce répertoire.

Des fichiers index.html sont présents pour empêcher un éventuel listage automatique du contenu de ces répertoires, et un fichier .htaccess est présent à la racine du répertoire data/ avec la directive Deny from all. Pour les serveurs HTTP autres qu’Apache, je vous invite à consulter leur documentation pour protéger efficacement le répertoire data/.

De plus, les sous-répertoires tmp/, logs/ et stats/ peuvent être renommés ou déplacés. Il faut simplement définir les entrées correspondantes 'tmp_dir', 'logs_dir' et 'stats_dir' du tableau $nl_config dans le fichier de configuration data/config.inc.php. Consultez le modèle de fichier de configuration data/config.sample.inc.php pour l’exemple.

Quant aux bases de données SQLite, Wanewsletter n’en utilise qu’une et c’est vous qui la définissez à l’installation. L’emplacement par défaut qui vous est proposé est data/db/wanewsletter.sqlite, mais rien ne vous empêche de changer ce chemin par un autre, pointant en dehors du document root de votre site.

Enfin, le sous-répertoire uploads peut être redéfini via la page de configuration dans l’administration du script.

Dans le cas où l’upload de fichier est autorisé sur votre serveur, cela peut être dù au fait que le script n’a pas les droits en écriture sur le répertoire de stockage des fichiers joints. Vérifiez donc le chmod ou les attributs de ce répertoire.

Si l’upload n’est pas autorisé, le script n’ajoute le fichier à la liste des fichiers joints que si celui ci est déja présent sur le serveur, dans le répertoire de stockage des fichiers joints. Uploadez vos fichiers joints avec votre client FTP avant d’ajouter vos fichiers joints via le formulaire.

Pour que vos lettres aient plus de chance de parvenir dans la boîte de réception de vos destinataires, vous devez vous assurer de plusieurs points comme : ne pas apparaître dans des listes noires, émettre des lettres HTML de bonne qualité (ratio texte/images, doctype, voire balise <title>, ...), et d’autres règles de base.

Il existe sur Internet énormément d’articles sur le sujet, donc vous devriez en trouver sans peine. Je voudrais juste mentionner un outil que j’ai trouvé personnellement très bien fait : mail-tester.com.

Pour faire le test, il vous suffit de préparer une nouvelle lettre dans l’interface de Wanewsletter puis, quand elle est prête, vous rendre sur le site mail-tester.com, copier l’adresse email qui vous est proposée et la coller dans le champ "Faire un test d’envoi" de la page envoi de Wanewsletter. Une fois que l’email de test a été envoyé, il ne vous reste qu’à retourner sur la page de mail-tester.com et vérifier votre score.

Wanewsletter peut signer les emails sortants en utilisant la norme DKIM. Pour plus d’informations sur cette norme, consultez le lien suivant : http://www.dkim.org/

En pré-requis, vous devez avoir créé votre paire de clés et déclaré votre clé publique dans votre zone DNS.

Vous devez ensuite ajouter quelques entrées de configuration dans votre fichier data/config.inc.php (un exemple est aussi disponible dans le fichier data/config.sample.inc.php) :

$nl_config['mailer']['dkim']['selector'] = 'le_selecteur';
$nl_config['mailer']['dkim']['domain']   = 'votre_domaine';
$nl_config['mailer']['dkim']['privkey']  = '/chemin/vers/la/clé.key';

L’entrée 'privkey' accepte aussi directement la clé au format PEM. Si la clé est protégée par un passphrase, vous devez spécifier ce dernier avec l’entrée $nl_config['mailer']['dkim']['passphrase'].

D’autres options de configuration pour le module DKIM de Wamailer sont disponibles. Consultez la documentation de ce dernier (fichier vendor/wascripts/wamailer/lib/Tools/README.dkim.md).

Wanewsletter peut dialoguer directement avec un serveur SMTP pour envoyer vos emails, plutôt que d’utiliser la fonction mail() de PHP.

Cela devient particulièrement avantageux si votre serveur tourne sur Windows. En effet, dans ce cas, la fonction mail() ouvre une connexion réseau vers le serveur SMTP indiqué dans la configuration de PHP. Le problème est qu’elle ouvre et ferme une connexion à chaque appel, ce qui n’est évidemment pas du tout optimal lorsqu’il s’agit d’envoyer plusieurs emails à la chaîne !

Wamailer, la librairie de formatage et d’envoi d’emails, supporte les méthodes d’authentification SASL 'CRAM-MD5', 'PLAIN' et 'LOGIN'. D’autres méthodes seront peut-être supportées dans l’avenir.

Le protocole de sécurisation TLS est aussi supporté (sous réserve que l’extension PHP OpenSSL soit présente), et il est bien sûr recommandé de l’utiliser.

Notez qu’en cas d’utilisation de TLS, des ajustements peuvent être nécessaires pour accepter le certificat présenté par le serveur SMTP. Par exemple, si c’est un certificat auto-signé, il vous faudra autoriser spécifiquement ce type de certificat dans le fichier de configuration :

$nl_config['mailer']['ssl']['allow_self_signed'] = true;

Comme précisé dans le fichier data/config.sample.inc.php, le tableau 'ssl' accepte toutes les entrées décrites dans la documentation PHP sur les contextes de flux SSL : https://www.php.net/manual/en/context.ssl.php.

Le script donne la possibilité de réaliser vos envois de newsletters avec cron.
C’est très simple, il suffit d’appeler l’adresse suivante : http://www.yourdomaine.com/rep/options/cron.php?mode=send&liste=[ID]
Vous devez là aussi remplacer [ID] par l’identifiant de la liste concernée.

Pour faciliter les traitements automatisés, le script cron.php accepte aussi le paramètre output=json dans l’URL, lui indiquant de retourner une réponse dans ce format. Exemple de réponse :

{
	error: false,
	message: "La newsletter a été envoyé à X abonnés..."
}

À partir de Wanewsletter 2.3, un module utilisable en ligne de comande est disponible dans le répertoire contrib/. Vous devez donner les droits d’exécution sur le fichier contrib/wanewsletter (ou passer par l’exécutable PHP dans votre ligne de commande).

Voici la commande pour lancer un envoi pour une liste donnée :

$ /path/to/contrib/wanewsletter --process-send=1

Avec 1 l’identifiant de la liste concernée dans cet exemple.

Par défaut, le script enverra tous les emails en faisant une pause de 10 secondes tous les 30 emails pour éviter d’engorger le serveur de mail. Ces deux valeurs (10 et 30) sont modifiables en ligne de commande avec respectivement les paramètres --delay et --packet.

Si vous ne souhaitez pas envoyer tous les emails, vous pouvez utiliser le paramètre --limit pour indiquer le nombre d’emails maximum à envoyer.

Pour utiliser les tags personnalisés (à l’instar de {LINKS} ou {NAME}), copiez le fichier tags.sample.inc.php dans le répertoire data/ et renommez-le tags.inc.php. Ensuite, éditez-le. Vous devriez trouver ceci au début du fichier :

//$other_tags[$t]['column_name'] = '';
//$other_tags[$t]['field_name']  = '';
//$other_tags[$t]['tag_name']    = '';
//$t++;

Wanewsletter ne gère pas automatiquement les tags personnalisés. C’est à dire que c’est à vous de rajouter le champ voulu dans la table prefixe_abonnes, puis de spécifier le tag dans data/tags.inc.php pour que le script effectue le remplacement du tag par sa valeur lors de l’envoi.

Exemple :
Vous souhaitez pouvoir mettre un tag {ADDRESS} dans vos newsletters, lequel sera remplacé par l’adresse de l’abonné. Après avoir ajouté un champs nommé par exemple abo_address dans la table prefixe_abonnes, vous placerez les données du tag dans data/tags.inc.php (en ayant décommenté les lignes que j’ai données plus haut), comme ci dessous :

$other_tags[$t]['column_name'] = 'abo_address';
$other_tags[$t]['field_name']  = '';
$other_tags[$t]['tag_name']    = 'ADDRESS';
$t++;

Vous souhaitez maintenant ajouter un autre tag ? Reproduisez simplement la même opération.

Pour que vos abonnés puissent ajouter ces données dans leur profil, le panneau de gestion de profil doit être activé (voir configuration générale). Vous devez modifier le template editprofile_body.tpl présent dans le répertoire templates/ du script.
Ajoutez les champs text nécessaires en prenant soin de leur donner le nom de la colonne à laquelle ils se rapportent.
Exemple en se basant sur les tags des exemples précédents :

<table>
	<tr>
		<td><label>{L_EMAIL}&nbsp;:</label></td>
		<td>{EMAIL}</td>
	</tr>
	<tr>
		<td><label for="pseudo">{L_PSEUDO}&nbsp;:</label></td>
		<td><input type="text" id="pseudo" name="pseudo" value="{PSEUDO}" size="30" maxlength="30"></td>
	</tr>
	<tr>
		<td><label for="abo_address">Votre adresse&nbsp;:</label></td>
		<td><textarea id="abo_address" name="abo_address" rows="4" cols="50">{ADDRESS}</textarea></td>
	</tr>
	...
</table>

Il vous est possible d’ajouter des champs au formulaire d’inscription pour réceptionner des données et remplir vos champs personnalisés. Il suffit que ces champs portent le nom donné dans l‘entrée 'column_name', ou 'field_name' si vous souhaitez utiliser un nom différent de celui de la colonne dans la base de données.

Le script de traitement de l’inscription sauvegardera automatiquement ces données supplémentaires dans leur champ respectif.

Cette fonctionnalité était demandée par plusieurs utilisateurs de Wanewsletter.
Pour définir une langue à utiliser avec le formulaire (sous réserve que cette langue soit installée dans Wanewsletter), il vous suffit d’ajouter la ligne suivante dans le code d’inclusion de newsletter.php qui est fourni par le générateur de formulaire : $language = 'fr';

Additionellement, vous pouvez également définir l’adresse URL à utiliser pour forger le lien de confirmation d’inscription ou désinscription.
Voici un exemple de code PHP intégrant ces deux ajouts.

<?php
$language = 'en';
$formURL  = 'http://mydomain.tld/en/myform';

require 'path/to/newsletter.php';
?>

À partir de la version 2.3.0, Wanewsletter peut fonctionner avec les bases de données SQLite 3. Vérifiez cependant que votre installation de PHP comporte une des extensions sqlite existantes. Wanewsletter possède des couches d’abstraction pour fonctionner avec les extensions sqlite3 ou pdo + pdo_sqlite.

Vous devez vous assurer avant de débuter l’installation que le répertoire data/db/ de Wanewsletter lui est accessible en lecture ET en écriture. En effet, c’est dans ce répertoire que sera créé par défaut la base de données sqlite de Wanewsletter. Vous pouvez cependant définir le chemin d’installation de la base de données sqlite lors de l’installation.

Votre base de données sqlite peut être déplacée sans que cela pose de problème. Il faut simplement qu'elle soit accessible en écriture, de même que le répertoire qui la contient, et que la chaîne DSN dans le fichier de configuration de wanewsletter soit correctement renseignée.

Consultez le fichier readme du script.

Oui, c’est possible. Vous devez pour cela éditer le fichier admin/envoi.php et remplacer false par true au début du fichier :

const DISABLE_CHECK_LINKS = false;

N’oubliez pas que permettre aux abonnés à vos listes de se désinscrire simplement et rapidement si tel est leur souhait est une obligation légale (1).
Aussi, et sauf cas particuliers, vous ne devriez pas retirer ces liens des lettres que vous envoyez, et donc changer la valeur de cette constante.

(1) Au moins en France, en application de l’article 22 de la loi n° 2004-575 du 21 juin 2004 pour la confiance dans l’économie numérique (LCEN).

Vous les trouverez dans le répertoire languages/{code langue}/emails/.

Cette fonctionnalité a fait l’objet d’une forte demande par les utilisateurs de Wanewsletter et a donc été implémentée dans Wanewsletter 2.3.

Le chargement de modèles de newsletters par URL est très simple à utiliser. Indiquez simplement l’adresse du modèle au format texte et/ou celle du modèle au format HTML dans les champs correspondants lorsque vous êtes sur la page de chargement des newsletters (lien charger une newsletter dans la page d’envoi).

Le script rapatriera alors le contenu de chacune des URLs fournies et effectuera une conversion automatique vers l’UTF-8 si besoin.

Dans le cas d’un modèle au format HTML, Wanewsletter récupèrera le contenu d’un éventuel élément <title/> présent dans l’en-tête de la page et l’utilisera comme sujet du modèle. Une balise <base> sera également ajoutée dans l’en-tête du modèle pour assurer le bon fonctionnement des URLs relatives.

Rendez-vous sur la page de téléchargement de Wanewsletter. Le paquet de langue vous concernant y est peut-être disponible.

Consultez également le fichier readme du script.

Les modifications doivent être faites dans le fichier templates/subscribe_body.tpl.

Wanewsletter propose aussi l’utilisation de tags spéciaux dits tags d’inclusion. Le principe est d’indiquer une url ou un chemin de fichier, le contenu du fichier ciblé étant ajouté à la newsletter lorsque celle-ci est mise en attente d’envoi.

texte quelconque...

<?include src="/path/to/file"?>

fin de newsletter...

Ce mécanisme prend tout son sens par exemple lorsque l’URL indiquée cible un script serveur générant du contenu. Attention dans ce cas à utiliser une URL et non un chemin local, de manière à ce que le script cible soit bien exécuté par le serveur.

Si vous souhaitez que l’inclusion soit faite dès la sauvegarde suivante, utilisez l’attribut "now" avec "true" pour valeur :

texte quelconque...

<?include src="/path/to/file" now="true"?>

fin de newsletter...

Consultez l’entrée Utilisation de tags personnalisés de la FAQ.

Vous pouvez, si vous le souhaitez, ajouter une feuille de styles CSS personnalisée dans le dossier templates/ et nommée wanewsletter.custom.css. Elle sera prise en compte et appelée dans le bloc <head> du profil_cp.php, ainsi que dans celui de l’administration.