Extension:EmailToWiki

From MediaWiki.org

Manual on MediaWiki Extensions
List of MediaWiki Extensions

EmailToWiki Release status: beta
Implementation	Notify
Description	Allows emails to be sent to and appended to articles in the wiki using pagename@your-wiki-domain
Author(s)	User:Nad
Version	1.0.0 (2007-06-14)
Download	see article

[edit] Installation

Download the following source files, and save them into a directory called EmailToWiki in your wiki's extensions directory. This extension depends on the SimpleForms extension so that must be downloaded and installed too, see Extension:Simple Forms for details.

• OrganicDesign:Extension:EmailToWiki.php
• OrganicDesign:Extension:EmailToWiki.pl

Include the PHP script from your LocalSettings.php file like usual:

include("$IP/extensions/EmailToWiki/EmailToWiki.php");

The EmailToWiki extension is not a MediaWiki extension in the usual sense because it's written in Perl not PHP. When it is executed it checks the specified POP box, and scans the messages for any messages requiring article adjustments. It only checks once then exits, so it must be executed periodically from your system scheduler.

If using a Windows server you can get Perl from www.activeperl.org and add the execution to you system scheduler from control panel. On Linux you'll already have Perl and you can add the script to your crontab with a line similar to the following which calls the script once every 5 minutes.

*/5 * * * * /var/www/wiki/extensions/EmailToWiki/EmailToWiki.pl /full/path/to/your.conf

[edit] Email addresses

The username part of the email address (everything before the @) is treated as a page title, and the content of the email is appended to the content of the article having that title, or to a newly created article of that name if one didn't already exist.

Many characters which are allowed in article titles are not allowed in email addresses, so the title gets URL-encoded first which converts any illegal characters to a percentage followed by their numeric code. But also the percentages are one of the invalid email characters, so the encoding uses the ampersand character instead. The main reason this is of any concern is that any emails directed at pages outside the default namespace (like a talk page) include a colon character which is one of the invalid ones and will be converted to &3A, for example: User_talk&3ANad@foo.bar.

The extension also adds a MediaWiki variable called {{EMAILTOWIKI}} which expands to an email link for the current page.

[edit] Configuration

There can be any number of configuration files to cater for having many wikis on the same server needing to be emailed. Each has its own config file and cron entry. The config file's name should be the wiki name followed by .conf. A log file will automatically be generated in the same location as the config file but with the .conf extension replaced with .log.

The EmailToWiki.pl script takes a single parameter which is the full path name of a configuration file. The configuration file sets some global variables to specify configuration, the different variables are as follows:

[edit] Testing

If you're having trouble with the perl script not being able to write to the wiki, the following test script may help to isolate the problem, it just does and edit to the wiki using the same method that the EmailToWiki.pl script uses. Make sure you change the URL in the last line to suit your own wiki.

#!/usr/bin/perl
use Net::POP3;
use HTTP::Request;
use LWP::UserAgent;
$ua = LWP::UserAgent->new(cookie_jar => {}, agent => 'Mozilla/5.0');
%data = (title => 'test-article', content  => 'test-content');
$ua->post('http://yourdomain.tld/wiki/index.php',\%data);

Most Perl installations will come with the necessary modules to do the HTTP request, but some will not have the Net::POP3 module which is part of the libnet package. Even though the test script above doesn't use POP3, I've included it in the use list so that you can see if you Perl installation includes it since it is required by EmailToWiki.pl. If errors are raised stating that you don't have Net::POP3, then you can download and install it from your shell as follows:

wget http://search.cpan.org/CPAN/authors/id/G/GB/GBARR/libnet-1.22.tar.gz
gzip -dc libnet-1.22.tar.gz | tar -xof -
cd libnet-1.22
perl Makefile.PL
make install

[edit] Todo & bugs

• Currently only first address in TO field is extracted
• Testing for failed HTTP request not working
• Allow an option for filters to use MW registered users with emails
• Should extract $wgServer and $wgScript from LocalSettings.php automatically
• Could make Simple Forms dependency optional using code from OrganicDesign:wiki.pl

[edit] See also

• Extension:Simple Forms - EmailToWiki uses SimpleForms to prepend/append/replace content via request variables
• Extension:EmailArticle - Send rendered wiki articles to email recipients