Mailer Contrib

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

<--

   PLEASE DO NOT EDIT THIS TOPIC

   It is automatically generated from the subversion repository, and any changes
   you make will simply be overwritten the next time a release is generated.

   Instead, you could check your fix in, or raise a bug in the Tasks web on
   foswiki.org
-->

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.

Each web can optionally contain a topic called WebNotify.

<-- Included by WebNotifyHelp -->

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 configuraion of that user.

topics is an optional space-separated list of topics:

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

• 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

   * daisy.cutter@flowers.com : Web*

   * DaisyCutter: Petal* (1) WeedKillers (3) Pretty*Flowers

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

   * daisy@flowers.com: NewsLetter?

   * buttercup@flowers.com: NewsLetter! (1)

   * GardenGroup: AllNewsLetters? (3)
   * petunia@flowers.com: - ManureNewsLetter

   * '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.

Warning: Because an email address is not linked to a user name, there is no way for Foswiki to check access controls for subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit which 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 mailer.

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.

Foswiki/Contrib/MailerContrib code library

Installation Instructions

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 configure, then you can still install manually from the command-line. See http://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.

• 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.

If you plan to use the "run from the web" feature, you must run configure and save at least once after installing for the first time.

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 script is used as follows:
perl -I bin mailnotify [-q] [-nonews] [-nochanges] [ web1 web2 ... webN ]

Be careful what user you use to run this script. It will write the Foswiki log files, and if these log files are left in a state where they can't be written to by the Foswiki server, you may break your site.

Setting up a cron job(s)

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

Crontab syntax is 5 numbers followed by the command

A B C D E   command to be executed

• A is minutes (0-59)
• B is hour (0-23)
• C is day of month (1-31)
• D is month (1-12)
• E day of week (0-6) (Sunday=0)

An asterix '*' means any value

If you choose to setup the cron by editing the system-wide /etc/crontab file, the syntax is A B C D E username command-to-be-executed

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

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

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

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

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

Note: Multiple instances of the 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 Foswiki:Support.DuplicateNotificationsFromMailerCon.

Note: Even if you run separate -nonews and -nochanges cron jobs, the subscriptions using the "?" feature will only show the topics that changed since last time the mailnotify script was run even if it was run with -nonews. Separate newsletter jobs work best with the unconditional "!" mode.

Triggering mail notification from the browser

Because there is a risk that a stupid person could lock up your server by firing multiple notification requests at it, the REST handler is only accessible to administrators.

<-- 

 Set SHORTDESCRIPTION = Supports email notification of changes
 

-->

Tailoring the email format

Avoid editing the distributed mailnotify.tmpl file, or you will regret it later when it gets overwritten when you upgrade Foswiki. Instead, you should either use a skin setting to choose the template file, or use the web part of the template search path rules.

It is recommended to use the skin method, as it is easier to control, and requires less hacking around. Especially if you need to use the same tailoring for many (or all) webs.

• 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 Main.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

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

Another great Foswiki extension from the WikiRing - working together to improve your wiki experience!

Many thanks to the following sponsors for supporting this work:

• Wind River
• WikiGardens