MediaWiki extensions manual

EmailNotifications Release status: stableCategory:Stable extensions
Implementation	Hook Category:Hook extensions, Special page Category:Special page extensions
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 (2025-01-13)
Compatibility policy	Master maintains backward compatibility.Category:Extensions with master compatibility policy
MediaWiki	1.35+Category:Extensions with manual MediaWiki version
License	GNU General Public License 2.0 or later
Download	Download extension Git [?]: Browse repository (Phabricator · GitHub) Gerrit code review Git commit log Download source tarball Category:Extensions in Wikimedia version control
Parameters $wgEmailNotificationsUnsubscribeLink $wgEmailNotificationsMailer $wgEmailNotificationsEmailTracking $wgEmailNotificationsCreateAccountEmailRequired $wgEmailNotificationsDisableVersionCheck
Added rights emailnotifications-can-manage-notifications
Hooks used AlternateUserMailer Category:AlternateUserMailer extensions BeforeInitialize Category:BeforeInitialize extensions GetPreferences Category:GetPreferences extensions LoadExtensionSchemaUpdates Category:LoadExtensionSchemaUpdates extensions
Quarterly downloads	12 (Ranked 102nd)
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/run.php update (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]/maintenance/run.php [absolute path to your mediawiki install]/extensions/EmailNotifications/maintenance/sendNotifications.php > /dev/null 2>&1

Ensure that the script has execute permissions and the Cron service can access it in the specified directory

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

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:

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' => '',
];

$wgPasswordSender must be set and must be a verified domain if sending through a third party provider

Rights and privileges

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)

See also

• Extension:SwiftMailer
• Extension:ContactManager
• Extension:UserVerification
• Extension:Newsletter
• Extension:NotifyMe