SMTP mail

SMTP mail sends the mail of WordPress, WooCommerce and every plugin that uses wp_mail() through your own SMTP server instead of PHP mail(). The server address and login live in wp-config.php as constants, never in the database.

SMTP mail keeps no mail log, so password-reset links are never stored. Mail logs have been a way into sites before. Only delivery failures reach the activity log, without the content of the message.

Module ID	smtp
Default	Off
Available	Always. Sending through SMTP also needs SHOUSE_SMTP_HOST in wp-config.php.
WP-CLI	None
Since	0.1.0

How it works

Sending through your server

While the module runs and SHOUSE_SMTP_HOST is set, SafeHouse configures WordPress's mailer (PHPMailer) for every message sent with wp_mail():

• It connects to the host and port from the constants, with the encryption set in SHOUSE_SMTP_SECURE.
• It logs in only when SHOUSE_SMTP_USER is set. Without a user it sends without logging in.
• It sets the envelope sender (where bounces go) to the From address, when that is a valid e-mail address. Bounces and SPF checks then match the sender people see.

SafeHouse's own alert e-mails are sent with wp_mail() too, so they also go through your server.

Without SHOUSE_SMTP_HOST, SafeHouse leaves the mailer alone and mail goes through PHP mail(), as in a standard WordPress. Details then shows:

SMTP is not configured: add SHOUSE_SMTP_HOST (and port, user, password) to wp-config.php. Until then mail goes through PHP mail(); the From settings still apply.

With the host set, Details shows the connection in use, for example SMTP: smtp.example.com:587, with login (from wp-config.php). The password is never shown.

The From address and name

The From settings change only WordPress's placeholder sender.

• From address replaces the sender address only when it starts with wordpress@, the address WordPress uses when nothing else sets one.
• From name replaces the sender name only when it is exactly WordPress.
• Senders set by other code, such as the sender WooCommerce sets for its own e-mails, stay as they are.
• Both apply while the module runs, with or without SHOUSE_SMTP_HOST.

When sending fails

• The message is not sent. SafeHouse does not retry it and does not fall back to PHP mail().
• SafeHouse writes a mail_failed warning to the activity log: "Mail delivery failed: " followed by the error from the mailer. It writes at most one such entry every 10 minutes. Further failures within those 10 minutes are not logged, so a flood of failing mail cannot flood the log.
• There is no mail log, so there is no list of sent or failed messages to look at.
• SafeHouse sets no connection timeout, so PHPMailer's own default applies (300 seconds in the PHPMailer copy that ships with WordPress 7.1). A server that does not answer can hold up the request that sends the mail, such as a checkout or a password reset, until PHPMailer gives up.

Settings

On SafeHouse → Modules → SMTP mail, select Details.

Setting	Default	What it does
From address	Empty	"Used when the sender is not set otherwise (WooCommerce sets its own). Should be on a domain your SMTP server may send for." Up to 190 characters. A value that is not a valid e-mail address is saved as empty, without a warning.
From name	Empty	Replaces the sender name WordPress. Up to 190 characters.

While the module runs, Details also shows the SMTP connection and the Send a test e-mail to me button.

The server settings are constants in wp-config.php:

Constant	Default	What it does
SHOUSE_SMTP_HOST	None	The SMTP server, for example smtp.example.com. Without it, SafeHouse does not use SMTP.
SHOUSE_SMTP_PORT	587	The port.
SHOUSE_SMTP_SECURE	'tls'	'tls' connects unencrypted and then switches to encryption (STARTTLS). 'ssl' encrypts from the start. '' turns encryption off (see Send without encryption).
SHOUSE_SMTP_USER	None	The user name. When set, SafeHouse logs in with it and SHOUSE_SMTP_PASS.
SHOUSE_SMTP_PASS	None	The password. Used only when SHOUSE_SMTP_USER is set.

The names from before the rename, WPHOUSE_SMTP_*, still work (see Upgrade from WPHouse).

Set up SMTP

1. From your mail provider, get the SMTP host, port, encryption, user name and password.
2. In wp-config.php, add the constants (examples below).
3. Go to SafeHouse → Modules.
4. Turn on SMTP mail and select Details.
5. In From address, enter an address on a domain your SMTP server may send for, for example shop@example.com.
6. In From name, enter the name people should see, for example your shop's name.
7. Select Save Changes.

Then send a test e-mail.

For port 587 with STARTTLS:

define( 'SHOUSE_SMTP_HOST', 'smtp.example.com' );
define( 'SHOUSE_SMTP_PORT', 587 );
define( 'SHOUSE_SMTP_SECURE', 'tls' );
define( 'SHOUSE_SMTP_USER', 'shop@example.com' );
define( 'SHOUSE_SMTP_PASS', 'SMTP_PASSWORD' );

For port 465 with encryption from the start:

define( 'SHOUSE_SMTP_HOST', 'smtp.example.com' );
define( 'SHOUSE_SMTP_PORT', 465 );
define( 'SHOUSE_SMTP_SECURE', 'ssl' );
define( 'SHOUSE_SMTP_USER', 'shop@example.com' );
define( 'SHOUSE_SMTP_PASS', 'SMTP_PASSWORD' );

Use 'tls' with port 587 and 'ssl' with port 465. A mismatched pair usually fails to connect. For more on where constants go, see Configure in wp-config.

Send without encryption

To connect without any encryption, for example to a relay on the same server, set SHOUSE_SMTP_SECURE to exactly '':

define( 'SHOUSE_SMTP_HOST', 'localhost' );
define( 'SHOUSE_SMTP_PORT', 25 );
define( 'SHOUSE_SMTP_SECURE', '' );

A value other than 'tls', 'ssl' or '', such as 'none', 'off' or 'TLS' in capitals, does not turn encryption off. PHPMailer's automatic TLS then stays on: the connection starts unencrypted and switches to STARTTLS whenever the server offers it.

Send a test e-mail

The button appears only while the module is Running.

1. Go to SafeHouse → Modules → SMTP mail and select Details.
2. Select Send a test e-mail to me.

SafeHouse sends a message with the subject "SafeHouse test e-mail" and the text "If you can read this, WordPress can send mail." to the e-mail address of your WordPress account. It then shows one of these notices:

• "Test e-mail sent to you@example.com." The message left WordPress without an error. This does not prove delivery: check the inbox and the spam folder.
• "Sending failed: " followed by the error from the mailer, or "unknown error". The notice shows the error even when the 10-minute limit keeps it out of the activity log.

Each test writes a mail_test entry to the activity log: "Test e-mail sent" or "Test e-mail failed".

If the test fails:

• The connection fails: check the host, the port and the encryption. Port 587 goes with 'tls', port 465 with 'ssl'.
• The login fails: check SHOUSE_SMTP_USER and SHOUSE_SMTP_PASS.
• The server refuses the sender: set From address to an address on a domain your SMTP server may send for.

There is no WP-CLI command for a test e-mail.

What it stores

• From address and From name in the option shouse_settings. The server, user name and password stay in wp-config.php only.
• Transient shouse_mail_failed_logged for 10 minutes after a failure is logged. It holds the log back for that time.
• Activity log entries: mail_failed (at most one every 10 minutes) and mail_test.
• No copy of any message, sent or failed.

Limitations

• No mail log, no queue and no retry. A message that fails is lost, and only the first failure in each 10 minutes is logged.
• No fallback to PHP mail() when the SMTP server fails.
• SafeHouse logs in with a user name and password only. A provider that requires OAuth or its own HTTP API needs another plugin.
• SafeHouse sets no SMTP timeout. An unreachable server can hold up the request that sends the mail.
• The From settings change only WordPress's default sender, not senders set by WooCommerce or other plugins.
• SMTP mail does not check for other SMTP plugins. Keep only one plugin that configures mail.
• SHOUSE_SMTP_SECURE set to anything other than 'tls', 'ssl' or '' does not turn encryption off.

Related pages

• Configure in wp-config
• Configuration constants
• Alerts and reports
• Data and privacy
• Upgrade from WPHouse