Troubleshooting

Emails aren’t sending

Cause: usually a connection that isn’t active, or credentials the provider has rejected.

1. Open Email Logs and find the message. Its status and error message say what the provider said.
2. Open the connection it should have used, under Mailers, and confirm it’s switched on.
3. Click Verify credentials (or Re-verify credentials) on the connection to re-check them against the provider.
4. Still stuck? Turn on Log mailer resolution to PHP error log in Settings → Logging & Retention, send the email again, and check your server’s PHP error log for the line tagged [boolean-smtp] — it says which connection and transport BooleanSMTP chose.

The test said it sent, but nothing arrived

Test email sent successfully! only means your provider accepted the message — not that it reached the inbox. Check the spam folder first. If it’s genuinely missing, see why an accepted email doesn’t arrive.

“Authentication failed” in the logs

Cause: wrong or expired credentials, or a provider security setting blocking BooleanSMTP.

1. Re-enter the credential fields on the connection — don’t leave a masked placeholder in place, retype it.
2. For an OAuth connection (Google Workspace, Microsoft Outlook), see the next section.
3. For SMTP, confirm the provider still allows the authentication method you’re using; some providers require an app-specific password rather than your account password.

An OAuth connection stopped sending

Cause: almost always that the provider revoked access — a changed password, a removed app permission, a security review — not a one-off refresh glitch. Tokens refresh automatically in the background before every send, so you don’t need to trigger that yourself.

1. Open the connection and click Authorize (shown as Reconnect account once it’s connected once before) to get a fresh token.
2. Send a test email from the connection to confirm it’s healthy again.

Connection timeout

Cause: your server, or a firewall between it and the provider, is blocking the connection.

1. Confirm your host allows outbound connections on the port your connection uses.
2. Click Verify credentials on the connection to retest it.
3. Ask your hosting provider whether they restrict outbound SMTP or the port your provider needs.

A failed email isn’t being retried

Only a message that already failed is ever queued, and only when Retry on other connections is on (Settings → Delivery & Reliability) — there’s no setting that queues every email.

1. Open the message in Email Logs and check its attempts for the retry’s own error.

2. To send whatever is due right now, including a backlog of failed messages, instead of waiting for WordPress’s cron to catch up, run:

   wp boolean-smtp queue:work --retry

See the WP-CLI reference for this and BooleanSMTP’s other commands.

“… already sends through ‘…’”

Cause: each From address belongs to one connection. Saving a connection, or switching one on, with an address another connection already owns is refused, naming that connection.

Open the connection the message names and either change its provider there, or give one of the two connections a different From address. See One connection per sender for the full rule.

“Page not found” in BooleanSMTP

The address you opened has no page — usually an old bookmark. The message on screen says why. Click Go to Overview to get back.

The Migration screen has no sidebar entry but does exist: press ⌘K (Mac) or Ctrl K (Windows and Linux) anywhere in BooleanSMTP, type Migration, and press Enter.

Diagnostic tools

• Log mailer resolution to PHP error log (Settings → Logging & Retention) — writes one JSON line per email to your server’s PHP error log, showing which connection and transport were chosen.
• SMTP Debug Level, on an SMTP connection’s own edit form — set it to capture the raw SMTP conversation for that connection’s sends.
• Test Email Activity Console (Settings → Testing & Content) — shows the SMTP handshake on the Test Email page for a manual test send, without changing any other setting.

Turn diagnostic logging back off once you’re done — it adds overhead to every send.