Download the PHP package wp-spaghetti/wp-mail-transport without Composer

WP Mail Transport

Symfony Mailer transport that uses WordPress's wp_mail() function, allowing you to use Laravel's Mail facade while leveraging WordPress email plugins.

Works with any Laravel + WordPress setup: Acorn (w/wo Sage), WP Starter, Corcel, or custom integrations.

Features

• Clean Laravel Syntax - Use Mail::to(), Mail::send(), etc. anywhere in your code
• WordPress Plugin Support - Works seamlessly with WP Mail SMTP, SendGrid, Mailgun, and other WP email plugins
• Zero Configuration - Works out of the box with sensible defaults
• Framework Agnostic - Not tied to Acorn, works across different Laravel+WordPress stacks
• Full Symfony Mailer API - Support for attachments, HTML emails, CC, BCC, custom headers

Requirements

• PHP >= 8.2
• WordPress >= 6.0
• Laravel Illuminate/Support ^10.0|^11.0|^12.0|^13.0
• Symfony Mailer ^6.0|^7.0

Installation

1. Install the package

In your Laravel + WordPress project (Sage theme, WP Starter, etc.):

The package auto-registers via service provider discovery.

2. Configure mail transport

Update your config/mail.php:

3. Set environment variable

Update your .env:

That's it! The transport will now use WordPress's wp_mail() function.

Usage

Basic Email

Using Mailables

HTML Emails

With Attachments

Multiple Recipients

Custom Headers

Framework-Specific Examples

Sage Themes (Acorn)

WP Starter

Corcel

How It Works

Architecture

Technical Details

Email Conversion:

• Converts Symfony Message to Email object
• Extracts headers, recipients, subject, body
• Handles HTML and plain text bodies
• Processes attachments

Header Handling:

• Filters out headers that wp_mail() adds automatically (From, To, Subject, Content-Type)
• Preserves custom headers (CC, BCC, Reply-To, X-* headers)
• Properly formats From header with name and address

Attachment Processing:

• Creates temporary files for attachments
• Passes file paths to wp_mail()
• Cleans up temporary files after sending

Error Handling:

• Throws TransportException if sending fails
• Proper exception chaining for debugging
• Graceful cleanup on errors

WordPress Plugin Integration

The transport automatically works with popular WordPress email plugins:

WP Mail SMTP

Configure WP Mail SMTP in WordPress admin, then use Laravel's Mail facade normally:

SendGrid Plugin

Install and configure the SendGrid WordPress plugin:

Mailgun Plugin

Configure Mailgun in WordPress, then:

Advanced Configuration

Publish Configuration (Optional)

This creates config/wp-mail.php with debugging options:

Debug Mode

Enable debug logging to troubleshoot email delivery issues:

In .env:

Or in config/wp-mail.php:

What gets logged:

• Email recipients
• Subject line
• Content type (HTML or plain text)
• Number of headers
• Number of attachments
• wp_mail() success/failure status
• Exception details if sending fails

Logging System: Debug messages are logged using Laravel's Log facade at the debug level. Configure logging in config/logging.php:

Log Format: Laravel automatically formats logs with timestamp and context:

Log Channels: You can specify different log channels in config/logging.php:

• single - Single file
• daily - Daily rotating files
• slack - Send to Slack
• syslog - System log
• errorlog - PHP error log
• stack - Multiple channels

Note: Debug mode logs sensitive information (email addresses). Only enable in development or when troubleshooting specific issues.

Multiple Mailers

You can use multiple transports in the same application:

Then switch between them:

Custom From Address

Set globally in config/mail.php:

Or per-email:

Troubleshooting

Emails not being sent

1. Check if wp_mail() is working:

2. Check WordPress email plugins:

   • Ensure WP Mail SMTP or similar plugin is configured
   • Test sending from WordPress admin
3. Enable debug mode:

With debug mode enabled, the transport will log detailed information about each email using Laravel's logging system. Check your logs in storage/logs/laravel.log:

What gets logged:

• Recipients
• Subject
• Content type (HTML/plain text)
• Number of headers
• Number of attachments
• Success/failure status

Example debug output:

Configure logging channels in config/logging.php to send logs to different destinations (files, Slack, syslog, etc.).

Attachments not working

Ensure your WordPress upload directory is writable:

Custom headers not appearing

Some WordPress email plugins may strip custom headers. Check your plugin's settings or filters.

From address being overridden

WordPress plugins may force a specific From address. Check:

Testing

Comparison with Other Solutions

Changelog

Please see CHANGELOG for a detailed list of changes for each release.

We follow Semantic Versioning and use Conventional Commits to automatically generate our changelog.

Release Process

• Major versions (1.0.0 → 2.0.0): Breaking changes
• Minor versions (1.0.0 → 1.1.0): New features, backward compatible
• Patch versions (1.0.0 → 1.0.1): Bug fixes, backward compatible

All releases are automatically created when changes are pushed to the main branch, based on commit message conventions.

Contributing

For your contributions please use:

• Conventional Commits
• Pull request workflow

See CONTRIBUTING for detailed guidelines.

Sponsor

License

(ɔ) Copyleft 2026 Frugan.
GNU GPLv3, see LICENSE file.