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	Download extension ; Git [?]: Download Git master; browse repository (Phabricator · GitHub); commit history; repository contributors (GitHub); code review;
	Parameters $wgEmailNotificationsUnsubscribeLink; $wgEmailNotificationsMailer; $wgEmailNotificationsEmailTracking; $wgEmailNotificationsCreateAccountEmailRequired; $wgEmailNotificationsDisableVersionCheck;
	Added rights emailnotifications-can-manage-notifications;
	Hooks used AlternateUserMailer; BeforeInitialize; GetPreferences; LoadExtensionSchemaUpdates;
Quarterly downloads	7 (Ranked 129th)
	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

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

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

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

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

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

Groups

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

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

Use-cases

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

send batch email or async
option with fallback, alternate or concurrent use with Extension:Echo
unsubcribe notifications from User preferences
email templates based on Mustache (see also BlueSpice's NotifyMe)

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-it^talk)
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	Download extension Git ^[?]: Download Git master browse repository (Phabricator · GitHub) commit history repository contributors (GitHub) code review
Parameters $wgEmailNotificationsUnsubscribeLink $wgEmailNotificationsMailer $wgEmailNotificationsEmailTracking $wgEmailNotificationsCreateAccountEmailRequired $wgEmailNotificationsDisableVersionCheck
Added rights emailnotifications-can-manage-notifications
Hooks used AlternateUserMailer BeforeInitialize GetPreferences LoadExtensionSchemaUpdates
Quarterly downloads	7 (Ranked 129^th)
Translate the EmailNotifications extension if it is available at translatewiki.net