SMTPMail

Summary: Send automated e-mails via your SMTP server
Version: 20180112
Prerequisites: PmWiki 2.2.107 (for Notify), curl
Status: Experimental
Maintainer: Petko
License: GPLv2+
Categories: SystemTools PHP72
Users: (view? / edit)
Discussion: SMTPMail-Talk

Questions answered by this recipe

All sections are optional, you can remove those that do not apply to your recipe, and add new ones.

Description

Send automated e-mails via your SMTP server instead of the built-in PHP function "mail()".

E-mails sent from a hosting plan directly with the mail() function will sometimes get labeled as spam or simply rejected by the mail servers of the recipients. This is more probable if your wiki is on a shared hosting and other clients have abused this function and got the hosting's IP addresses blacklisted.

This function connects to your actual SMTP server, authenticated with a username and password, and sends the e-mails like you do it with your e-mail software or webmail.

This is a lightweight solution (much lighter than other existing PHP-only libraries). It relies on the cURL utility which needs to be installed on the server and callable by the PHP process (it is available on most Linux hosting plans).

The recipe will work for the Notify feature since PmWiki 2.2.107, but it doesn't require any particular PmWiki version in order to work e.g. for another addon.

Installation

  • Copy smtpmail.phpΔ to your pmwiki/cookbook directory.
  • Add to config.php this code:
    function SMTPMailOpt(){
      return array(
        'server' => 'smtps://smtp.gmail.com:465',
        'userpass' => 'USERNAME:PASSWORD',
        'from' => 'wiki@example.com',
        'bcc' => 'webmaster@example.com',
        'curl' => 'curl',
        'options' => ' --ssl -k --anyauth ',
      );
    }
    
    include_once("$FarmD/cookbook/smtpmail.php");
    $MailFunction = "MailSMTP";

Configuration

  • $MailFunction = "MailSMTP"; # This causes PmWiki and addons who implement $MailFunction to use this feature instead of the mail() PHP function.

To configure the SMTP server and authentication, create a function named "SMTPMailOpt" in config.php which would return an array of the settings, explained below. The reason to create a function instead of setting global variables is to reduce the risk your username and password to become available by mistake, e.g. via the "diag" action.

The settings array can contain the following entries:

  • 'server' => 'smtps://smtp.gmail.com:465', # This is the URI for the mail server, starting with the smtp: or smtps: (secure) protocol, then the server domain or IP address, then the port. The example server works for GMail/GSuite, check the documentation for your company e-mails and/or your internet provider.
  • $'userpass' => 'USERNAME:PASSWORD', # The username (sometimes e-mail address) and password to use when connecting to the server.
  • 'from' => 'wiki@example.com', # REQUIRED. The e-mail address for the "From:" field, usually the e-mail address for the account; sometimes you need to use the actual address of the mailbox that is authenticated, or the server may reject or rewrite the header.
  • 'bcc' => 'me@example.com', # Add a Bcc: recipient to all outgoing messages, default empty.
  • 'curl' => 'curl', # The path to the curl executable.
  • 'options' => ' --ssl -k --anyauth ', # Additional options to pass to the curl command.

This function could have a conditional and return different settings based on the global $pagename variable.

Usage

To use it for the Notify feature, you'll need PmWiki 2.2.107 or newer, and the line $MailFunction = "MailSMTP"; in config.php, no other interaction is required.

To call the function from your addon, use the same arguments as the mail() PHP function:

  $sent = MailSMTP( $to, $subject, $message, $headers);

Or, use the global $MailFunction if you don't know whether SMTPMail is installed:

  SDV($MailFunction, 'mail');
  $sent = $MailFunction( $to, $subject, $message, $headers);

The function should return true if the message was sent, false otherwise.

Notes

The recipe is experimental, please monitor the Sent folder of your mailbox and report any problems.

To enable sending SMTP mails from GMail/GSuite, you need to allow "less-secure" apps, and to disable 2-factor authentication for that mailbox. You may want to do this for a specific mailbox separate from your main one.

The actual SMTP password is written in clear in the config files, you should estimate the risks. At the very least, place it inside a if($action != 'diag') {...} block.

The recipe has not been tested in many environments, it is theoretically possible to have false positives or false negatives as a return value (like with 'mail'). Monitor your Sent folder.

Change log / Release notes

  • 20180112 Add function SMTPMailOpt(), change installation code.
  • 20180107 first public release, ready to be tested.

See also

Contributors

Written and maintained by Petko.

Comments

See discussion at SMTPMail-Talk

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.