# Troubleshooting

> Common BooleanSMTP problems with their cause and their fix — emails not sending, a failed send not retrying, and a connection that won't authenticate.

## 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](/learn/nothing-arrived/).

## "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:

   ```bash
   wp boolean-smtp queue:work --retry
   ```

See <DevLink path="/wp-cli/">the WP-CLI reference</DevLink> 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](/sending/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.