Acorn Mail Laravel Package

Getting Started

This package wires Laravel's mail subsystem (via Acorn) into WordPress, so wp_mail() and the Mail facade both send through your configured transport. On v2.0.0 the prerequisites changed:

• PHP >= 8.3
• Acorn v6 (which pulls in Laravel v13). If you're pinned to Acorn ≤5, stay on v1.0.4 — do not attempt a partial upgrade.

First steps:

1. Require the package via Composer alongside roots/acorn v6, then run wp acorn vendor:publish if you want the mail config in your project.

2. Set your transport in .env. Note the renamed key — MAIL_SCHEME replaces MAIL_ENCRYPTION:

   MAIL_MAILER=smtp
   MAIL_HOST=smtp.example.com
   MAIL_PORT=465
   MAIL_USERNAME=...
   MAIL_PASSWORD=...
   MAIL_SCHEME=ssl
   [email protected]
   MAIL_FROM_NAME="My Site"
   

3. Verify with a one-liner from wp acorn tinker or a mu-plugin: Mail::raw('test', fn ($m) => $m->to('[email protected]')->subject('test')); then confirm the same path works for wp_mail().

Your first real use case is almost always transactional form mail (Gravity Forms, Contact Form 7, a custom handler) pointed at a provider that requires implicit TLS on port 465 — which is precisely the scenario this release fixes.

Implementation Patterns

Keep credentials in .env, never in config/mail.php. Acorn's config layer reads env at boot; committing a published config with hardcoded hosts is the most common source of "works locally, fails in staging."

Route WordPress mail through the Laravel mailer. Rather than calling wp_mail() directly in theme code, use the Mail facade or Mail::raw() in a mu-plugin or Acorn service provider. This gives you Mailable classes, Blade templates, and queueing — none of which the raw wp_mail() API offers.

Use Mailables for multi-recipient or templated flows. Define a Mailable in app/Mail, render a Blade view from resources/views/emails, and send with Mail::to($user)->send(new Receipt($order)). This is where the package earns its keep versus plain WordPress mail.

Queue anything user-triggered. Set QUEUE_CONNECTION to your database or Redis driver and implement ShouldQueue on Mailables so form submissions don't block the request on a slow SMTP handshake. Run wp acorn queue:work under a supervisor.

Per-environment transport switching. A durable pattern is MAIL_MAILER=log in local and smtp in staging/production, driven by .env per environment. This keeps local development free of accidental real sends while exercising identical code paths.

Explicit scheme per port. For port 465 use MAIL_SCHEME=ssl; for 587 use MAIL_SCHEME=tls. If your provider offers both, prefer 587 + tls — it survives more network egress restrictions than implicit 465.

Gotchas and Tips

The MAIL_ENCRYPTION key is now dead. It will not error — it will simply be ignored, and you'll silently fall back to PHPMailer's default, which breaks SSL delivery on port 465. This is exactly the bug fixed in #17. Grep your repos and any deployment .env templates for MAIL_ENCRYPTION and replace it.

Published config/mail.php is the big trap. If you ran vendor:publish on v1.x, your project-local copy still declares 'encryption' => env('MAIL_ENCRYPTION', ...) and will never read MAIL_SCHEME. Re-publish and diff against roots/acorn's config/mail.php, or delete your copy to fall back to the package default. Setting the env var alone will not fix a stale published config.

Check your deployment .env before you deploy. Updating Composer without updating the server's .env produces a green build and broken mail. Treat the env rename as a coordinated release step across every environment, including any secrets manager or CI variable store.

Debugging silent failures. Because the failure mode is a silent fallback rather than an exception, start by dumping the resolved config: wp acorn tinker then config('mail.mailers.smtp'). Confirm the scheme is actually present and correct, not merely that your .env file claims it. If it's missing, you have a stale published config.

PHP 8.3 is a hard floor. Shared hosts on 8.1/8.2 will fatal, not degrade gracefully. Verify php -v on the target server (not just your container) before bumping.

Extension points. Custom transports can be registered in a service provider via Mail::extend('name', fn () => ...) and selected with MAIL_MAILER=name — useful for API-based providers (Postmark, SES HTTP) where SMTP is undesirable. Keep any such registration in a provider that boots after Acorn's mail provider.

Pin deliberately during the transition. If you must ship a hotfix before the Acorn v6 upgrade lands, pin v1.0.4 explicitly in composer.json rather than relying on a caret constraint that will resolve to v2 and break the build.