Acorn Mail: A Cleaner Way to Configure and Test SMTP in WordPress

Getting WordPress to send mail reliably via SMTP is one of those tasks that looks simple until you need it to work across local dev, staging, and production. You install an SMTP plugin, paste credentials, click “Send test email”, and then… nothing useful. Or worse: it works on one environment and quietly fails on another.

Roots’ new Acorn Mail takes a different approach: configure SMTP via environment variables, automatically wire it into WordPress’ mailer, and give developers a CLI command that actually reports errors when testing email delivery.

Why SMTP plugins are a problem in modern WordPress stacks

SMTP plugins are popular because WordPress doesn’t ship with first-class SMTP configuration. But plugins come with trade-offs that become obvious on professional projects:

• Inconsistent behavior across environments: what works in production may fail in staging due to different network rules, SSL/TLS defaults, or PHP extensions.
• Weak debugging: “test mail” UIs often provide minimal logging, so you don’t know whether DNS, auth, TLS, or the remote server is failing you.
• Security surface area: SMTP plugins add admin screens, settings storage, and code paths that can become liabilities. Some have had real-world vulnerabilities (for example, CVE-2023-6875 is a reminder that mail plugins aren’t immune).
• Credential management pain: copying secrets into wp-admin settings is the opposite of how most teams handle configuration today.

If you already deploy WordPress like an application (Composer dependencies, environment variables, infrastructure-managed secrets), it makes sense for SMTP to follow the same model.

What Acorn Mail does (and where it fits)

Acorn Mail is built to pair with Acorn, Roots’ framework layer for WordPress projects. It focuses on two things:

• Streamlined SMTP configuration using environment variables (no settings pages).
• SMTP testing via CLI so you can verify credentials and get readable error output.

Under the hood, when credentials are present, Acorn Mail hooks into WordPress’ PHPMailer instance. PHPMailer is the library WordPress uses to send email. Instead of replacing WordPress mail, Acorn Mail configures the existing mailer to use SMTP.

Install Acorn Mail with Composer

Acorn Mail is installed as a Composer dependency alongside Acorn:

$ composer require roots/acorn-mail

$ composer require roots/acorn-mail

Configure SMTP via environment variables

Once installed, you configure SMTP by setting environment variables. This plays nicely with platform-provided secrets, container environments, and deploy pipelines:

MAIL_HOST=
MAIL_PORT=
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_FROM_ADDRESS=
MAIL_FROM_NAME=

MAIL_HOST=
MAIL_PORT=
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_FROM_ADDRESS=
MAIL_FROM_NAME=

Acorn Mail detects these values, and as long as they’re not empty, it automatically configures WordPress’ PHPMailer to use SMTP.

Optional: publish a config file for advanced options

If you need more control than the default environment variables provide, Acorn Mail lets you publish its mail.php configuration file:

$ wp acorn mail:config

$ wp acorn mail:config

This is useful when your project needs a more explicit mail configuration story (for example, aligning local defaults, adding environment-specific overrides, or keeping config discoverable for a team).

Test delivery from the CLI (with real error output)

The most developer-friendly feature is the test command. Instead of guessing whether WordPress can reach your SMTP server, you can verify it directly from the environment you care about (local container, staging box, production instance):

$ wp acorn mail:test [--to=]

$ wp acorn mail:test [--to=]

The command sends a test email to the address you specify and surfaces errors along the way. That means faster diagnosis when the issue is TLS negotiation, authentication, blocked ports, or a misconfigured host value.

When Acorn Mail is a good fit

Acorn Mail makes the most sense if you already run a modern Roots-style WordPress stack—Composer-managed dependencies, environment-based configuration, and WP-CLI as part of your workflow.

• You want consistent SMTP config across dev/staging/prod without clicking through wp-admin settings.
• You want a repeatable, scriptable test you can run while provisioning servers or debugging deliverability.
• You prefer reducing reliance on SMTP plugins that add admin UI and extra attack surface.

Wrap-up

SMTP shouldn’t be one of the most fragile parts of a WordPress project. Acorn Mail moves email configuration closer to how the rest of modern WordPress infrastructure works: environment variables for credentials, automatic PHPMailer wiring, and a CLI command that makes failures visible.