Although PHP’s mail() function is easy to use, it relies on having a program underneath to send the mail. On Linux, sendmail is the standard, while on other platforms, such as IBM i, any program that meets the sendmail standard can be used. Seiden Community Plus+ PHP provides msmtp, a flexible, open source, sendmail-compatible SMTP mailer, to implement PHP mail() . Here are instructions on installing and configuring msmtp, as well as an example of how to use mail().

1. Install msmtp

The msmtp component is an optional one. It doesn’t install with PHP by default, but assuming you’ve set up our CommunityPlus+ PHP repository, you can add msmtp from ACS, or through yum:

yum install msmtp

2. Configure msmtp

The system-wide msmtp configuration file is /QOpenSys/etc/msmtprc (a file name with no extension). If it doesn’t exist, create it. The contents of msmtprc should look something like this:

defaults
auth on
tls on
logfile /QOpenSys/var/log/msmtp.log
account example
host smtp.example.com
port 587
from foo@example.com
user youruser
password yourpw
account default : example

Adjust this file to match the configuration of your SMTP mail server. Every mail server is unique, so you might need to consult your mail administrator or review other software that currently uses the mail server. (For example, classic Zend Server will have the SMTP hostname and port in phpinfo/INI files.) Each option in this configuration file is explained below:

  • defaults: The following lines are the default settings for msmtp, until any specific account is configured. This is more explicitly useful in complex multiple-server msmtp configurations.
  • auth: Enable SMTP authentication.
  • tls: Enable TLS, for encrypted transport. Note that TLS can be started two different ways; normally and via STARTTLS. If your server uses STARTTLS, then you will also need to add tls_starttls on.
  • logfile: Points to a log file for msmtp. The msmtp log file is very useful for determining problems and is usually precise about what problems were, but the directory the log file is in must be writable by whatever user uses msmtp.
  • account: Set up an account definition, with a name. This can be whatever you want; it doesn’t have anything to do with what settings you need to enter for the mail user. It’s just a label for your own convenience.
  • host: The SMTP server hostname.
  • port: The port number SMTP is running on. Sometimes different ports are used, and they may offer different TLS settings as well. Usually, this will be either 25, 465, or 587; depending on if TLS is required.
  • from: The “From” address used in any mail.
  • user: The user to use when authentication is on.
  • password: The password to use when authentication is on.
  • account default : example: This makes another account (in this case, default) that “inherits” its configuration from another account (in this case, example). The account must be one that has a corresponding account line in the configuration file. “default” is a special name that msmtp uses for the default account to use; so this line simply makes the default account from the existing definition we just wrote.

More options that you need like tls_starttls or more complex examples can be found in the msmtp manual.

This file is sensitive because it’ll have the credentials for your mail server, so be sure to restrict read access to only the required users (like QTMHHTTP). Optionally, instead of (or in addition to) a system configuration file, each user can have their own configuration file called .msmtprc in their home directory.

Also make sure this file is not in EBCDIC. msmtp can only read files stored as ASCII/UTF-8.

3. Send mail

You can now use the mail function like so:

echo mail('hello@world.example.com', 'Hello', 'Hello world!');

Troubleshooting

Make sure that the user that PHP is running as can write to the log file you put in the msmtp configuration file. Either make sure it can write to the directory, or create the file (the one in the configuration file, for example /QOpenSys/var/log/msmtp.log) and make sure the PHP user can write to that.

The logs that msmtp writes are detailed, and will often pinpoint the issue exactly (for example, authentication issues). For example, two entries from the msmtp log file:

May 15 19:48:15 host=smtp.example.org tls=on auth=on user=user1@example.com from=example@example.com recipients=sample@example.com smtpstatus=535 smtpmsg='535 5.7.0 Invalid login or password' errormsg='authentication failed (method PLAIN)' exitcode=EX_NOPERM
May 15 19:51:08 host=smtp.example.org tls=on auth=on user=user2@example.com from=example@example.com recipients=sample@example.com mailsize=123 smtpstatus=250 smtpmsg='250 2.0.0 Ok: queued' exitcode=EX_OK

Additional mail options are available as PHP INI mail configuration settings. The most interesting one for debugging is mail.log, because it’ll create a log file for the mail function from the PHP perspective. If you used siteadd with the flag for a custom PHP configuration, it will suggest a place for the mail log in the INI. When the mail.log setting for PHP is configured, that log will provide a mail history:

[16-May-2020 00:32:27 UTC] mail() on [/www/server/htdocs/mailtest.php:13]: To: example@example.com -- Headers:  -- Subject: from PHP RPM

If PHP can’t call sendmail

Check phpinfo() or php -i to make sure sendmail_path is set to /QOpenSys/pkgs/bin/sendmail -t -i . This must be an absolute path with those arguments, so that the sendmail program can be found regardless of the PATH variable, and behave as expected. If not, set it in php.ini.