README

A CakePHP 5.x plugin that intercepts all outgoing emails and redirects them to a specified address. Perfect for development and staging environments where you want to test email functionality without sending emails to real users.

Why Use This Plugin?

When developing or testing applications that send emails, you need a way to prevent emails from reaching real users. There are several approaches:

Paid services like Mailtrap or Mailosaur work great but require subscriptions and external dependencies.

Local tools like Mailpit, MailHog, or MailCatcher are excellent free alternatives, but they require local installation and configuration - which isn't always possible in shared hosting environments, Docker-less setups, or restricted infrastructure.

This plugin offers a zero-infrastructure solution:

• No additional services to install or maintain
• Works with your existing email transport (SMTP, Mailgun, SES, etc.)
• Simple configuration change - just wrap your existing transport
• Ideal for shared staging environments where installing local tools isn't an option
• Perfect for quick local development without setting up additional services

Features

• Redirects all outgoing emails to a single address
• Preserves original recipient information in email headers (X-Original-To, X-Original-Cc, X-Original-Bcc)
• Adds configurable subject prefix to identify intercepted emails
• Optionally includes original recipients in subject line
• Logs all intercepted emails
• Works with any underlying CakePHP mail transport (SMTP, Mailgun, etc.)

Requirements

• PHP 8.1+
• CakePHP 5.0+

Installation

composer require salines/cakephp-mail-interceptor

Load the plugin in your src/Application.php:

use CakeMailInterceptor\CakeMailInterceptorPlugin;

public function bootstrap(): void
{
    parent::bootstrap();
    $this->addPlugin(CakeMailInterceptorPlugin::class);
}

Configuration

Configure the transport in your config/app_local.php:

'EmailTransport' => [
    // Your real transport (used in production)
    'smtp' => [
        'className' => \Cake\Mailer\Transport\SmtpTransport::class,
        'host' => 'smtp.example.com',
        'port' => 587,
        'username' => 'user@example.com',
        'password' => 'secret',
        'tls' => true,
    ],

    // Intercept transport (used in development/staging)
    'default' => [
        'className' => \CakeMailInterceptor\Mailer\Transport\InterceptTransport::class,
        'transport' => 'smtp', // The underlying transport to use
        'to' => 'dev@example.com', // Where all emails will be redirected
        'subjectPrefix' => 'DEV', // Optional: tag for subject line
        'includeOriginalInSubject' => true, // Optional: add original recipients to subject
        'logInterceptions' => true, // Optional: log intercepted emails
    ],
],

Configuration Options

How It Works

When an email is sent through the InterceptTransport:

1. Original recipients (To, Cc, Bcc) are saved to custom headers
2. All recipients are replaced with the configured to address
3. Subject is modified with prefix and/or original recipients
4. Email is sent using the underlying transport
5. Interception is logged (if enabled)

Example

Original email:

• To: user@example.com
• Cc: manager@example.com
• Subject: Your Order Confirmation

Intercepted email:

• To: dev@example.com
• Subject: [DEV: user@example.com] Your Order Confirmation
• Header X-Original-To: user@example.com
• Header X-Original-Cc: manager@example.com

Recommended: Use Plus-Addressed Emails

We recommend using plus-addressed (subaddressed) emails for intercepted mail:

'to' => 'dev+projectname@example.com',
// or with environment identifier
'to' => 'dev+myapp-staging@example.com',

Benefits of plus addressing:

• Easy filtering - Create inbox rules to automatically sort intercepted emails by project or environment
• Quick identification - Instantly see which project/environment an email came from
• Single inbox - Use one email account for all projects without mixing emails
• No extra accounts - No need to create separate email addresses for each project

Most email providers support plus addressing, including Gmail, Outlook, ProtonMail, Fastmail, and others.

Environment-Based Configuration

A common pattern is to use the intercept transport only in non-production environments:

// config/app_local.php
'EmailTransport' => [
    'smtp' => [
        'className' => \Cake\Mailer\Transport\SmtpTransport::class,
        // ... smtp config
    ],
    'default' => env('APP_ENV') === 'production'
        ? [
            'className' => \Cake\Mailer\Transport\SmtpTransport::class,
            // ... production config
        ]
        : [
            'className' => \CakeMailInterceptor\Mailer\Transport\InterceptTransport::class,
            'transport' => 'smtp',
            'to' => 'dev@example.com',
        ],
],

Testing

composer install
composer test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License. See LICENSE for details.