Weave Code
Acorn Mail Laravel Package
roots/acorn-mail
Bring Laravel’s Mail system to WordPress via Acorn. Send email with familiar Mailables, mailers, and Blade templates, configure SMTP and other transports, and use Laravel-style mail APIs inside your Acorn-powered theme or plugin.
Simple WordPress SMTP using Acorn.
Frequently asked questions about Acorn Mail
- How do I install roots/acorn-mail in a Laravel Acorn WordPress theme?
- Install it with Composer from your project root using composer require roots/acorn-mail. It is designed for Acorn-powered Roots stacks such as Sage, Bedrock, and Trellis, where Acorn boots Laravel-style services inside WordPress. v2.0.0 requires Acorn v6, Laravel 13, and PHP 8.3 or newer, so confirm your stack matches before requiring it. If you are on Acorn 5 or earlier, pin the older v1.0.4 line instead.
- Does roots/acorn-mail work with Acorn 5 or Sage 10?
- No, v2.0.0 is hard-coupled to Acorn v6, Laravel 13, and PHP 8.3 or newer. Projects still on Acorn 5 or earlier must pin roots/acorn-mail to 1.0.4 rather than using a floating constraint. Avoid open-ended constraints such as * or ^1 || ^2 because Composer may resolve v2.0.0 onto an incompatible stack.
- How do I configure SMTP for WordPress with roots/acorn-mail?
- Set MAIL_MAILER to smtp and provide MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_FROM_ADDRESS, and MAIL_FROM_NAME in your Bedrock .env file. On v2.0.0 use MAIL_SCHEME for TLS/SSL selection because MAIL_ENCRYPTION has been renamed. The package passes that configuration into Laravel's mail transport, so sends go through your SMTP provider instead of PHPMailer defaults. Keep environment values consistent across local, staging, CI, and Trellis-provisioned environments.
- Why does SMTP on port 465 fail or fall back to PHPMailer after upgrading roots/acorn-mail?
- The bug fixed in v2.0.0 involved SMTP sends falling back to PHPMailer defaults, which broke SSL on port 465 and could make mail appear sent but never arrive. The fix depends on MAIL_SCHEME, so an old MAIL_ENCRYPTION variable or a stale published config/mail.php can keep the failure silent. Check that config/mail.php is republished or diffed against the upstream Acorn version in the same change as the package bump. Also update CI secrets, Trellis vault entries, and deployment manifests, not just .env.
- Can I use Laravel Mailables and Blade templates for WordPress emails with roots/acorn-mail?
- Yes, the package brings Laravel's Mail API into Acorn, so you can send mail with Mailables, mailers, the Mail facade, and Blade-rendered templates inside a Sage theme or plugin. It is a thin configuration and integration layer over Laravel's mail transport rather than a custom mailer, so familiar Laravel behavior applies. Blade views are rendered through Acorn's view layer, which keeps email markup consistent with the rest of your Laravel-style code.
- Do I need to publish config/mail.php when using roots/acorn-mail?
- You do not have to publish config/mail.php for the package to work, but any project that ran vendor:publish keeps a local copy that can drift from the upstream defaults. That matters most on v2.0.0 because a published file keyed on MAIL_ENCRYPTION makes the MAIL_SCHEME fix silently inert. If you have a published copy, republish or diff it against the upstream Acorn version as part of the upgrade. Detect published configs in each repository with a git ls-files config/mail.php check before rolling out the version bump.
- Is roots/acorn-mail a replacement for WP Mail SMTP?
- It solves a similar problem but takes a different approach: instead of a WordPress admin plugin, it routes mail through Laravel's mail transport configured by Acorn. That suits Roots projects that already use .env-based configuration and want Mailables and Blade email templates in code. It has little surface area and no admin UI, so teams expecting a settings screen or delivery logs from a plugin should plan for that separately. You can also remove it and inline the mail configuration if you prefer.
- How do I test emails sent from WordPress with roots/acorn-mail?
- Use Mail::fake in automated tests to assert that Mailables are sent without hitting a real transport. For manual and integration testing, point MAIL_MAILER at a local catcher such as Mailpit or the log driver so you can inspect rendered Blade output. Keep real SMTP credentials out of CI and test that your .env, CI secrets, and Trellis templates resolve the same MAIL_SCHEME value. A quick send test on port 465 is worth running after any upgrade because the failure mode can be silent.
- What PHP and Laravel versions does roots/acorn-mail v2.0.0 require?
- v2.0.0 requires Acorn v6, which brings Laravel 13 and a PHP floor of 8.3 or newer. That is a triple-lock upgrade, so verify PHP, Acorn, and Laravel versions together before changing the Composer constraint. Sites that cannot meet the PHP 8.3 requirement should stay on the v1.0.4 track. Document the two tracks internally so a shared config template does not mix them.
- How do I upgrade roots/acorn-mail from v1.0.4 to v2.0.0 safely?
- Start with an inventory of every project's Acorn version, PHP version, Composer constraint, and whether config/mail.php is published. Then constrain Composer to ^2.0 for upgraded projects and exact 1.0.4 for projects remaining on Acorn 5 or earlier. Rename MAIL_ENCRYPTION to MAIL_SCHEME everywhere: .env files, .env.example, CI secrets, Trellis vault entries, and deployment manifests. Do the config republish or diff in the same change as the version bump, and keep MAIL_ENCRYPTION only as a short-lived transition aid.
Weaver
How can I help you explore Laravel packages today?