Manual:Email

Email is an important part of the way MediaWiki is designed to operate. Although it is technically possible to do without it, many features from MediaWiki core as well as certain extensions depend on, or otherwise benefit from, the ability to send email. Such features include user registration, authentication or user confirmation, password changes and password resets, and user-to-user email.

This page is intended to help the site admin get started in setting up email notifications on the wiki, or making changes to the existing setup.

Basic setup

Review the following list of configuration options commonly used in LocalSettings.php. Many of them should have been set when you first set up your wiki, while others may still call for closer attention.

$wgEnableEmail (boolean) - commonly set to true to enable the basic email features, such as user registration by email, password reminders, etc.
$wgPasswordSender - the email address from which to send notifications to users, most notably notifications relating to the creation and modification of passwords.
- The default is a server address: 'apache@' followed by the value of $wgServerName, for instance apache@localhost. It may not be the right address if you enable SMTP authentication (see below).
- The name of the sender defaults to $wgSitename and if necessary, can be customised by editing MediaWiki:Emailsender.
$wgEmailAuthentication - set to true (default) to enable email authentication (confirmation) for this wiki. Except for password reminder emails, email functions only work for authenticated email addresses.
$wgEnableUserEmail (boolean) - additionally enables user-to-user email via Special:EmailUser. If it is enabled, users can still opt out of receiving email by editing their personal preferences.
$wgEmailConfirmToEdit - set to true (default: false) to require users to confirm email address before they can edit.
$wgSMTP - see below.

When to send or not to send notifications

$wgEnotifUserTalk - set to true (default: false) to allow email notifications to a user when someone else edits the user's talk page. This is a default: if enabled, users can still opt in or out by editing their user preferences.
$wgEnotifWatchlist - set to true (default: false) to allow email notifications for watched pages. Again, this is a default: if enabled, users can still opt in or out by editing their user preferences.

Advanced configuration

Many more options are listed here.

How to handle email notifications

MediaWiki supports two ways of handling outgoing email on behalf of the wiki. Consider which works best for you:

PHP Mail

The default setting of MediaWiki is to rely on PHP's mail() function, which is then used to send email directly from the server. Because it is a built-in function, it does not require any additional setup. Although it is the easiest approach, a common issue is the tendency for emails to end up in the recipient's spam folder or even to fail to be delivered at all.

Make sure that the email address you set in $wgPasswordSender is correct. Some hosts will throw an error message if the address does not match the server domain.

SMTP

SMTP (Simple Mail Transfer Protocol) is usually the recommended approach if you are able to connect to an SMTP server. Your webhost may offer such a service and there are other, third-party service providers (ESPs) you can look into. See the manual page about $wgSMTP for further information. Even if there is no absolute guarantee that emails are always received in good order, SMTP-based sending has a much better track record.

Optionally, you can run some checks to see if email features are working as intended. An easy way of checking this is to go to Special:EmailUser and send an email to yourself. If there are issues, you may see an error message like Failed to connect to (hostname):(port) [SMTP: Failed to connect socket: (code: -1, response: )].