Mails for Filament

To customize the package behavior or the UI, publish the configuration file and the views.

# Publish configuration
php artisan vendor:publish --tag="mails-config"

# Optionally publish views
php artisan vendor:publish --tag="mails-views"

To use the Mails package within a Filament application, you must register the routes and the plugin in your PanelProvider.

Use authenticatedRoutes() to register the mail management routes. This ensures the routes are protected by the panel's authentication.

Then, add the MailsPlugin to the panel.

use Backstage\Mails\Facades\Mails;
use Backstage\Mails\MailsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->authenticatedRoutes(fn () => Mails::routes())
        ->plugin(MailsPlugin::make());
}

Install the package via Composer and run the necessary migrations to set up the database schema.

composer require backstage/mails

php artisan vendor:publish --tag="mails-migrations"
php artisan migrate

You can override the default Filament resources used by the package (such as MailResource, EventResource, or SuppressionResource) by specifying your own classes in the mails config file. Your custom classes must extend the original resource classes.

return [
    'resources' => [
        'mail' => \App\Filament\Resources\MailResource::class,
        'event' => \App\Filament\Resources\EventResource::class,
        'suppression' => \App\Filament\Resources\SuppressionResource::class
    ],
];

The package includes an installation command that automates the initial setup. Running the install command will:

1. Publish the configuration file.
2. Publish the database migrations.
3. Prompt you to run the migrations.
4. Prompt you to star the repository on GitHub.

Note: The package uses spatie/laravel-package-tools for its installation lifecycle.

# The exact command is provided by the package's install command
php artisan mails:install

To integrate mail logging and management into your Filament admin panel, register the MailsPlugin within your panel configuration. The plugin provides access to Mail, Event, and Suppression resources.

By default, the plugin is available to all users. You can restrict access to the mail management features using the canManageMails method.

use Backstage\Mails\MailsPlugin;

// In your Panel Provider
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            MailsPlugin::make(),
        ]);
}

If your application uses multi-tenancy and you want to protect the mail routes with your tenant middleware, use the authenticatedTenantRoutes() method instead of authenticatedRoutes().

use Backstage\Mails\MailsPlugin;
use Backstage\Mails\Facades\Mails;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(MailsPlugin::make())
        ->authenticatedTenantRoutes(fn () => Mails::routes());
}

By default, you can control which users have access to the mail resources and pages by providing a callback to the canManageMails() method on the MailsPlugin.

use Backstage\Mails\MailsPlugin;
use Illuminate\\Support\\Facades\\Auth;

$panel
    ->plugins([
        MailsPlugin::make()
            ->canManageMails(function () {
                $user = Auth::user();

                // Allow access for users with specific roles
                if ($user->hasRole('admin') || $user->hasRole('supervisor')) {
                    return true;
                }

                // Allow access for users with specific permissions
                if ($user->hasPermissionTo('manage mails')) {
                    return true;
                }

                return false;
            }),
    ]);

The plugin uses Laravel configuration to determine which Filament resources to register. You can override the default resource classes by setting the following keys in your config/mails.php file:

• mails.resources.mail: The class for the Mail resource (defaults to Backstage\Mails\Resources\MailResource).
• mails.resources.event: The class for the Event resource (defaults to Backstage\Mails\Resources\EventResource).
• mails.resources.suppression: The class for the Suppression resource (defaults to Backstage\Mails\Resources\SuppressionResource).

The ListEvents page uses a configuration key to determine which class handles the Event resource. You can override the default EventResource class by setting the mails.resources.event key in your Laravel configuration files.

// In your config/mails.php
'resources' => [
    'event' => Your\Custom\EventResource::class,
],

The ListMails page in the Filament admin panel uses a configurable class to represent the Mail resource. You can override the default MailResource by setting the mails.resources.mail configuration key in your Laravel application.

// Example configuration in config/mails.php
'resources' => [
    'mail' => App\Models\YourCustomMailResource::class,
],