| Home | Gifts |
Allows users to "subscribe" to regularly scheduled e-mails containing either: 
) lets you trivially add a "Subscribe to changes" button to topics
.tools/mailnotify, that generates and sends out the emails based on analysis of cron (or an equivalent off-line job scheduler), or from the command-line.
The script collates the changes emails so that each subscriber only receives one changes notification for all changes in all webs in the TWiki. Furthermore, users can elect to receive just summaries of changes, or the entire content of topics that have changed.
Each web can optionally contain a topic called WebNotify.
Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole groups of users can also be subscribed for notification.
The general format of a subscription is:
three spaces * subscriber [ : topics ]
Where subscriber can be a WikiName, an E-mail address, or a
group name. If subscriber contains any characters that are not legal in
an email address, then it must be enclosed in 'single' or "double" quotes.
topics is an optional space-separated list of topics: * in a topic name, where it is treated as a wildcard character. A * will match zero or more other characters - so, for example, Fred* will match all topic names starting with Fred, *Fred will match all topic names ending with Fred, and * will match all topic names.
* daisy.cutter@flowers.comSubscribe Daisy to all changes to topics that start with
Web.
* daisy.cutter@flowers.com : Web*Subscribe Daisy to changes to topics starting with
Petal, and their immediate children, WeedKillers and children to a depth of 3, and all topics that match start with Pretty and end with Flowers e.g. PrettyPinkFlowers
* DaisyCutter: Petal* (1) WeedKillers (3) Pretty*FlowersSubscribe StarTrekFan to changes to all topics that start with
Star except those that end in Wars, sInTheirEyes or shipTroopers.
* StarTrekFan: Star* - *Wars - *sInTheirEyes - *shipTroopersSubscribe Daisy to the full content of NewsLetter whenever it has changed
* daisy@flowers.com: NewsLetter?Subscribe buttercup to NewsLetter and its immediate children, even if it hasn't changed.
* buttercup@flowers.com: NewsLetter! (1)Subscribe GardenGroup (which includes Petunia) to all changed topics under AllnewsLetters to a depth of 3. Then unsubscribe Petunia from the ManureNewsLetter, which she would normally get as a member of GardenGroup:
* GardenGroup: AllNewsLetters? (3) * petunia@flowers.com: - ManureNewsLetterSubscribe
IT:admins (a non-TWiki group defined by an alternate user mapping) to all changes to Web* topics.
* 'IT:admins' : Web*A user may be listed many times in the WebNotify topic. Where a user has several lines in WebNotify that all match the same topic, they will only be notified about changes that topic once (though they will still receive individual mails for news topics). If a group is listed for notification, the group will be recursively expanded to the e-mail addresses of all members. __
Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for email addresses. A user identified by an email address will only be sent change notifications if the topic they are asubscribed to is readable by guest users. You can limit what email addresses can be used in WebNotify, or even block use of emails altogther, using the {MailerContrib}{EmailFilterIn} setting in =configure.
Tip: List names in alphabetical order to make it easier to find the names.
In the future it is intended that individual users will be able to control the frequency with which they are notified of topic changes, by changing a schedule specification in their home topic. However at present, the notification schedule is controlled by the frequency of activation of the cron job that runs the mailnotify script.
Note that when using the "news mode" ! or ? specifiers the entire topic text is mailed out as HTML. The newsletter template is used to generate the content in this mail, using whatever skin is selected in the topic being mailed.
In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected in news mode.
configure interface (Go to Plugins->Find More Extensions) on TWiki.org for more information.
.zip or .tgz archives
perl <module>_installer )
configure and enable the module, if it is a plugin.
,v files in your existing install (take care not to lock the files when you check in)
mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
{MailerContrib}{EmailFilterIn} setting in =configure. This allows you to limit the domains to which emails can be sent, or even block email addresses altogether.
cron (or equivalent) job to run the tools/mailnotify perl script.
The script is used as follows: perl -I bin mailnotify [-q] [-news] [ web1 web2 ... webN ]
| bin | path to the TWiki bin directory, so that the script can find the rest of TWiki. |
-q |
Don't print progress information |
-news |
Run in "news mode" (process subscriptions that include "!" or "?" following the topic) |
web1 web2 ... webN |
List of webs to process, separated by spaces or commas. The default is to process all webs. Wildcards (*) are supported. |
/usr/local/twiki, this cron entry:
0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q Public Privatewill generate change notifications for the
Public and Private webs every night at midnight. (Google for crontab for more information on what all the 0 0 * * * fields mean)
0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q -Sandboxwill generate change notifications for all webs, except the
Sandbox web.
0 0 * * 0 cd /usr/local/twiki && perl -I bin tools/mailnotify -newswill generate newsletters from all webs every week on midnight Saturday.
Note: Multiple instances of mailnotify script are not allowed to be executed simutaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.
mailnotify. This template must contain the following definitions.
HTML:before |
Section of a HTML mail before the changes |
HTML:middle |
Repeated in a HTML mail for each change |
HTML:after |
Section of a HTML mail after the changes |
PLAIN:before |
Section of a plain text mail before the changes |
PLAIN:middle |
Repeated in a plain text mail for each changes |
PLAIN:after |
Section of a plain text mail after the changes |
MailNotifyBody |
All the above are embedded in this. %HTML_TEXT% expands to the HTML obtained by expanding the HTML:* templates, and %PLAIN_TEXT% from the PLAIN:* templates. |
view template, using whatever skin is selected in the topic being mailed.
WikiRing - working together to improve your wiki experience!
Many thanks to the following sponsors for supporting this work:
| Author: | TWiki:Main/CrawfordCurrie (http://c-dot.co.uk) |
| Copyright ©: | 2004, Wind River Systems; 2006, http://WikiRing.com |
| License: | GPL |
| Version: | 03 Aug 2008 |
| Change History: | |
| 03 Aug 2008 | TWiki 4.2.1 release version |
| 27 Jul 2008 | TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time. |
| 15 May 2008 | TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors |
| 25 Jan 2008 | TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups |
| 2 Nov 2007 | TWikibug:Item4818: added quotes to support non-alphabetic and other wierd group names TWikibug:Item4887: corrected minor rendering error TWikibug:Item4917: removed dependence on symbolic web names |
| 9 Sep 2007 | TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users. |
| 6 Sep 2007 | TWikibug:Item4488 doc tweaks |
| 14550 | TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history |
| 22 Jun 2007 | TWikibug:Item4284 - added access control checks and email filter |
| 21 May 2007 | TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris) |
| 13623 | TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down. |
| 12496 | TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser. |
| 11672 | Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown |
| 11534 | TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting. |
| 8808 | TWikibug:Item1654 mailnotify must enter the command_line context |
| 8625 | TWikibug:Item1508 Making the dashes in the separatator clearer |
| 8606 | TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template |
| 8602 | TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA |
| 8522 | TWikibug:Item1511 arguments to getScriptUrl in wrong order  |
| 8434 | TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.' |
| 8398 | TWikibug:Item1460 polished up the comment a bit |
| 8308 | TWikibug:Item1362 moving mailnotify cron script |
| 7848 | TWikibug:Item1167 forced all mail operations to generate absolute URLs |
| 7568 | TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr |
| 6864 | TWikibug:tem624 mailer templates moved the the right places |
| 6861 | TWikibug:tem624 Added proper templates support for plain text mails |
| 6809 | TWikibug:tem623 don't print anything if verbosity is switched off. |
| 6659 | TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used. |
| 6474 | TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib |
| 5924 | TWikibug:tem153 fix mail URL-fixing scheme |
| 5269 | Minor doc fixes |
| 5266 | Doc tidy-ups, added filtering of _ webs, added obsolete lock script |
| 5264 | Changed default to add web name to user name (I hope) |
| 5263 | Minor doc tidyups |
| 5261 | Documentation changes, and fixed to scan all webs. |
| 5253 | runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib |
| 5234 | Minor doc changes |
| 5231 | Made a change an object, added unit tests to CVS, lots of testing. |
| 4 March 2005 | 1.010 Dakar release ready. |
| 12 Oct 2004 | 1.004 Added support for anti-subscriptions. Doc fixes from TWiki:Main.PeterThoeny. Bug fixes to permissions code. Back-off and retry if the mailer can't be reached (should really be in Net::sendEmail) |
| 6 Oct 2004 | 1.003 Excluded _ webs from processing, added bin/remove_obsolete_locks for full reverse-compatibility |
| 1 Oct 2004 | 1.002 PeterThoeny provided additional documentation |
| 27 Sep 2004 | 1.001 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib |
| 8 Sep 2004 | 1.000 Initial version |
| Home: | TWiki:Plugins/MailerContrib |
| Feedback: | TWiki:Plugins/MailerContribDev |
| Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal |
| Revision r6 - 2008-08-03 - 22:17:45 - TWikiContributor | Edit |