Documentation · v2.7

Everything the plugin does, unstuck.

If you landed here from the settings screen, you are probably mid-problem. Go straight to the section that matches it; each one ends with the next step rather than a sales pitch.

Documentation · Custom SMTP contents

01 · Getting started

Three steps,
in this order.

Logging starts at activation, before any configuration: from the first minute, the plugin is already recording what your site tries to send.

STEP 01

Install and activate

Plugins, Add New, search for “Custom SMTP”, install, activate. Then open Settings, Custom SMTP. The status bar at the top tells you at any moment whether email delivery is configured.

STEP 02

Pick your provider

Choose your provider from the list and the server, port and encryption fill themselves in. What remains is your username, your password and the sender address, and those three are exactly what the provider guides cover.

STEP 03

Test before trusting

Two buttons: Test Connection checks the server and credentials without sending anything, Send Test Email sends a real message to the address you choose. When either fails, the error is a sentence pointing at the cause, not a numeric code.

Settings · Custom SMTPthe Brevo preset, filled in
The Custom SMTP settings screen with the Brevo preset selected: host, port and encryption filled in automatically, and the green status bar confirming that email delivery is active.

The provider guides

Where the credentials live at Gmail, Brevo, Amazon SES and the eight others, plus the pitfalls each one hides: app passwords, sandboxes, domain authentication.

Pick your provider

02 · Email log

The email log.

Every email sent through wp_mail() gets one row: WooCommerce orders, contact forms, password resets, all of it, whichever plugin sent it.

  • Each row holds the recipient, the subject, the date, the sent-or-failed status, the exact error message when it failed, the headers, and the number of attachments.
  • The message body is stored only if Store Email Content is on. It is on for new installs so the preview works out of the box, and one click in the Email Logging card turns it off. Bodies are capped at 500 KB each.
  • Retention is yours: 30 days by default, adjustable from 1 to 365. A daily task deletes anything older, automatically.
  • Preview and download. Open any logged message in a sidebar to read it as the recipient did, view the HTML source, or download it as a file.
  • Resend a failed message. Fix your configuration, then use Resend on the failed row: the message is rebuilt from the log and sent through your current settings. It needs the body to have been stored, and attachments are not kept, so they are not resent.
  • Export to CSV. The current filter, searched and dated as displayed, streams to a file you can hand to a client or an auditor.

Search covers recipient and subject, filters cover status and date range. When someone says “I never got the email”, this is where the conversation ends.

Email Logssearch, filters, export
The Email Logs screen: counters for sent and failed messages, status and date filters, search, CSV export, and a failed row carrying the exact SMTP error returned by the server.

03 · Alerts

Unusual usage alerts.

A compromised form turns your site into a spam relay; a revoked password stops your order confirmations. Both are silent until someone complains.

Alerts are off by default. Switch them on in the Alerts card, and four rules start watching: more sends than expected in an hour, more than expected in a day, several failures in a row, and too many failures among the last messages sent.

  • Thresholds are absolute, never relative. On a site that sends two emails a week, “three times the usual volume” is statistical noise, and an alert that cries wolf teaches you to ignore it. You set numbers that mean something for your site; the defaults are 20 per hour and 100 per day.
  • Failures are counted over the last sends, not over a time window. A per-hour failure rate would never notice anything on a quiet site. Three consecutive failures alert immediately, even when logging is disabled.
  • Three channels, because email may be the thing that is broken. An email to the address you choose, an optional HTTPS webhook for Slack, Teams or any JSON endpoint, and a persistent notice in wp-admin that stays until you dismiss it.
  • A cooldown keeps an incident from flooding you. One alert per rule per cooldown period, 60 minutes by default. The alert email itself is neither logged nor counted against your thresholds.

The volume rules read the log, so they need logging to stay on. The consecutive-failures rule works without it.

Unusual Usage Alertsthresholds and channels
The Unusual Usage Alerts card: alert email and webhook URL, hourly and daily volume thresholds, consecutive-failure and failure-rate rules, and the cooldown between alerts.

04 · Notifications · new in v2.7

The WordPress
notification switches.

A notice at every password reset, a report after every automatic update, a message for every comment in moderation. Wanted by some, noise for others.

The WordPress Notifications card lists them with one switch each: the password change and new user notices to the administrator, the automatic update reports for core, plugins and themes, and the two comment notifications. Three things worth knowing:

  • Nothing is off by default. Installing or updating the plugin never silences an email your site was already sending.
  • A switched-off notification is never created, so it does not appear in the email log either. If you are hunting the log for an email you switched off yourself, this is why it is not there.
  • Account recovery is out of reach on purpose. The reset link and address change confirmations your users need are not on this screen, so no combination of switches can lock someone out.
WordPress Notificationsone switch per email
The WordPress Notifications card: one switch per automatic email, covering the password reset and new user notices to the administrator, the core, plugin and theme auto-update reports, and the two comment notifications.

05 · Troubleshooting

A send failed.
Read the row first.

Every failed row in the log carries the error message the server returned. It names the cause more precisely than any checklist, so start there, then match it below.

“Could not authenticate”

The server refused your username or password. The most common cause is not a typo: Gmail, Yahoo, iCloud and Zoho with two-factor authentication all refuse the account password and require an app password, and Brevo, SendGrid, Mailjet and Postmark expect a key rather than your login password. Your provider guide says which one and where to create it.

Connection timed out, or connection refused

The request never reached the mail server. Check the host for typos first, then try the provider’s alternate port if it documents one. If nothing gets through on any port, your hosting company may be blocking outbound SMTP connections; their support can confirm it and usually unblock or name the port they allow.

Sender address refused

Wording varies: “email address is not verified” at Amazon SES, “relay access denied” at Mailjet, “sender not allowed” elsewhere. It means the provider does not trust the From address you used. Most transactional providers require the sender address or its whole domain to be verified in their dashboard before they accept a single message, and the From address must match what you verified.

It says sent, but lands in spam

Delivery to the relay worked, so the log shows sent; the receiving side then judged your domain. That judgment is decided by SPF, DKIM and DMARC records in your DNS, not by any plugin. The deliverability section explains all three in plain words.

It says sent, and nothing arrives at all

Check the recipient’s spam folder first, then the provider’s own dashboard: most transactional providers keep their own activity log showing what happened after they accepted the message, including bounces the plugin cannot see. A new Amazon SES account in sandbox mode, for instance, silently accepts only verified recipients.

Starting from the symptom instead?

If the problem is “WordPress isn’t sending emails” and there is no error to match yet, the troubleshooting page walks the diagnosis in order, from the first test to the durable fix.

The troubleshooting page

Constants, environment variables, SES with an IAM role

Every setting can be forced from a PHP constant or an environment variable, and Amazon SES can authenticate with no stored keys at all. That, multisite, and the extension filters live on the developer page.

The developer page

Not answered here?

The support forum on WordPress.org is read and answered. Include the error message from the log if there is one; it usually shortens the thread to one reply.

Support forum