Skip to content
Documentation

The journey of an email

Follow one WordPress email through BooleanSMTP — simulation check, connection choice, API or SMTP, logs — and what happens when a send fails.

Updated View as Markdown

Every email your WordPress site sends — a contact form, a password reset, an order receipt — starts with the WordPress function wp_mail(). BooleanSMTP takes over at that point and decides, in a fixed order, whether and how the message is sent.

The normal path

  1. Simulation check. If Email Simulation Mode is on, the message is recorded and goes no further.
  2. The connection is chosen. A connection the sending code asked for comes first; then the connection that owns the From address; then your Default Connection — or, if none is set, your primary connection. If there is no connection at all, WordPress’s own PHP mail sends it.
  3. It is sent. Amazon SES, Google Workspace and Microsoft Outlook connections in API mode send over the provider’s API; SMTP connections use SMTP, while PHP Mail uses the server’s mail() function.
  4. It is logged when logging is enabled. Email Logs records it as Successful when the send transport reports success; that status does not confirm inbox delivery.

When the provider fails

If the provider refuses the message or cannot be reached, BooleanSMTP tries once more on your Fallback Connection, straight away. If that fails too and Retry on other connections is on (it is by default), the message waits in a queue and is retried on your other active connections — after about a minute, then after five — up to two retries. When nothing is left to try, the log entry is marked Failed and your alert channels are notified.

Step through it

Choose a scenario, then press Play, or step with Previous and Next.

wp_mail()
Simulation check
Choose the connection
Send transport
Alert
Retry queue
Fallback connection
Provider or server
Captured, not sent
Email Logs
Delivery path
Normal send
  1. wp_mail() is called. A contact form, a password reset or an order receipt: every WordPress email starts with wp_mail(), and BooleanSMTP takes over from there.
  2. Simulation check. Email Simulation Mode is off, so the message goes on.
  3. The connection is chosen. A connection the sending code asked for comes first, then the connection that owns the From address, then your Default Connection — or, if none is set, your primary connection. With no connection at all, WordPress’s own PHP mail sends it.
  4. The send transport runs. API-mode connections use the provider’s API, SMTP connections use SMTP, and PHP Mail uses the server’s mail() function.
  5. The transport reports success. The provider or server accepted the send attempt; inbox delivery is still to be confirmed.
  6. It is logged if enabled. With email logging on, Email Logs records the message as Successful.
  7. Check the recipient inbox. The receiving side decides whether to deliver, reject, or filter the email. Check the recipient inbox and spam folder; Successful in Logs alone does not prove delivery.
Provider is down
  1. wp_mail() is called. A contact form, a password reset or an order receipt: every WordPress email starts with wp_mail(), and BooleanSMTP takes over from there.
  2. Simulation check. Email Simulation Mode is off, so the message goes on.
  3. The connection is chosen. A connection the sending code asked for comes first, then the connection that owns the From address, then your Default Connection — or, if none is set, your primary connection. With no connection at all, WordPress’s own PHP mail sends it.
  4. The send transport runs. API-mode connections use the provider’s API, SMTP connections use SMTP, and PHP Mail uses the server’s mail() function.
  5. The send fails. The provider or server rejects the message or cannot be reached: a wrong key, a suspended account, an outage.
  6. One try on the fallback. If an active Fallback Connection is set, BooleanSMTP tries the message once more on it, straight away.
  7. Retries on other connections. If retry is enabled, logging records the failure, and other active connections are available, BooleanSMTP can queue up to two attempts: after about 1 minute, then 5 minutes.
  8. The failure is recorded if logging is on. When nothing is left to try, Email Logs marks a recorded message Failed, with the send error.
  9. You are alerted. Configured, active alert channels can notify you through Slack, Discord or Telegram.
Simulation mode on
  1. wp_mail() is called. A contact form, a password reset or an order receipt: every WordPress email starts with wp_mail(), and BooleanSMTP takes over from there.
  2. Simulation mode is on. Email Simulation Mode is on, so BooleanSMTP stops the message here — before any connection is chosen.
  3. It is logged as Simulated. Email Logs records the message under Simulated, so you can see what would have been sent.
  4. Nothing is sent. No provider ever sees it. A site left in simulation mode is a common reason email never arrives: turn it off in Settings when the site goes live.

Check yourself

Email Simulation Mode is on. Which connection sends the email?
The Default Connection

Not quite. Simulation stops the message before any connection is chosen.

None — it is recorded, not sent

Right. The message is logged under Simulated and never reaches a provider.

PHP mail

Not quite. PHP mail is used only when there is no connection at all — and simulation stops the message even before that.

Your provider rejects a message and a Fallback Connection is set. What happens first?
An alert is sent

Not quite. Alerts come last, when nothing is left to try.

It is retried once on the fallback connection, straight away

Right. The fallback gets one immediate try; the retry queue comes after that.

It waits 15 minutes

Not quite. The queue retries after about 1 minute, then 5 — and only after the immediate fallback try.

Was this helpful?

Documentation

Type to search…

↑↓ navigate↵ selectEsc close