wp-cli-smtp

A WP-CLI command that diverts all outgoing WordPress mail to a local mail catcher (MailHog / Mailpit) by reconfiguring the Fluent SMTP plugin.

Its job is confidence: after you copy a production database to a dev or staging instance, run one command and be sure nobody receives real email from that instance.

What it does

wp smtp capture replaces the site's Fluent SMTP configuration with a single SMTP connection pointing at your catcher, set as both the default and fallback. Because Fluent routes mail by matching the sender against a mapping table — and an exact mapping beats the default — simply adding a catcher connection is not enough; the command wipes existing connections and mappings so no email can escape to a real provider. See docs/adr/0001.

Original From headers are preserved, so your catcher shows what each plugin/theme actually intended to send.

Requirements

• WP-CLI 2.12+
• PHP 7.4+
• Fluent SMTP installed and active on the target site (this command configures it; it does not install it)
• A running MailHog or Mailpit (defaults assume 127.0.0.1:1025)

Usage

# Capture all mail to a local catcher on the default 127.0.0.1:1025
wp smtp capture

# Point at a differently-hosted catcher (e.g. a Docker service named "mailpit")
wp smtp capture --host=mailpit --port=1026

# Configure, then send a test email and report whether the catcher accepted it
wp smtp capture --test

If Fluent SMTP is not active, the command errors and tells you how to install it (wp plugin install fluent-smtp --activate).

On a production environment (WP_ENVIRONMENT_TYPE), the command warns and asks for confirmation first, since it is destructive to the real mail configuration. Pass --yes to skip the prompt in scripted pipelines.

Options

Flag	Default	Description
--host=<host>	127.0.0.1	Catcher SMTP host.
--port=<port>	1025	Catcher SMTP port.
--test	off	Send a test email through wp_mail() after configuring.

Installing

wp package install /path/to/wp-cli-smtp     # or a git URL once published

Development

This package follows the layout of the official wp-cli/scaffold-package-command.

composer install

# Run the command against a WordPress install without "installing" the package:
#   from this directory, wp-cli.yml auto-loads it, or add the require path globally:
#   ~/.wp-cli/config.yml → require: [ /path/to/wp-cli-smtp/wp-cli-smtp.php ]

# Unit tests (pure settings-building logic — no WordPress needed):
vendor/bin/phpunit

The settings-building logic lives in a pure, unit-tested class (src/SmtpSettingsBuilder.php); the command class (src/SmtpCommand.php) is a thin adapter that resolves site defaults, guards production, and persists through Fluent's own helpers (see docs/adr/0002). Command-level behaviour is documented in features/capture.feature, which needs a live WordPress + Fluent SMTP to run.

License

MIT — see LICENSE.