Download the PHP package tobmoeller/laravel-mail-allowlist without Composer

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 as well as inspecting just sent emails.

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.
  • You can define custom middleware that runs before or after an email is sent.
• Advanced Logging Options:
  • Configure logging to use custom channels.
  • Set custom log levels (e.g., 'debug', 'info', 'error', etc.).
  • Enable mail middleware to add individual log messages during email processing.
  • Choose whether to include middleware logs, email message headers, message meta data or message bodies in the logs.
  • Write logs for messages that are about to be sent and for messages that have just been sent.

Important Note:

This package utilizes Laravel's MessageSending and MessageSent events 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:

You can publish the config file with:

Your Laravel application will merge your local config file with the package config file. This enables you to just keep the edited configuration 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:

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:

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:

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:

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.

Custom Middleware for already sent emails

You can add custom middleware to the sent pipeline to run custom logic on the sent emails like creating database records. The process is similar to the sending middleware but requires you to implement the MailSentMiddlewareContract interface in your middleware class.

Customizing the Logging Behavior

You can control most of the logging behavior from environment variables or the configuration file. For more advanced use cases, you might want to have full control over how log messages are generated and where they are sent. You can achieve this by binding your own implementations of the log content generation action and/or the logging action itself.

Customizing the log message content

Create a new class that implements GenerateLogMessageContract to define how log messages are generated:

Customizing the log creation

Create a new class that implements LogMessageContract to define how log messages are handled:

Binding Custom Implementations

To instruct Laravel to use your custom classes, you need to bind them in your application's service container. This is typically done in a service provider like App\Providers\AppServiceProvider.

Customize the behavior after an email is sent

Customizing the logging for already sent mails is similar to customizing the logging of outgoing mails. You have to bind your custom implementations of the SentLogMessageContract and GenerateSentLogMessageContract interfaces in a service provider.

Testing

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.