Manual talk:$wgSMTP

Office365 SMTP Configuration - MediaWiki 1.40.0

For those constantly receiving TLSSTART failure, code 220, the $wgSMTP config detailed in the manual does not work. Instead, use the following section in LocalSettings.php, replacing user and pass with your Exchange credentials:

$smtp = Mail::factory(
    "smtp",
    [
        "host" => "smtp.office365.com",
        "username" => "email@yourdomain.com",
        "password" => "yourpassword",
        "port" => 587,
        "auth" => true,
        "html" => true,
    ]
);

In a line above this section, be sure to use:

require_once 'vendor/pear/mail/Mail.php';

MediaWiki 1.18.0 #BUG

For those having a headache trying to get the SMTP functionality to work using MW-1.18.0 there's a little oopsy in the UserMailer.php file under /includes. It seems the PEAR parameters "From" and "Return-Path" are incorrectly populated.

Make the following changes to Line 164 in UserMailer.php to fix the problem.
ORIGINAL

163:     $headers['From'] = $from->toString();
164:     $headers['Return-Path'] = $from->toString();

Change to:

163:     $headers['From'] = $from->toString();
164:     $headers['Return-Path'] = $from->address;

Note: It appears this is fixed in the "trunk" but i'm not sure if that code is slated for 1.19 or not

The above is fixed in 1.18.1 and the change above is confirmed to be in 1.19beta2.

IDHost causing problems

It appears that the MediaWiki code in includes/UserMailer.php is using the IDHost property to generate the email message id (in email headers).

Please note that IDHost is not a property documented at http://pear.php.net/manual/en/package.mail.mail.factory.php making it confusing that the code would count on it being present in $wgSMTP.

I recommend that either this documentation makes a special note that IDHost should be set for MediaWiki and is not a documented option for PEAR Mail, or providing an acceptable default such as automatically detecting the domain from other $wgSMTP options or the system hostname.

Usage, this usage needs to be confirmed!

This can be used to setup access to your mail server. Say, when you have trouble sending mails you may get strange messages - like this:

Notice of the mail server: It is not safe to rely on the system's timezone settings. Please use the date.timezone setting, the TZ environment variable or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'Europe/Paris' for '2.0/DST' instead

(sorry for the odd way of formating this, I dont know how to do this right) (Speciel:Confirmemail) Asset

Example for Usage

I used this configuration variable to resolve a problem that I was having with my ISP's mail server refusing to forward e-mail generated by my wiki site. I am running a web server using my DSL connection, with Bellsouth as my ISP. Bellsouth's mail server was not delivering any messages generated using PHP's sendmail() function -- to resolve this problem, I set up my configuraton file so that mail generated by my wiki was sent using Bellsouth's mail server.

In my case, the Bellsouth mail server does not require authentication because I am sending mail from a Bellsouth IP address. After installing PEAR's MAIL package, I included the following in my LocalSettings.php file:

$wgSMTP = array (
   'IDHost' => 'mywikidomainname.com', //this is used to build the Message-ID mail header
   'host'   => 'mail.bellsouth.net', //this is the outgoing mail server name (SMTP server)
   'port'   => 25, //this is the port used by the SMTP server
   'auth'   => false,  //in my case, authentication is not required by the mail server for outgoing mail
);

Voila! No more undelivered messages! --Hoggwild5 15:21, 18 November 2008 (UTC)

Another example

$wgSMTP = array(
                'host'     => "smtp.lifesci.dundee.ac.uk",
                'IDHost'   => "www.division.university.ac.uk",
                #'port'     => 25,
                'auth'     => false,
                #'username' => "my_user_name",
                #'password' => "my_password"
                );

--Dmb 16:16, 15 January 2009 (UTC)

Example with localhost parameter

if you are using a remote SMTP server, you may wish for the wiki to identify itself with a resolvable hostname instead of localhost. This is set in the $wgSMTP array localhost parameter:

$wgSMTP = array(
 "host" => 'smtp.example.com', 
 "IDHost" => 'example.com', 
 "localhost" => 'mywiki.example.com',
 "port" => "25",
 "auth" => true/false,
 "username" => user,
 "password" => password
);

Some mail servers will reject with "Helo command rejected: Host not found". For example postfix with smtpd_helo_restrictions = reject_unknown_helo_hostname --Erikvw 07:57, 23 January 2009 (UTC)

Nowadays "localhost" does not appear to be an option any longer. --[[kgh]] (talk) 21:00, 13 November 2020 (UTC)

Using Sendmail or Postfix (on Ubuntu/Linux)

If you are useing Postfix, that is more modern tool than Sendmail and should be installed by default with Ubuntu server, follow this manual to setup TLS encryption: How to Secure Postfix Using Let’s Encrypt. Then edit Localsettings.php in this way:

// Using Postfix
$wgSMTP = false;
$wgEmailAuthentication = false;

If you are prefer to use Sendmail install it by the command: sudo apt install sendmail. Probably, the installation process will hang on about 75%, when it is trying to generate a certificate. In this case interrupt the process by Ctrl+Z and follow this answer to complete the installation. Then edit Localsettings.php in the following way (or tray to use the above configuration):

// Using Sendmail
$wgSMTP = array(
       'host' => '127.0.0.1',
       'IDHost' => 'your.domain.com',
       'localhost' => 'your.domain.com',
       'port' => '25',
       'auth' => false,
);

Spas.Z.Spasov (talk) 14:52, 30 June 2018 (UTC)

I have postfix with SSL as you describe and I have $wgSMTP configured with the array of options. --Ciencia Al Poder (talk) 20:13, 1 July 2018 (UTC)

Does IDHost need to be changed?

The documentation isn't even clear on whether this value needs to be changed from default. If so, what should go here?  — Mike.lifeguard | ^@meta 18:32, 9 October 2009 (UTC)

Example using Google Mail

Note: this method should only be used on low-traffic wikis since Google limits the sending of emails from any single email address to 500 per day
Many ISPs are providing Google Apps as an alternative to their legacy email system. Using Google's mail servers requires additional configuration settings. If you are using Google Apps for email for your domain, there are a few additional configuration options that need to be implemented to use Google to send mail from your MediaWiki site.

First, you need to make sure your ISP has compiled PHP with OpenSSL support. You can check this with the output of phpinfo(), looking to see if OpenSSL is enabled ( this is for Unix/Linux flavors -- Windows will have other installation options ).

If this is the case, you can configure MediaWiki to use Google mail to send email from your MediaWiki site.

• Set up an email account for the MediaWiki site (webmaster@mydomain.com, or info@mydomain.com), making a note of the password assigned to this account.

• Configure your LocalSettings.php file with the following setting, replacing "mydomain.com" with your domain name:

     $wgSMTP = array(
        'host' => 'ssl://smtp.gmail.com',
        'IDHost' => 'mydomain.com',
        'port' => 465,
        'username' => 'webmaster@mydomain.com', ## or info@mydomain.com, or whatever email account you've set up for your Mediawiki installation
        'password' => 'emailpasswordforwebmaster',
        'auth' => true
     );

Customizing the "From" line

Using the Gmail option, you can configure a custom "From" line (that uses your own domain) by setting a new default address (under "Settings" -> "Accounts and Import" -> "Send mail as:"). Set $wgPasswordSender to match this new default address.

Comments

Dmitry N. Medvedev (talk) 01:58, 21 March 2012 (UTC) Does not work.

• How so?Jasper Deng (talk) 03:34, 21 March 2012 (UTC)
  • It wrote: Failed to connect to ssl://smtp.gmail.com:465 [SMTP: Failed to connect socket: Connection timed out (code: -1, response: )] --Dipsy (talk) 13:20, 25 July 2012 (UTC)
    • Sorry, I incorrectly wrote IDHost. Everything works fine. --Dipsy (talk) 07:38, 28 July 2012 (UTC)

why PEAR?

so i installed PEAR in /wiki/PEAR. but i don't quite know what it is used for? and does it even matter where it's installed?

• PEAR is an extension to PHP itself, not MediaWiki, so it's best to install it in PHP's directory.Jasper Deng (talk) 05:46, 21 March 2012 (UTC)

Amazon SES

I just wanted to note that I was successful integrating MediaWiki with Amazon's Simple E-mail Service using this feature and SES's new SMTP support. This is important because a lot of providers block e-mail sent directly from EC2 servers, and Amazon will block the SMTP port if too many messages are sent. However, even in production mode SES restricts From addresses to previously validated addresses, so the $wgUserEmailUseReplyTo variable must be set to true to ensure user-to-user e-mail will work, and $wgEmergencyContact must be set to a validated sender address. Dcoetzee (talk) 13:13, 8 April 2012 (UTC)

Since I fought this for a couple of days, I thought I'd add my experience for the next person attempting this. From this page, I got the following config:

  $wgSMTP = array(  
    'host' => 'tls://email-smtp.us-east-1.amazonaws.com',
    'IDHost' => 'email-smtp.us-east-1.amazonaws.com',
    'port' => 465,
    'username' => 'ISJAKSJAETQKJSAS8RP3LSFA',
    'password' => '13HJASHjhjhjHAkjhkhA/hUfJHSIFAjjAskJADOIW2',
    'auth' => true
);

Of course, username and password will be the ones Amazon assigned to you, not the ones shown in the example. I also found it extremely helpful to add 'debug' => true, in there to be able to see the errors in the SMTP exchange. WARNING, setting debug will show anyone who is visting your registration page the SMTP exchange which includes the password!

If your SES instance is configured in 'Sandbox' mode you should change your $wgPasswordSender and $wgEmergencyContact settings to an email address that you have verified in the AWS SES console. If new users register and they aren't in the SES verified list, they won't get the email and you'll be limited to 200 emails per day!

Using Gmail

I'm using Gmail to send mail, my configs:

         $wgSMTP = array(
                'host'     => 'smtp.gmail.com',
                'IDHost'   => "wikibiz.vn",
                'port'     => 587,
                'auth'     => true,
                'username' => myusername@gmail.com
                'password' => "mypassword"
                );

It doesn't work. Anyone know why? Thamdaocatba (talk) 06:09, 16 November 2012 (UTC)

See the section "Using Google Mail" above.--Jasper Deng (talk) 06:55, 16 November 2012 (UTC)

SELinux

If you see this error when sending email after configuring $wgSMTP, you probably have SELinux enabled.

 [SMTP: Failed to connect socket: Permission denied (code: -1, response: )]

CentOS, Fedora, Red Hat, and other users may need to reconfigure SELinux to allow PHP scripts to send email. You can *test* if this is your issue by following this guide - How to Disable SELinux. If it is, re-enable SELinux, and allow httpd (Apache) to use sendmail with setsebool httpd_can_sendmail 1

Some advices

I have solved problem with this tutorial, just take care with this:

1. If you are using Gmail, ensure of aprobe access, or Gmail will detect it as malicious acces and you couln't make it work. 2. If you have a error of acces to a socket or smething like this, it's due your hosting doesn't have open port for you, so ask them to open respective port, in case of Gmail, is port 465. 3. Put code at the beggining, before extensions codes. 4. Make sure you have installed 2 scripts of php, if you have cpanel, go to php console and install them, it's too easy as I can do it.

I hope could help you.

Google rejecting automated MediaWiki messages

I am trying to get mail working using my gmail account as the outgoing address. I am using the following configuration:

    $wgSMTP = array(
        'host' => 'ssl://smtp.gmail.com',
        'IDHost' => 'gmail.com',
        'port' => 465,
        'username' => '<redacted>@gmail.com',
        'password' => '<redacted>',
        'auth' => true
    );

All mail then gets bounced back to my gmail account with a message similar to this:

   Delivery to the following recipient failed permanently:
   <redacted>@gmail.com
   Technical details of permanent failure:
   Message rejected.  See https://support.google.com/mail/answer/69585 for more information.

Any ideas on how I can fix this? Entropy (talk) 20:09, 10 May 2016 (UTC)

Try changing IDHost so it matches your domain. Otherwise, try something from [1] --Ciencia Al Poder (talk) 21:59, 10 May 2016 (UTC)

It turns out my firewall was blocking port 465—unblocking it fixed the problem. I had to enable less secure apps for my Gmail account under Account Settings as well. Email is now working fine with IDHost set to gmail.com. Entropy (talk) 22:49, 10 May 2016 (UTC)

Problem with Hostmonster solved - should be part of the docs

Hi there, I think this should be added to the documentation. The code could also be improved to give a more helpful message. Thanks 146.198.223.71 23:30, 21 May 2016 (UTC)

Added to Manual:$wgEnableEmail, you may want to mention it in this page as well (I can't edit it). Thanks. 146.198.223.71 23:53, 21 May 2016 (UTC)

I've added it on the section about "Unknown error in PHP's mail() function " --Ciencia Al Poder (talk) 12:42, 22 May 2016 (UTC)

Nice one, thanks. Although, to me it reads a bit backwards, because fixing the sender is a less drastic solution than going through another SMTP server, and should be tried first. Also, if I understand it correctly, the reference to task T32260 relates to possible issues with the last-resort workaround, so it should be the last line of that section. Cheers. 146.198.223.71 17:05, 22 May 2016 (UTC)

Ok, done --Ciencia Al Poder (talk) 01:48, 24 May 2016 (UTC)

How do I avoid exposing the server's IP address?

I'm using mailgun, with this setup:

$wgSMTP = array(
        'host' => 'smtp.mailgun.org',
        'IDHost' => 'foowiki.com',
        'port' => 25,
        'username' => 'postmaster@foowiki.com',
        'password' => 'xxx',
        'auth' => true
);

The emails contain:

X-Mailgun-Sending-Ip: xxx.xx.xxx.xxx
X-Mailgun-Sid: ...
Received: from localhost (affiliate.test.known.host [xx.xxx.xx.xxx]) by mxa.mailgun.org with ESMTP id ... ; Tue, 27 Sep 2016 20:42:39 -0000 (UTC)

How do I get it to not expose that localhost IP address? Let me tell you hwhat (talk) 00:50, 30 September 2016 (UTC)

You can't do that, really. You send your email to a mail server, and that server tracks the original IP and adds it to mail headers. That's part of the protocol and, unless you have control on the mail server (mailgun in this case), you can't hide that. Even if you have control of the mail server, that server sends the mail to the recipient's server which would also add the IP of the previous server (mailgun). --Ciencia Al Poder (talk) 09:37, 30 September 2016 (UTC)

I ended up accomplishing this using cURL; see Manual:Mailgun#cURL_option. Let me tell you hwhat (talk) 13:57, 2 October 2016 (UTC)

Using gmail's SMTP - tested 31/03/17

Hi all,

First post on here, signed up just for this. Just a note that gmail SMTP only worked for me if i used an 'App password' instead of my usual gmail password. https://support.google.com/accounts/answer/185833

cheers.

--- Hi... can you write down your configuration? I'm trying gmail with specific app with no success. Thanks.--Ssspera (talk) 10:33, 31 March 2017 (UTC)

This is what I used. I think your localhost server name needs to match as well.

1. Enable SMTP Mail - Currently set to use personal gmail account.

 $wgSMTP = array(
       'host' => 'ssl://smtp.gmail.com',
       'IDHost' => 'gmail.com',
       'localhost' => 'myservername.org',
       'port' => 465,
       'username' => 'myemail@gmail.com',
       'password' => '16 digit special gmail app password as per url',
       'auth' => true

Test email

I'm getting SMTP set up for my MediaWiki install and was curious: what's the best way to make the wiki send a test email, just so I can verify that the configuration is correct? Thanks! Huwmanbeing (talk) 09:34, 14 October 2017 (UTC)

You can request a new password on the login page, it should send an email. Or when logged as user, you can also authenticate your email from the preferences. ~ Seb35 [^_^] 19:06, 15 October 2017 (UTC)

PEAR Mail installation when upgrading

Upgrading from an older mediawiki and also php 5.4 to php 5.6, some problems with incompatible sources and versions for Auth_SASL occurred. The sequence: sudo pear channel-update pear.php.net; sudo pear uninstall mail pear/Auth_SASL net_smtp; sudo pear install mail pear/Auth_SASL net_smtp may be helpful. It worked for us. --Gregor Hagedorn (talk) 22:52, 21 December 2017 (UTC)

Remove warning regarding MW 1.31

As far as I can see the current build of MW code at 1.31 already contains all required dependencies (https://gerrit.wikimedia.org/r/#/c/mediawiki/core/+/465674/). Therefore the waring (https://www.mediawiki.org/wiki/Manual:$wgSMTP#Install_dependencies_(MW_1.31_and_earlier)) could be removed, couldn't it? — Preceding unsigned comment added by Osnard (talk • contribs)

Looks like it's included in MediaWiki 1.31.2, which hasn't been released, but not on 1.31.1, which is the latest released version for 1.31. So... I guess it should remain, since nobody cares about doing a new release... :-( --Ciencia Al Poder (talk) 09:21, 23 May 2019 (UTC)

Yahoo?

Did somebody try to connect MediaWiki with Yahoo? --[[kgh]] (talk) 08:26, 7 October 2020 (UTC)

Running E-Mail Server on the same Server

It is not recommended, but if you are running the email-server on the same server and it gives you this error:

authentication failure [SMTP: STARTTLS failed (code: 220, response: TLS go ahead)]

you can add the following line:

'socket_options' => array('ssl' => array('verify_peer_name' => false)),

The array should look like this:

$wgSMTP = [
    'host' => 'localhost', // outbox server of the email account
    'IDHost' => 'yourdomain.com', // sub(domain) of your wiki (not something like mail.yourdomain.com)
    'port' => 587, // StartTLS-Port
    'username' => 'mediawiki@yourdomain.com', // user of the email account
    'password' => 'supersecure', // pass of the email account
    'auth' => true,
    'socket_options' => array('ssl' => array('verify_peer_name' => false))
];

This turns off the peer name verification of the server. Since the HELO sent by mediawiki respective pear is the same as the one of the mailserver, you get the error (as far as I understand..).

Reference on GitHub: 1.2   The Net_Socket Package

on php documentary: https://www.php.net/manual/en/context.ssl.php#context.ssl.verify-peer-name

Only works with direct user emails

I have found this only worked with direct user emails such as Special:EmailUser. Password reset and other emails all failed silently and I did also check my junk folder. It's a shame MediaWiki doesn't have a way of properly testing and diagnosing email problems and password reset emails are only allowed once every 24 hours so I ended up having to set up postfix and avoid $wgSMTP.

EDIT: I have just found all the failed emailed have bounced due to "unexpected volume or user complaints" so it's my email provider that's the problem. 86.173.33.162 22:48, 23 August 2022 (UTC)

Using Google Workspace

I was able to get this to work.

$wgSMTP = [
	'host' => 'smtp-relay.gmail.com',
	'localhost' => 'example.org', // Should be the domain you're registered under
	'port' => 587
];

In your workspace settings - https://admin.google.com/u/3/ac/apps/gmail/routing -> SMTP relay service
1) Allow senders - Only addresses in my domain
2) Authentication - Only accept mail from the specified IP addresses

However, this won't be encrypted, so should probably only be used for testing purposes. Prod (talk) 00:26, 15 September 2022 (UTC)

Updated gmail use

I danced around some config issues today and thought I could help some folks who may struggle with configuring gmail to work with their own mediawiki.In my LocalSettings.php:

$wgSMTP = array(

   'host' =>'ssl://smtp.gmail.com',

   'IDHost'=>'gmail.com',

   'port'=>465,

   'username'=>'myemailaddress@gmail.com',

   'password'=>'atrg thuy sdrg dvbh',

   'auth'=>true

);

Now, that password is, of course, not my password, but one I made up to reflect Gmail's requirement of an app authentication password. In "Manage my Account" in the web gmail interface, you need to turn on two factor authentication. Once that is complete, you need to generate an "app password". I labeled mine something to effect of "myawesomewiki" so I knew what it was for. Now, finding the generate app password was insanely difficult. Only by chance did I stumble on it while searching for another clue, "advanced protection". At this moment, trying to document it, I cannot find generate app password. https://support.google.com/accounts/answer/185833?sjid=16422449761093805597-NA had some useful information but was incomplete. 2603:7080:493F:FDD8:E1C1:788:B074:8E02 23:05, 22 May 2023 (UTC)

Thanks, still works as of today :) Allanext2 (talk) 00:08, 18 October 2024 (UTC)