Prevent stray mails from your Laravel application

This package provides a customizable middleware pipeline for email messages, allowing you to filter, modify, and inspect emails before they are sent.

Key Features:

• Recipient Allowlist Filtering:

  • Filter outgoing email recipients based on a configurable allowlist of domains and specific email addresses.
  • Ideal for staging and testing environments to prevent unintended emails from reaching unintended recipients.
  • Automatically removes recipients not matching the allowlist from the "To", "Cc", and "Bcc" fields.
  • If no valid recipients remain after filtering, the email is canceled to prevent unintended delivery.

• Add Global Recipients:

  • Set default or global "To", "Cc", and "Bcc" recipients via configuration.
  • Ensure certain recipients always receive emails, such as administrators, audit logs, or monitoring addresses.

• Customizable Middleware Pipeline:

  • Utilize a middleware pipeline similar to Laravel's HTTP middleware, but for outgoing emails.
  • Add, remove, or reorder middleware to control the processing of emails.

• Custom Middleware Support:

  • Create your own middleware to implement custom logic for outgoing emails.
  • Modify email content, set headers, add attachments, or perform any email transformation needed.
  • Middleware can inspect emails, log information, or integrate with other services.

Important Note:

This package utilizes Laravel's MessageSending event to inspect and modify outgoing emails. If your application has custom listeners or modifications affecting this event, please thoroughly test the package to ensure it integrates seamlessly and maintains the correct filtering functionality.

Installation

You can install the package via composer:

composer require tobmoeller/laravel-mail-allowlist

You can publish the config file with:

php artisan vendor:publish --tag="mail-allowlist-config"

Your Laravel application will merge your local config file with the package config file. This enables you just to keep the edited config values. Additionally this package provides the ability to configure most of the required values through your environment variables.

Usage

You can configure the package through environment variables:

# Enable the package
MAIL_ALLOWLIST_ENABLED=true

# Define a semicolon separated list of allowed domains
MAIL_ALLOWLIST_ALLOWED_DOMAINS="foo.com;bar.com"

# Define a semicolon separated list of allowed emails
MAIL_ALLOWLIST_ALLOWED_EMAILS="[email protected];[email protected]"

# Define a semicolon separated list of globally added emails
MAIL_ALLOWLIST_GLOBAL_TO="[email protected];[email protected]"
MAIL_ALLOWLIST_GLOBAL_CC="[email protected];[email protected]"
MAIL_ALLOWLIST_GLOBAL_BCC="[email protected];[email protected]"

Customizing the Middleware Pipeline

The package processes outgoing emails through a middleware pipeline, allowing you to customize or extend the email handling logic. By default, the pipeline includes the following middleware:

'middleware' => [
    ToFilter::class;
    CcFilter::class;
    BccFilter::class;
    AddGlobalTo::class,
    AddGlobalCc::class,
    AddGlobalBcc::class,
    EnsureRecipients::class;
],

Reordering or Removing Middleware

The order of middleware in the pipeline matters. Each middleware can modify the email before passing it to the next middleware. You can also reorder or remove middleware from the pipeline to suit your requirements. For example, if you want to disable the BccFilter and want the pipeline to stop right after no recipients remain in the ToFilter, you can adjust the pipeline:

'middleware' => [
    ToFilter::class;
    EnsureRecipients::class; // stops further execution when no recipients remain
    CcFilter::class;
    // BccFilter::class; // disabled
],

Creating Custom Middleware

You can add your own middleware to the pipeline to modify, inspect, or control outgoing emails according to your application's needs. For example, to prevent a mail from being sent on a custom condition, you might create a middleware like this:

use Closure;
use TobMoeller\LaravelMailAllowlist\MailMiddleware\MailMiddlewareContract;
use TobMoeller\LaravelMailAllowlist\MailMiddleware\MessageContext;

class CancelMessageMiddleware implements MailMiddlewareContract
{
    public function handle(MessageContext $messageContext, Closure $next): mixed
    {
        if ($customCondition) {
            // Indicate that the message should be canceled
            $messageContext->cancelSendingMessage('Custom reason');
            // Prevent execution of following middleware
            return null;
        }

        return $next($messageContext);
    }
}

Then add it to your middleware pipeline. This can be done as a class-string which will be instantiated by Laravel's service container or as a concrete instance.

'middleware' => [
    // Upstream middleware
    \App\Mail\Middleware\CancelMessageMiddleware::class, // As a class-string.
    new \App\Mail\Middleware\CancelMessageMiddleware(), // As an instance
    // Downstream middleware
],

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Tobias Möller
• All Contributors

License

The MIT License (MIT). Please see License File for more information.