Extension:EmailNotifications

MediaWiki extensions manual
EmailNotifications
Release status: beta
Implementation Hook , Special page
Description Provides a special page through which to manage periodic email notifications and an alternate UserMailer based on Symfony
Author(s) thomas-topway-it (thomas-topway-ittalk)
Latest version 1.0 (2024-08-16)
Compatibility policy Master maintains backward compatibility.
MediaWiki 1.35+
License GNU General Public License 2.0 or later
Download
  • $wgEmailNotificationsUnsubscribeLink
  • $wgEmailNotificationsMailer
  • $wgEmailNotificationsEmailTracking
  • $wgEmailNotificationsCreateAccountEmailRequired
  • $wgEmailNotificationsDisableVersionCheck
  • emailnotifications-can-manage-notifications
Quarterly downloads 7 (Ranked 122nd)
Translate the EmailNotifications extension if it is available at translatewiki.net

EmailNotifications provides a special page through which to manage periodic email notifications addressed to users of the wiki (based on their group) and an alternate UserMailer based on Symfony Mailer, which supports a large number of mail agents or providers like smtp, sendmail, native, Amazon SES, Mandrill, Mailgun, Mailjet.

EmailNotifications was originally developed for KM-A Knowledge Management Associates.

Key-features:

  • replaces the standard MediaWiki UserMailer for improved reliability
  • can send periodic notifications in Cron format to users of the wiki, through a user-friendly interface
  • keeps record of sent notifications and statuses for each recipient
  • supports email tracking


Installation

edit
  • Download and move the extracted UserVerification folder to your extensions/ directory
  • Run composer update --no-dev in the extension's folder, to install the required PHP libraries
  • Add the following code at the bottom of your LocalSettings.php
wfLoadExtension( 'EmailNotifications' );
  • Run php maintenance/update.php (it will create the database tables that this extension needs)
  •   Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.


In order to work for sending periodic notifications, the maintenance script needs to be executed each minute by the cron service. Then all the active notifications registered through the interface will be evaluated and executed if due.


Add the following line to your crontab file (here is a tutorial)

* * * * * php [absolute path to your mediawiki install]/extensions/EmailNotifications/maintenance/sendNotifications.php > /dev/null 2>&1




Special page Manage notifications

edit

Through the special page Manage notifications you can create multiple notifications by assigning for each of them one or more groups, the article to be used as body of the notification, the frequency[1] and a few more options. The notification will be sent to all users belonging to the specified groups and the option "send only if different from previous sent notification" can used to avoid to send notifications whose content has not changed after the previous sent notification. (based on the Manual:ParserOutput.php of the article used as body of the notification for each specific recipient)


 


The extension keeps also track of all sent notifications, which are accessible clicking the button "view" besides each of them.


 



Special page Activity

edit

If the parameter $EmailNotificationsEmailTracking is enabled (it is by default) an activity list is also available for each sent notification as long as the message get read in the email client of the recipient. A future version of the extension may support webhooks from specific email providers, like sendgrid, mailgun, etc.


 



Configuration

edit
variable description default
$wgEmailNotificationsCreateAccountEmailRequired enforce email required on user creation true
$wgEmailNotificationsUnsubscribeLink add unsubcribe link below the email body true
$wgEmailNotificationsEmailTracking add transparent pixel for tracking below email body true
$wgEmailNotificationsMailer default mailer sendmail
$wgEmailNotificationsDisableVersionCheck disable version check false


Example configuration:

$wgEnableEmail = true;
$wgPasswordSender = [sender email address]; // *** must be a verified domain if sending through a third party provider
$wgEmailNotificationsCreateAccountEmailRequired = true;
$wgEmailNotificationsUnsubscribeLink = false;
$wgEmailNotificationsEmailTracking = true;
$wgEmailNotificationsMailer = 'smtp';
$wgEmailNotificationsMailerConf = [
	'username' => '',
	'password' => '',
	'server' => '',
	'port' => ''
];

Mailer

edit

EmailNotifications includes Symfony Mailer which supports a large number of mail agents or providers like smtp, sendmail, native, Amazon SES, Mandrill, Mailgun, Mailjet.

The configuration of the mailer (which ensures the delivery of the email sent by the wiki) is done through the following parameters:

parameter description
$wgEmailNotificationsMailer the name of the chosen mailer (like "smtp", "sendgrid", etc.)
$wgEmailNotificationsMailerConf the object with the mailer configuration


The configuration for each different mailer must be provided in the following format:

// smtp
$wgEmailNotificationsMailerConf = [
	'username' => '',
	'password' => '',
	'server' => '',
	'port' => 
];

// gmail
$wgEmailNotificationsMailerConf = [
	'username' => '',
	'app-password' => ''
];

// amazon smtp
$wgEmailNotificationsMailerConf = [
	'transport' => 'smtp',
	'username' => '',
	'password' => ''
];

// amazon http
$wgEmailNotificationsMailerConf = [
	'transport' => 'http',
	'access_key' => '',
	'secret_key' => ''
];

// amazon api
$wgEmailNotificationsMailerConf = [
	'transport' => 'api',
	'access_key' => '',
	'secret_key' => ''
];

// mandrill smtp
$wgEmailNotificationsMailerConf = [
	'transport' => 'smtp',
	'username' => '',
	'password' => ''
];

// mandrill httpd
$wgEmailNotificationsMailerConf = [
	'transport' => 'httpd',
	'key' => '',
];

// mandrill api
$wgEmailNotificationsMailerConf = [
	'transport' => 'api',
	'key' => '',
];

// mailgun smtp
$wgEmailNotificationsMailerConf = [
	'transport' => 'smtp',
	'username' => '',
	'password' => ''
];

// mailgun http
$wgEmailNotificationsMailerConf = [
	'transport' => 'http',
	'key' => '',
	'domain' => '',
];

// mailgun api
$wgEmailNotificationsMailerConf = [
	'transport' => 'api',
	'key' => '',
	'domain' => '',
];

// mailjet smtp
$wgEmailNotificationsMailerConf = [
	'transport' => 'smtp',
	'access_key' => '',
	'secret_key' => ''
];

// mailjet
$wgEmailNotificationsMailerConf = [
	'transport' => 'api',
	'access_key' => '',
	'secret_key' => '',
];

// postmark smtp
$wgEmailNotificationsMailerConf = [
	'transport' => 'smtp',
	'ID' => '',
];

// postmark api
$wgEmailNotificationsMailerConf = [
	'transport' => 'api',
	'KEY' => '',
];

// sendgrid smtp
$wgEmailNotificationsMailerConf = [
	'transport' => 'smtp',
	'username' => '',
	'password' => '',
];

// sendgrid api
$wgEmailNotificationsMailerConf = [
	'transport' => 'api',
	'KEY' => '',
];

// ohmysmtp smtp
$wgEmailNotificationsMailerConf = [
	'transport' => 'smtp',
	'API_TOKEN' => '',
];

// ohmysmtp api
$wgEmailNotificationsMailerConf = [
	'transport' => 'api',
	'API_TOKEN' => '',
];




Rights and privileges

edit

Groups

edit

The extension creates the following groups: (they are assignable to users through the standard special page Special:UserRights)

group description
emailnotifications-admin let users to manage email notifications


The extension creates the following user rights.

right description
emailnotifications-can-manage-notifications Can manage email notifications

Group rights

edit
group emailnotifications-can-manage-notifications
sysop v
bureaucrat v
emailnotifications-admin v


Use-cases

edit

The extension can be used in conjunction with the following includable special pages:

  • SpecialAllPages
  • SpecialContribute
  • SpecialContributions
  • SpecialListFiles
  • SpecialListUsers
  • SpecialNewFiles
  • SpecialNewPages
  • SpecialWhatlinkshere

in order to notify users as long as the generated output changes. (the article is purged before the notification is sent). For instance, in conjunction with the option "send only if different from previous sent notification", and a frequency set for instance each week, the extension can send to administrators all the changes done in the wiki in the past week only if changes have been actually made.

Of course the same use-case also applies for all contents automatically generated by other extensions through their parser functions.


Road map

edit


See also

edit
  1. the frequency is expressed in cron format for maximum flexibility, you can use a schedule generator like crontab.guru or cronmaker for a user-friendly interface