MailInContrib for TWiki

This Contrib supports the submission of content to TWiki topics via e-mail.

WARNING: TWiki-4 only. If you want to use this plugin with an earlier version of TWiki, please use http://twiki.org/cgi-bin/viewfile/Plugins/MailInContrib?rev=1.7&filename=MailInContrib.zip

Mails for twiki can be pulled out of mail folders using POP3, IMAP, or anything else supported by CPAN:Email::Folder.

The implementation is very simple; a script called mailincron is run every so often (usually by cron or an equivalent offline job scheduler). The script trawls the mail folders you specify and grabs messages that it recognises as being for the TWiki.

For example, your wayward child might send a mail like this from an internet cafe in Thailand:

To: twiki@mum_and_dad.org.uk
From: gapper@isp.co.uk
Subject: Travels.DailyDiary: cashless

*Phuket*: I've run out of money!

The message lands in your email folder at your ISP. Once an hour, a cron job runs the mailincron script, which scans the folder. If it finds any messages that have nothing but a correctly formatted TWiki Web.TopicName in the subject line, that topic is appended to (created) with the plain text of the email. The Web must exist, though the topic will be created if necessary. Both web and topic must be specified.

In our example, the web exists, and so does the topic, so the following text gets appended to Travels.DailyDiary:

Attachments to the mail get treated as attachments by TWiki, and attached to the target topic.

Note that mailincron will only process messages that have arrived since the last time it ran. So if there was an error adding a mail, it won't attempt to add it again even if it is still in the inbox.

Where the mail gets added

The target topic for a mail is normally specified in the Subject: of the mail. You just put Web.Topic as the first thing on the subject line, optionally followed by a colon and other subject text. Alternatively you can configure the module to examine the To: field in the mail and get the topic name from there instead.

• If a topic is specified, but doesn't exist, it will be created.
• If there is no web name specified, then you can configure a default web to accept those mails.
• If a non-existant web is specified, then it is an error.

You can also define a 'spambox' for each mail folder. A spambox is a topic that will take all messages that do not have a valid topic.

The module can use special HTML comments in the topic to decide where to insert new emails within the text.

If it sees the comment <!--MAIL--> it will insert the incoming mail immediately below the comment. MAIL is rather ike a TWikiVariable^?; you can give it parameters. For example, <!--MAIL{where="below"}-->. The following options are available:

• where - can be above, below (relative to the comment) top, bottom (of the topic)
• template set to the name of one of the templates in MailInContribTemplate to change the formatting of comments. The default format is "below" format.

If there is no such comment in the topic, then it just appends it to the end. If there is more than one, only the first is recognised.

Any attachments in the mail get added to the target topic as TWiki attachments. Attachments are also listed immediately below the mail body in the topic.

How the contributor is identified

The user identity is used for access control checks on the target topic, so you can use TWiki access controls to protect target topics.

You can configure the module to look at the From: entry in the email, and if a registered user has set that email (see ChangeEmailAddress), then they are identified as the contributor. Note that there is a security risk here, as the From: address in e-mail can easily be spoofed.

You can also optionally set a default user for an inbox, so if the user can't be identified from the mail, it will fall back to the default.

See Installation for help on settings.

Settings

• One line description:
  • Set SHORTDESCRIPTION = Supports submissions to TWiki via e-mail
• Name of the perl package
  • Set STUB = TWiki::Contrib::MailInContrib

Installation

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.

Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.

• If you have TWiki 4.1 or later, and Perl 5.8, you can install from the configure interface (Go to Plugins->Find More Extensions)
  • The webserver user has to have permission to write to all areas of your installation for this to work.
• If you have a permanent connection to the internet (and Perl 5.8), you are recommended to use the automatic installer script
  • Just download the MailInContrib_installer perl script and run it.
• Notes:
  • The installer script will:
    • Automatically resolve dependencies,
    • Copy files into the right places in your local install (even if you have renamed data directories),
    • check in new versions of any installed files that have existing RCS histories files in your existing install (such as topics).
    • If the $TWIKI_PACKAGES environment variable is set to point to a directory, the installer will try to get archives from there. Otherwise it will try to download from twiki.org or cpan.org, as appropriate.
    • (Developers only: the script will look for twikiplugins/MailInContrib/MailInContrib.tgz before downloading from TWiki.org)
  • If you don't have a permanent connection, you can still use the automatic installer, by downloading all required TWiki archives to a local directory.
    • Point the environment variable $TWIKI_PACKAGES to this directory, and the installer script will look there first for required TWiki packages.
      • $TWIKI_PACKAGES is actually a path; you can list several directories separated by :
    • If you are behind a firewall that blocks access to CPAN, you can build a local CPAN mini-mirror, as described at http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN_local_minimirror
• If you don't want to use the installer script, or have problems on your platform (e.g. you don't have Perl 5.8), then you can still install manually:
  1. Download and unpack one of the .zip or .tgz archives to a temporary directory.
  2. Manually copy the contents across to the relevant places in your TWiki installation.
  3. Check in any installed files that have existing ,v files in your existing install (take care not to lock the files when you check in)
  4. Manually edit LocalSite.cfg to set any configuration variables.
  5. Run configure and enable the module, if it is a plugin.
  6. Repeat from step 1 for any missing dependencies.

Note: The CPAN Email modules uses many pluggable modules to support different folder types. It's impossible to cover all the options here; all we can suggest is that you try running the script from the command-line and resolve missing modules as you find them.

• Set up cron (or equivalent) jobs to run mailincron. You must cd to the TWiki bin directory, and invoke the sript from there (this is so mailincron can read setlib.cfg)

Because of the security issues involved (passwords for the mailboxes etc.) configuration uses variables set in your LocalSite.cfg. The easiest way to set them is using configure.

The mailincron script takes one optional parameter, debug, which takes a boolean value e.g. debug=1. If you pass anything other than 0 or the empty string in debug, the script will scan the mail folders, describe what it would have done, and exit, without modifying any folders, the TWiki, or sending any mails.

To run the script you need to set up a cron job. For example, to transfer mail into the TWiki once every hour you might write:

0 * * * * cd /home/twiki/bin && ./mailincron 2&>1 >> /home/twiki/logs/mailincron.log

You must run the script from the bin directory. Make sure that the cron is run by a user with the permissions needed to read and write the TWiki data directory.

The script can also be run from a browser, though this is intended primarily for testing. From the browser, the 'debug' parameter is passed as a CGI parameter e.g.

http://my.twiki/bin/mailincron?debug=on

This is a brand-new development, not related in any to the original TWiki:Plugins/MailInAddon. Due acknowledgement is made to those early pioneers for the idea.

Contrib Info

Author:	TWiki:Main/CrawfordCurrie (http://c-dot.co.uk)
Copyright ©:	2005, TWiki Contributors
License:	GPL (GNU General Public License)
Dependencies:	Name Version Description TWiki::Plugins >=1.1 This module requires TWiki-4 Time::ParseDate >=2003.0211 Required. Available from the CPAN:Time::ParseDate archive. Error >=0.15 Required. Available from the CPAN:Error archive. Email::Folder >=0.84 Required. Available from the CPAN:Email::Folder archive. Email::FolderType::Net >=1.02 Required. Available from the CPAN:Email::FolderType::Net archive. Email::MIME >=1.82 Required. Available from the CPAN:Email::MIME archive. Email::Delete >=1.02 Optional, recommended. Available from the CPAN:Email::Delete archive.
Version:	12412
Change History:
12412	Fixed Bugs:Item3334 by removing dependency on FuncUsersContrib
10239	Added support for listing attachments in-line with the mail
10182	Fixed parser failures on multipart MIME messages
10111	Fixed problem with spaces in attachment names
9427	Added Email::Delete::POP3 and Email::Delete::IMAP implementations, and solved a curious problem with IMAP folders, where the MIME parser couldn't parse messages coming from them.
8969	Item1665 Item1666: Now configurable to accept mail only from registered users. Automatically maps the user and signs the contribution. Also configurable to parse the topic from the To: line. Also improved error reporting and recovery.
7205	Item788 updated CPAN dependencies for MailInContrib
7196	Item784 Added POP3 support for delete. Don't understand why it was working before; though I suspect it must have been using MailDir?
6993	Item143 Cairo compatibility in MailInContrib
5980	Item181 added dependendcy on Error for Cairo installs; split contributions using a blank line to stop them crushing together
5961	Item181 minor formatting issue fixed
5960	Item181 new version, supports DEVELOP and Cairo, and adds support for attachments (you can now mail attachments to topics)
31 July 2005	1.001 Back-ported to Cairo, added spambox (work generously supported by the Evolved Media Network)
10 Mar 2005	1.000 Initial version		Home:	TWiki:Plugins/MailInContrib
Feedback:	TWiki:Plugins/MailInContribDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/MailInContribAppraisal

Related Topics: TWikiPreferences

-- TWiki:Main/CrawfordCurrie - 14:39:14 02 January 2007