Extension:BounceHandler
BounceHandler État de la version : stable |
|
---|---|
Implémentation | Accroche , Base de données |
Description | Permet aux utilisateurs de gérer les rebonds d'e-mails |
Auteur(s) |
|
Dernière version | 1.0 (Continuous updates) |
Politique de compatibilité | Versions ponctuelles alignées avec MediaWiki. Le master n'est pas compatible arrière. |
MediaWiki | 1.29+ |
PHP | 5.4+ |
Modifie la base de données |
Oui |
Tables | bounce_records |
Licence | Licence publique générale GNU v2.0 ou supérieur |
Téléchargement | |
|
|
Téléchargements trimestriels | 1 (Ranked 131st) |
Utilisé par les wikis publics | 847 (Ranked 296th) |
Traduire l’extension BounceHandler sur translatewiki.net si elle y est disponible | |
Problèmes | Tâches ouvertes · Signaler un bogue |
L'extension BounceHandler permet aux wikis de gérer efficacement les e-mails de rebond, en :
- Générer un VERP "Variable envelope Return-Path" sur les appels d'e-mail de
UserMailer::send
. - Les rebonds peuvent être directement transmis à l'API
bouncehandler
depuis le MTA à l'aide d'une requête curl POST
En conséquence, les utilisateurs dont l'adresse est erronée sont désabonnés et ils en sont informés via Echo lors de leur prochaine connexion sur le wiki. Plus exactement, leur adresse n'est pas confirmée, et dans le cas où MediaWiki requiert des e-mails confirmés, aucun e-mail ne sera envoyé.
Installation
- Téléchargez et placez le(s) fichier(s) dans un répertoire appelé
BounceHandler
dans votre dossierextensions/
.
Les développeurs et les contributeurs au code doivent à la place installer l'extension à partir de Git en utilisant:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/BounceHandler - Ajoutez le code suivant à la fin de votre fichier LocalSettings.php :
wfLoadExtension( 'BounceHandler' );
- Exécutez le script de mise à jour qui va créer automatiquement les tables de base de données dont cette extension a besoin.
- Fait – Accédez à Special:Version sur votre wiki pour vérifier que l'extension a bien été installée.
Configuration
L'extension nécessite que l'agent de transfert de courrier (MTA) installé sur votre serveur de messagerie HTTP POST l'e-mail de rebond entrant à l'API d'extension nommée bouncehandler
. Cela peut être fait en ajoutant les configurations correspondantes à votre configuration MTA.
Ajout d'un routeur bouncehandler et d'une configuration de transport à Exim
Vous pouvez rediriger tous vos e-mails de rebond vers l'API bouncehandler directement pour effectuer le traitement. Vous pouvez modifier vos configurations Exim pour acheminer tous les e-mails de rebond vers un bounce-handler-router et effectuer un HTTP POST vers l'API d'extension, qui est la méthode recommandée.
Ajoutez ceci à votre /etc/exim4/exim4.conf
Sous la section de déclaration de variable :
VERP_BOUNCE_LOCALPART_REGEXP = \N^wiki-[\w.]+-\w+-\w+-[+/\w]+$\N
under router configuration:
# Route bounce emails
mw_verp_api:
driver = accept
domains = +verp_domains
condition = ${if match{$local_part}{VERP_BOUNCE_LOCALPART_REGEXP}{true}{false}}
transport = mwverpbounceprocessor
under transports, we need to write the configuration that would HTTP POST to our bouncehandler API
# POST VERP bounce emails to a MediaWiki 'bouncehandler' API 822
mwverpbounceprocessor:
driver = pipe
command = /usr/bin/curl --interface 127.0.0.1 -H 'Host: mywiki.org' http://mywiki.org/api.php -d "action=bouncehandler" -d "format=json" --data-urlencode "email@-" -o /dev/null
user = nobody
group = nogroup
You can find more details in this blog-post "POST-ing bounce email to a Mediawiki API directly from exim".
Adding bouncehandler configuration to Postfix
This section shows how the BounceHandler extension can be configured to handle bounced emails from Postfix, unlike the above section which shows how to do the same with Exim.
First of all, please make sure that Postfix & the package "postfix-pcre" are installed. Once these two installed, open up /etc/postfix/main.cf and add the following in the end of the file:
virtual_alias_maps = pcre:/etc/postfix/virtual
Also, make sure that alias_maps is set to the following:
alias_maps = hash:/etc/aliases
Save & close that file, and then create a new file called etc/postfix/virtual, , and add the following ode
/wiki-[a-z0-9_.]+-[a-z0-9]+-[a-z0-9]+-[a-z0-9+\/=]+@yourdomainname.ext/ curl_email
This will tell Postfix that all the bounced emails (the ones which have return path matching with the above regex expression) should be passed on to the command specified in the alias 'curl_email'.
Now we need to define curl_email as our alias, so save & close this file, open up /etc/aliases and add the following:
curl_email: "|curl --interface 127.0.0.1 -d action=bouncehandler -d format=json --data-urlencode email@- http://yourdomain.ext/path-to-mediawiki-install/api.php"
Save & close that file, and now type the following commands, to map your /etc/postfix/ to postfix, and then restart postfix:
sudo postmap /etc/postfix/virtual
sudo postalias /etc/aliases
sudo /etc/init.d/postfix reload
sudo /etc/init.d/postfix restart
Save and close this file, and head over to your MediaWiki's LocalSettings.php and make sure add the following line:
$wgJobRunRate = 0;
Once that is done, save and close this file. To test if this works, send an email to an invalid email to your server and then run:
php maintenance/runJobs.php
To check if your email bounces were captured, check the bounce_records
table in your MediaWiki database, and /var/log/mail.log for further testing.
API
The BounceHandler extension installs an API bouncehandler
to receive the HTTP POST from the mail server.
The API has a parameter email
to which the entire bounce email is URL encoded to.
This helps in avoiding the use of a separate bounce collector inbox or other IMAP features for the extension to work.
Example API call:
http://example.org/api.php?action=bouncehandler&email=This%20is%20a%20test%20email
This would send a bounce email with the body This is a test email
for processing.
VERP address
The extension creates a unique w:VERP address as the Return Path header to every single email send from the wiki installation. The generated VERP address is of the form
wiki-testwiki-2a-nanrfx-Tn14EQZWaotS2XNn@verpwebhost.wmflabs.org
The general template of the generated VERP address is:
$prefix-$wikiName-base36( $userID )-base36( $timestamp )-base64( hash( $algorithm, $key, $data ) )@$email_domain
Variable | Description |
---|---|
$prefix | The prefix applied to every VERP email. Default to wiki |
$wikiName | The name of the Wiki on which the extension is running |
$userID | The user id (int) of the recipient from the MediaWiki user table
|
$timestamp | The unix time-stamp value at the time of the VERP address generation |
$data | The string resulting as the concatenation of $prefix,'-',$wikiId,'-',base_convert( $userID, 10, 36),'-' and base_convert( $timestamp, 10, 36) |
$algorithm | The hashing php-hmac algorithm used to prepare the hash of $prefix |
$key | The key used to prepare the hash using the hmac algorithm |
$email_domain | The domain part of the VERP email address |
Paramètres
Configuration | Défaut | Description |
---|---|---|
$wgVERPalgorithm
|
'md5'
|
The PHP hashing algorithm you need to employ to generate the VERP return-path address. Can be md5, sha256 etc. More details at [1] |
$wgVERPsecret
|
'MediaWikiVERP'
|
The secret key you need to pass to the PHP HMAC function |
$wgVERPAcceptTime
|
259200 (3 jours) |
The threshold time (in seconds) until we are expecting a bounce. Setting it < 3 days will make sure you respond only to the valid bounces. |
$wgVERPprefix
|
'wiki'
|
The prefix of the bounce addresses. |
$wgVERPdomainPart
|
null
|
The domain part of the bounce addresses. null is equivalent to $wgServerName
|
$wgBounceRecordPeriod
|
604800 (1 semaine) |
The Bounce allowed period (in seconds). Setting it to a week makes sure that we consider a weeks bounce frequency before taking un-subscribe actions. |
$wgBounceRecordLimit
|
10
|
Allowed bounces in the given time period. |
$wgBounceHandlerInternalIPs
|
[ '127.0.0.1', '::1' ]
|
The internal IPs that are allowed to use the API. Make sure this is configured correctly, so that no outside user can cause unwanted email un-subscriptions. |
$wgBounceHandlerUnconfirmUsers
|
false
|
Set to true to enable unsubcriptions when bounces are above the threshold.
|
$wgBounceRecordMaxAge
|
5184000 (60 days) |
The period (in seconds) where are kept the records of bounces. Older bounces records are deleted. false to deactivate deletion.
|
$wgBounceHandlerSharedDB
|
false
|
(to be documented) |
$wgBounceHandlerCluster
|
false
|
(to be documented) |
$wgUnrecognizedBounceNotify
|
null
|
Array of email addresses where unrecognized bounces are sent. |
$wgGenerateVERP
|
true
|
Activate VERP addresses. |
Cette extension est utilisée par au moins un des projets Wikimédia. Cela signifie probablement que l’extension est assez stable et fonctionnelle pour être utilisée sur des sites à fort trafic. Recherchez le nom de cette extension dans le CommonSettings.php de Wikimédia et dans le fichier de configuration InitialiseSettings.php pour situer les endroits où elle est installée. Une liste complète des extensions installées sur un Wiki donné peut être visualisée sur la page Special:Version de ce wiki. |