Extensão:BounceHandler
BounceHandler Estado da versão: estável |
|
---|---|
Implementação | Hook , Banco de dados |
Descrição | Permite que os usuários lidem com devoluções de e-mail. |
Autor(es) |
|
Última versão | 1.0 (Continuous updates) |
Política de compatibilidade |
Snapshots releases along with MediaWiki. Master is not backward compatible. |
MediaWiki | 1.29+ |
PHP | 5.4+ |
Modifica o banco de dados |
Sim |
Tabelas | bounce_records |
Licença | GNU GPL (Licença Pública Geral) 2.0 ou superior |
Download | |
|
|
Quarterly downloads | 3 (Ranked 131st) |
Public wikis using | 847 (Ranked 296th) |
Para traduzir a extensão BounceHandler, verifique sua disponibilidade no translatewiki.net | |
Problemas | Tarefas em aberto · Relatar um bug |
A extensão BounceHandler permite às wikis manipular e-mails devolvidos de forma eficiente, fazendo o seguinte:
- Gera um 'caminho de retorno' VERP nas chamadas de UserMailer::send.
- Bounces can be directly fed to the
bouncehandler
API from the MTA using a curl POST request
As a result, users whose address is in error are un-subscribed and they are notified through Echo about this the next time they connect on the wiki. More exactly, their address is un-confirmed, and in case MediaWiki requires confirmed emails no emails will be further sent.
Instalação
- Baixe e coloque o(s) arquivo(s) num diretório chamado
BounceHandler
na sua pastaextensions/
.
Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/BounceHandler - Adicione o seguinte código ao final do seu arquivo LocalSettings.php :
wfLoadExtension( 'BounceHandler' );
- Execute o script de atualização que criará automaticamente as tabelas de banco de dados necessárias a essa extensão.
- Concluído – Navegue à página Special:Version em sua wiki para verificar se a instalação da extensão foi bem sucedida.
Configuração
The extension requires the Mail Transfer Agent (MTA) installed in your mail server to HTTP POST the incoming bounce email to the extension API named as bouncehandler
. This can be done by adding the corresponding configurations to your MTA configuration.
Adding bouncehandler router and transport configuration to Exim
You can redirect all your bounce emails to the bouncehandler API directly to do the processing. You can edit your Exim configurations to route all bounce emails to a bounce-handler-router and do HTTP POST to the extension API, which is the recommended method.
Adicione o seguinte em seu arquivo /etc/exim4/exim4.conf
Under the variable declaration section:
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: example.com' http://example.com/api.php -d "action=bouncehandler" -d "format=json" --data-urlencode "email@-" -o /dev/null
user = nobody
group = nogroup
Encontre mais detalhes aqui.
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+\/=]+@example.com/ 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://example.com/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.
Endereço do VERP
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
Variável | Descrição |
---|---|
$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 |
Parâmetros
Configuração | Default | Descrição |
---|---|---|
$wgVERPalgorithm
|
'md5'
|
O algoritmo de hash do PHP que você precisará empregar para gerar o endereço de retorno VERP. Pode ser md5, sha256 etc. Mais detalhes em [1] |
$wgVERPsecret
|
'MediaWikiVERP'
|
A chave secreta que você precisa para passar para a função PHP HMAC |
$wgVERPAcceptTime
|
259200 (3 days) |
O tempo limite até o qual estamos esperando um retorno. Defini-lo como inferior a 3 fará com que você responda apenas às devoluções válidas. |
$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 week) |
O prazo previsto para rejeição. Defini-lo para um tempo semanal (604800) garante que consideramos uma freqüência semanal para evolução antes de tomar ações de cancelamento de inscrição. |
$wgBounceRecordLimit
|
10
|
Devoluções permitidas num período de tempo determinado. |
$wgBounceHandlerInternalIPs
|
[ '127.0.0.1', '::1' ]
|
Os IPs internos que têm permissão para usar a API. Certifique-se que isto esteja configurado corretamente, para que nenhum usuário externo possa causar cancelamentos de assinaturas de e-mail indesejados. |
$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. |
Esta extensão está sendo usada(o) por um ou mais projetos da Wikimedia. Isto significa que, provavelmente, a extensão é estável e funciona bem o suficiente para ser utilizada(o) em sites da web de alto tráfego. Procure pelo nome dessa extensão nos arquivos de configuração CommonSettings.php e InitialiseSettings.php da Wikimedia para verificar onde ela foi instalada. Uma lista completa das extensões instaladas numa wiki em particular podem ser visualizadas na página Special:Version da wiki. |