Mail In to Foswiki
Supports submissions to Foswiki via e-mail
This Contrib supports the submission of content to Foswiki topics via e-mail.
Mails can be pulled out of mail folders using POP3
, or anything else supported by CPAN:Email::Folder
The implementation is very simple; a script called
is run every so often (usually by
or an equivalent offline job scheduler). The script trawls the mail folders you specify and grabs messages that it recognises as being for the wiki.
For example, your wayward child might send a mail like this from an internet cafe in Thailand:
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
script, which scans the folder. If it finds any messages that have nothing but a correctly formatted 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 can be created if necessary.
In our example, the web exists, and so does the topic, so the following text gets appended to Travels.DailyDiary:
: I've run out of money!
-- Prodigal Son <firstname.lastname@example.org> 10 Jul 2005 08:35:11 -0900
Attachments to the mail get treated as attachments by Foswiki, and attached to the target topic.
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
By default the target topic for mail is specified in the
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. If there is no web name specified, then you can configure a default web to accept those mails.
- A mail with a
Schedule.MyClass will be saved to Schedule.MyClass
Subject: Schedule.MyClass: timetable will be saved to Schedule.MyClass
Subject: MyClass will be saved to <default web>.MyClass.
Subject: MyClass: timetable will be saved to <default web>.MyClass, if the default web is set as
- If a topic specified on the
Subject: line doesn't exist, it will be created.
You can also configure the module to examine the
fields in the mail, and get the name of an existing topic from there instead.
- If a non-existant topic is specified in
CC: then it is ignored.
- The valid, existing topic found in the
CC: fields is taken, and overrides the
- A mail addressed to
<MyTopic@example.com> will be saved in <default web>.MyTopic
- A mail addressed to
<Schedule.MyTopic@example.com> will be saved in Schedule.MyTopic
- A mail addressed to
"Mylene Classe" <Schedule.MyClass@example.com> will be saved in Schedule.MyTopic
- A mail addressed to
"Mylene Classe" <MyClass@example.com> will be saved in <default web>.MyTopic
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
it will insert the incoming mail immediately below
is rather ike a Foswiki macro
; you can give it parameters. For example,
. The following options are available:
where - can be
below (relative to the comment)
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 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 Foswiki access controls to protect target topics.
You can configure the module to look at the
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
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.
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.
Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".
If you have any problems, or if the extension isn't available in
, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions
for more help.
: The CPAN
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
bin directory, and invoke the sript from there (this is so
mailincron can read
Because of the security issues involved (passwords for the mailboxes etc.) configuration uses variables set in your
. The easiest way to set them is using
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
, the script will scan the mail folders, describe what it would have done, and exit, without modifying any folders, the wiki, or sending any mails.
To run the script you need to set up a cron job. For example, to transfer mail into the wiki once every hour you might write:
0 * * * * cd /home/foswiki/bin && ../tools/mailincron 2>&1 >> /home/foswiki/logs/mailincron.log
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
Another great Foswiki extension from the WikiRing
- working together to improve your wiki experience!
Many thanks to the following sponsors for supporting this work:
Related Topics: DefaultPreferences
|| Foswiki:Main.CrawfordCurrie (http://c-dot.co.uk)
| Copyright ©:
|| 2005, TWiki Contributors
2008-2009 Foswiki Contributors
|| GPL (GNU General Public License)
|| 2329 (03 Feb 2009)
| Change History:
| 3 Feb 2009
|| Foswikitask:Item456: ported to Foswiki Foswikitask:Item4955: config options moved to 'Mail and Proxies' Foswikitask:Item5829: force new revision on each submission Foswikitask:Item5843: extract target topic from CC: field - general improvement to rules for extracting the target topic
| 1 Aug 2008
|| TWikibug:Item5450: minor doc fix
| 8 Sep 2007
|| TWikibug:Item4575 various ideas from Dev topic, tested against 4.2.0
|| Fixed TWikibug:Item3334 by removing dependency on FuncUsersContrib
|| Added support for listing attachments in-line with the mail
|| Fixed parser failures on multipart MIME messages
|| Fixed problem with spaces in attachment names
|| 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.
|| TWikibug:Item1665 - TWikibug: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.
|| TWikibug:Item788 - updated CPAN dependencies for MailInContrib
|| TWikibug:Item784 - Added POP3 support for delete. Don't understand why it was working before; though I suspect it must have been using MailDir
|| TWikibug:Item143 - Cairo compatibility in MailInContrib
|| TWikibug:Item181 - added dependendcy on Error for Cairo installs; split contributions using a blank line to stop them crushing together
|| TWikibug:Item181 - minor formatting issue fixed
|| TWikibug: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