MailInContrib for TWiki
Add content to TWiki topics via e-mail
Introduction
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:
Phuket: I've run out of money!
-- Prodigal Son <gapper@isp.co.uk> 10 Jul 2005 08:35:11 -0900
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.
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.2 or later, you can install from the
configure
interface (Go to Plugins->Find More Extensions)
- If you have any problems, then you can still install manually from the command-line:
- Download one of the
.zip
or .tgz
archives
- Unpack the archive in the root directory of your TWiki installation.
- Run the installer script (
perl <module>_installer
)
- Run
configure
and enable the module, if it is a plugin.
- Repeat for any missing dependencies.
- If you are still having problems, then instead of running the installer script:
- Make sure that the file permissions allow the webserver user to access all files.
- 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)
- Manually edit LocalSite.cfg to set any configuration variables.
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 && ../tools/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.
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
Many thanks to the following sponsors for supporting this work:
Related Topics: MailInContribTemplate,
TWikiPreferences