Mailer Contrib

Supports email notification of changes

Allows users to "subscribe" to regularly scheduled emails containing either:

• A report on changes to all topics that have changed within a particular Foswiki web.
• A report on changes to a specific topic or set of topics the user can define flexibly.
• The entire content of a specific topic or set of topics. This is referred to as "news mode."
• The companion plugin (Foswiki:Extensions.SubscribePlugin) lets you trivially add a "Subscribe to changes" button to topics

How it works

MailerContrib generates and sends out emails based on analysis of

1. users' subscriptions listed in the WebNotify topic in each web, and
2. changes within the respective webs.

The mailer collates the changes so that each subscriber only receives one email notification for all changes in all webs in the wiki. Furthermore, users can elect to receive just summaries of changes, or the entire content of topics that have changed.

Notifications are only sent for changes that are not considered "minor". This is controlled by several factors:

• Changes to the same topic by the same user, when made within the configure setting $Foswiki::cfg{ReplaceIfEditedAgainWithin} (default 3600 seconds / 1 hour), will be recorded as minor.
• Changes with the "force new revision" flag set are never logged as minor.
• Old releases of Foswiki allowed users to select a "Don't notify" checkbox during save. This feature was removed from Foswiki 2.x.

If the mailnotify process runs in the interm between a recorded change, and a subsequent minor change, then the 2nd minor change will not trigger a new notification.

How notifications are requested

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 email 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. Note: The guest user WikiGuest does not have an email address mapped to it, and will never receive email regardless of the configuration of that user.

topics is an optional space-separated list of topics:

• ... without a Web. prefix
• ...that exist in this web.

Users may further customize the specific content they will receive using the following controls:

• Using wild-card character in topic names - You can use * 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.
• Unsubscribing to specific topics - Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic". The '-' sign means "unsubscribe" or "don't send notifications regarding this particular topic". This allows users to elect to filter out certain topics. Topic filters ('-') take precedence over topic includes ('+') i.e. if you unsubscribe from a topic it will cancel out any subscriptions to that topic.
• Including child-topics in subscription - Each topic may optionally be followed by an integer in parentheses, indicating the depth of the tree of children below that topic. Changes in all these children will be detected and reported along with changes to the topic itself. Note This uses the Foswiki "Topic parent" feature.
• Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/or a question mark ? with no intervening spaces, indicating that the topic (and children if there is a tree depth specifier as well) should be mailed out as complete topics instead of change summaries. ! causes the full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic.

Examples: Subscribe Daisy to all changes to topics in this web.

   * daisy.cutter@flowers.com

Subscribe 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*Flowers

Subscribe StarTrekFan to changes to all topics that start with Star except those that end in Wars, sInTheirEyes or shipTroopers.

   * StarTrekFan: Star* - *Wars - *sInTheirEyes - *shipTroopers

Subscribe 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: - ManureNewsLetter

Subscribe IT:admins (a non-Foswiki 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 in 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 email addresses of all members.

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 email, using whichever skin is selected in the topic being mailed.

In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by Foswiki:Extensions.PublishPlugin to delimit the text to be published are respected in news mode.

Per-user preferences

When emails are generated, they take into account a subset of the user preferences of the user being mailed to (where these can be determined from user topics in the wiki), allowing things like (for example) user language preferences to be taken into account. The subset of preferences that is respected is defined configure setting {MailerContrib}{RespectUserPrefs} and defaults to LANGUAGE.

Foswiki/Contrib/MailerContrib code library

The second part of the module is a code library that provides the services for other applications to modify the subscription topics through a clean, well documented API. This allows (for example) plugin developers to add (for example) a "Register me for this newsletter" button to their pages. Developers should refer to the documentation for the WebNotify class as their starting point.

Installation Instructions

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. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

• To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.

Additional settings

• You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} setting in configure. This allows you to limit the domains to which emails can be sent, or even block email addresses altogether.

The mailer can be run from cron (or an equivalent off-line job scheduler), from the command-line, or from a web page.

Running from the command-line

The mailer can be invoked from the command line by the tools/mailnotify script.

The script is used as follows:
perl -I bin mailnotify [-q] [-nonews] [-nochanges] [ web1 web2 ... webN ]

bin	path to the Foswiki bin directory, so that the script can find the rest of Foswiki
-q	Don't print progress information
-nonews	Skip the "news mode" (do not process subscriptions that include "!" or "?" following the topic)
-nochanges	Only run the news mode. (only process subscriptions that include "!" or "?" following the topic)
-noreset	Don't reset the timestamp after this run. The next run will repeat the same changes notified in this run
-nomail	Don't actually send mail, just show what would be done. Be sure to include -noreset or the timestamp will be reset even though no mail was sent.
web1 web2 ... webN	List of webs to process, separated by spaces or commas. The default is to process all webs. Wildcards (*) are supported.

Setting up a cron job(s)

You need to set up a cron (or equivalent) job to run the tools/mailnotify script.

Setting up cron can be done in many ways. Below is an ultra-short overview which may be sufficient.

For example, assuming Foswiki was installed at /usr/local/foswiki, this cron entry:

0 0 * * * cd /usr/local/foswiki && perl -I bin tools/mailnotify -q Public Private

will generate change notifications for the Public and Private webs every night at midnight.

0 0 * * * cd /usr/local/foswiki && perl -I bin tools/mailnotify -q -Sandbox

will generate change notifications for all webs, except the Sandbox web.

0 0 * * 0 cd /usr/local/foswiki && perl -I bin tools/mailnotify -nochanges

will generate newsletters from all webs every week on midnight Saturday but will not process the non-newsletter subscriptions.

0 0 * * * cd /usr/local/foswiki && perl -I bin tools/mailnotify -nonews

will generate change notifications for all webs every night at midnight but will not process the newsletter subscriptions.

To learn more about cron and crontab, Google for crontab.

Triggering mail notification from the browser

You can also the mailer from within the browser, using a REST handler.

For example, to notify changes in all webs, POST to %SCRIPTURL{rest}%/MailerContribPlugin/notify. The URL parameters webs, nonews, nochanges, and excludewebs correspond to the different command-line parameters.

nonews=1	Skip the "news mode" (do not process subscriptions that include "!" or "?" following the topic)
nochanges=1	Only run the news mode. (only process subscriptions that include "!" or "?" following the topic)
noreset=1	Don't reset the timestamp after this run. The next run will repeat the same changes notified in this run
nomail=1	Don't actually send mail, just show what would be done. Be sure to include -noreset or the timestamp will be reset even though no mail was sent.
webs=web1 web2 ... webN	List of webs to process, separated by spaces or commas. The default is to process all webs. Wildcards (*) are supported.
excludewebs=web1 web2 ... webN	List of webs to exclude, separated by spaces or commas. The default is to process all webs. Wildcards (*) are supported.

(Admin authority required!) Because there is a risk that someone could lock up your server by firing multiple notification requests at it, the REST handler is only accessible to administrators.

Tailoring the email format

The changes emails sent to subscribers are based on a Foswiki template called mailnotify. This template must contain the following definitions.

HTML:before	Section of an HTML email before the changes
HTML:middle	Repeated in an HTML email for each change
HTML:after	Section of an HTML email after the changes
HTML:diff	Topic diffs in HTML format
PLAIN:before	Section of a plain text email before the changes
PLAIN:middle	Repeated in a plain text email for each changes
PLAIN:after	Section of a plain text email after the changes
PLAIN:diff	Topic diffs in plain text format
MailNotifyBody	All the above are embedded in this. %HTML_TEXT% expands to the HTML obtained by expanding the HTML:* templates, %PLAIN_TEXT% from the PLAIN:* templates. The definitions may contain %DIFF_TEXT%.

The default template sends multipart emails containing both HTML and plaintext versions.

• Simple global tailoring used in all webs using your normal default skin
  • Make a copy of templates/mailnotify.tmpl called templates/mailnotify.skiname.tmpl. For example, templates/mailnotify.pattern.tmpl, and modify this copy to your need. If you use the NatSkin simply use templates/mailnotify.nat.tmpl instead

• Using a dummy skin name globally
  • In SitePreferences, define a setting * Set SKIN = notifyskin,pattern where the notifyskin is the dummy skin name and the pattern in this example is the real skin.
  • Create a templates/mailnotify.notifyskin.tmpl with your tailorings

• Using a dummy skin name per web
  • In each web where you want a special mailnotify template, add the setting * Set SKIN = notifywebname,pattern where the notifywebname is the dummy skin name for this web and the pattern in this example is the real skin.
  • For each web where you need a special mailnotify template, create a templates/mailnotify.notifywebname.tmpl with your tailorings

• Using the web path in the templates directory
  • For each web where you want a special mailnotify, create subdirectories in templates with the same names as the webs and place a templates/mailnotify.tmpl in these subdirectories with your tailorings

Newsletters are sent after formatting using the standard view template, using whichever skin is selected in the topic being mailed.

Using a topic defined email template

If you want to use a topic to define the notify email format this is possible with a small workaround. Before you go ahead and do this you need to consider the security implication. Making the email format available to any user from a browser means that spammers can abuse this to create messages where they can spoof the from address. Only use this method if your Foswiki installation is safely behind a firewall and your users can be trusted.

The method can best be shown with an example. In the following we...

• Define a custom mailnotify template based on a skin setting in WebNotify
• Allow the users to define the email format in a topic called WebNotifyCustomTemplate

Here are the steps:

First, we create a file templates/mailnotify.customnotify.tmpl which only contains these two lines

%TMPL:INCLUDE{"mailnotify"}%
%TMPL:INCLUDE{"WebNotifyCustom"}%

In the webs where you want the topic defined email format, we add the setting

   * Set SKIN = customnotify,pattern

(assuming pattern is the normal skin)

And we create a topic in the web called WebNotifyCustomTemplate which contains the entire mailnotify template you want to use. Simply copy the content from templates/mailnotify.tmpl to this template and do the tailoring.

Info

Many thanks to the following sponsors for supporting this work:

• Wind River
• WikiGardens

Change History

2.92 (15 Mar 2023)	Foswikitask:Item14580: fix DIFF_TEXT
2.91 (17 Jan 2023)	Foswikitask:Item15176: mailer fails to load language preferences for users
2.90 (28 Apr 2022)	Foswikitask:Item15090: mailnotify script must run as admin user Foswikitask:Item15091: only notify people of topics that they have view access to
2.85 (8 Jan 2018)	Foswiki 2.1.5 Foswikitask:Item14554: remove link to unused wikiring.com domain. Foswikitask:Item13350: Mailnotify appears to skip notification of some changes. Foswikitask:Item14446: Unwritable work_area results in mega-spam. Foswikitask:Item14588: mailnotify fills debug log with errors about "surprising mapping" and "missing mapping". Foswikitask:Item14590: missing closing tag in html diff of mailnotify.
2.84 (8 Feb 2017)	Foswiki 2.1.3 Minor file permissions changes
2.83 (15 Nov 2016)	Foswikitask:Item13936: Allow From: address of emails to be separately configured Foswikitask:Item14216: mailnotify fails with "Wide character in print"
2.82 (14 Jun 2015)	Foswiki 2.0. Foswikitask:Item13423: Perl 5.22 deprecations Foswikitask:Item13378: Foswikitask:Item13387: utf-8 foswiki core Foswikitask:Item13323: use /usr/bin/env perl in scripts Foswikitask:Item13345: CGI deprecations. Foswikitask:Item13287: Regular expression updates Foswikitask:Item13125: CGI Changes Various documentation and copyright updates.
2.81 (16 Jun 2014)	Foswiki:Tasks/Item12839: Fully specify the REST security parameters. Foswiki:Tasks/Item12943: notify REST handler crashes with invalid array ref.
2.80 (28 Apr 2014)	Foswiki:Tasks/Item8425: support relative links better. Foswiki:Tasks/Item11507: support changing LANGUAGE via user preferences
2.70 (27 Mar 2014)	Foswiki:Tasks/Item12717: fix inconsistencies in template expansion of mailnotify
2.60 (25 Mar 2014)	Foswiki:Tasks/Item12786: fix flooding with unintended mails Foswiki:Tasks/Item12823: mark cron-generated mails as per RFC 3834, Foswiki:Tasks/Item12583: Convert to simple decimal version.
2.5.5 (27 Aug 2013)	Foswiki:Tasks/Item12525: fix removal of subscriptions
2.5.4 (25 Mar 2013)	Foswiki:Tasks/Item12447: correct support for character encodings
2.5.3 (11 Sep 2012)	Foswiki:Tasks/Item12072: undocument non-existent -user parameter and update faulty examples Foswiki:Tasks/Item11138: Empty subscription without trailing space after colon is treated as wildcard for all topics
2.5.2 (2 Dec 2011)	Foswiki 1.1.4 Release: Foswiki:Tasks/Item11138: Foswiki:Tasks/Item11131: Document behavior with group subscriptions, Resolve issue with trailing spaces impacting subscriptions
2.5.1 (25 Jul 2011)	Foswiki:Tasks/Item10980: fix case where interaction with SubscribePlugin could potentially break cached CGI (fcgid/mod_perl)
2.5.0 (5 Apr 2011)	Foswiki:Tasks/Item9459: add DIFF template for improved change presentation
2.4.4 (5 Apr 2011)	Foswiki:Tasks/Item10545: Fix overriding rules
2.4.3 (30 Sep 2010)	Foswikitask:Item6011: document -user parameter and update examples in order to make fully functional on versions of Foswiki through 1.0.10; other documentation cleanup -- Foswiki:Main.WillNorris
2.4.2 (31 Jul 2010)	Foswikitask:Item9415: Documentation updates
2.4.1 (9 Jul 2010)	Foswikitask:Item9261: split of the plugin more completely to make configuration cleaner. No functional changes.
2.4.0 (18 Dec 2009)	Foswikitask:Item2511: make a new tiny plugin module, to reduce load time for when the mailer isn't used in a request
2.3.0 (8 Dec 2009)	Foswikitask:Item8316: Added REST handler, Foswikitask:Item2473: Foswikitask:Item2480: doc & dead code tidy-ups
2.2.1 (4 Dec 2009)	Foswikitask:Item8354: Martin Rowe fixed a problem with STARTPUBLISH in newsletters corrupting the template
2.2.0 (17 Oct 2009)	Foswikitask:Item1302: Removed the documentation of the -news mode which was actually never really implemented. Instead added two new -nonews and -nochanges modes which enables running mailnotify in newsletter mode with another schedule than the changes mode. If you upgrade and used the -news option with mailnotify things will work like you are used to as the -news option made no difference (old bug).
2.1.0 (15 Oct 2009)	Foswikitask:Item2260: Make the feature that allows defining the email template based in either skin or web path. And improve the documentation so people can learn how to tailor the emails that the WebNotify feature sends. Foswikitask:Item1603: use quotes to protect topic names with odd characters in them
2.0.2 (20 Sep 2009)	Small documentation update for Foswiki 1.0.7 release (RELEASE and adding parent)
2.0.1 (23 Apr 2009)	Foswikitask:Item1501: Minor bug in logfile output fixed
2.0.0 (03 Dec 2008)	Re-released for the Foswiki project
8 Sep 2004	1.000 Initial (tm)wiki version