Extension:BounceHandler

From MediaWiki.org
Jump to: navigation, search

Other languages:
беларуская (тарашкевіца)‎ • ‎català • ‎Deutsch • ‎English • ‎español • ‎suomi • ‎français • ‎italiano • ‎日本語 • ‎Nederlands • ‎polski • ‎português • ‎português do Brasil • ‎sicilianu • ‎中文
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.png
BounceHandler

Release status:Extension status stable

ImplementationTemplate:Extension#type Hook, Database
DescriptionTemplate:Extension#description Allows users to handle email bounces
Author(s)Template:Extension#username
Latest versionTemplate:Extension#version 1.0 (Continuous updates)
MediaWikiTemplate:Extension#mediawiki 1.25+
PHPTemplate:Extension#php 5.3+
Database changesTemplate:Extension#needs-updatephp Yes
ComposerComposer Yes
TablesTemplate:Extension#table1 bounce_recordsExtension:BounceHandler/bounce_records table
LicenseTemplate:Extension#license GNU General Public License 2.0 or later
Download
ParametersTemplate:Extension#parameters
  • $wgBounceHandlerCluster
  • $wgBounceHandlerInternalIPs
  • $wgBounceHandlerSharedDB
  • $wgBounceHandlerUnconfirmUsers
  • $wgBounceRecordLimit
  • $wgBounceRecordPeriod
  • $wgGenerateVERP
  • $wgUnrecognizedBounceNotify
  • $wgVERPAcceptTime
  • $wgVERPalgorithm
  • $wgVERPdomainPart
  • $wgVERPprefix
  • $wgVERPsecret
TagsTemplate:Extension#tags
VERP
Hooks usedTemplate:Extension#hook
UserMailerChangeReturnPathManual:Hooks/UserMailerChangeReturnPath
LoadExtensionSchemaUpdatesManual:Hooks/LoadExtensionSchemaUpdates
UnitTestsListManual:Hooks/UnitTestsList
BeforeCreateEchoEventManual:Hooks/BeforeCreateEchoEvent
EchoGetDefaultNotifiedUsers

Translate the BounceHandler extension if it is available at translatewiki.net

Check usage and version matrix.

IssuesPhabricator

Open tasks · Report a bug

The BounceHandler extension allows wikis to handle bounce emails efficiently, by:

  • Generate a VERP "Variable envelope Return-Path" on UserMailer::send email invocations.
  • Bounces can be directly fed to the bouncehandler API from the MTA using a curl POST request

Installation[edit]

  • Download and place the file(s) in a directory called BounceHandler in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    wfLoadExtension( 'BounceHandler' );
    
  • Run the update script which will automatically create the necessary database tables that this extension needs.
  • YesY Done - Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration[edit]

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[edit]

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.

Add this to your /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 -H 'Host: mywiki.org' http://mywiki.org/api.php -d "action=bouncehandler" --data-urlencode "email@-" -o /dev/null
	user = nobody
	group = nogroup

You can find more details in here.

Adding bouncehandler configuration to Postfix[edit]

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-[\w.]+-\w+-\w+-\w...............@yourdomainname.ext/  curl_email

Note Note: You need to replace yourdomainname.ext with your own domain name.

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 -d action=bouncehandler --data-urlencode email@- http://yourdomain.ext/path-to-mediawiki-install/api.php"

Note Note: You need to provide the full domain name in place of yourdomain.ext and the full path to your MediaWiki Installation in place of /path-to-mediawiki-install.

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 /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 a 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[edit]

The BounceHandler extesnsion 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://mywiki.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[edit]

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, $prefix ) )@$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
$prefix 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

Parameters[edit]

Configuration Description
$wgVERPalgorithm 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 The secret key you need to pass to the PHP HMAC function
$wgVERPAcceptTime The threshold time until we are expecting a bounce. Setting it < 3 will make sure you respond only to the valid bounces.
$wgBounceRecordPeriod The Bounce allowed period. Setting it to a weeks time ( 604800 ) makes sure that we consider a weeks bounce frequency before taking un-subscribe actions.
$wgBounceRecordLimit Allowed bounces in the given time period.
$wgBounceHandlerInternalIPs The internal IP's that are allowed to use the API. Make sure this is configured correctly, so that no outside user can cause unwanted email un-subscriptions.