Filament Mail

https://github.com/jeffersongoncalves/filament-mail
Admin
Filament Mail is a complete email management plugin for Filament that provides mail logging,...
Tokens:6,529
Snippets:57
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install filament-mail with Composer

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Install the filament-mail package via Composer. This is the first step in the installation process.

```bash
composer require jeffersongoncalves/filament-mail
```

--------------------------------

### Custom Editor Driver Implementation

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/resources/boost/skills/filament-mail-development/SKILL.md

Example of creating a custom driver by implementing the TemplateEditorContract.

```php
use JeffersonGoncalves\FilamentMail\Contracts\TemplateEditorContract;

class MyCustomEditorDriver implements TemplateEditorContract
{
    public function getFormField(string $fieldName = 'html_body'): Component
    {
        return MyCustomField::make($fieldName)->columnSpanFull();
    }

    public function render(string $content, array $variables): string
    {
        // Replace {{variable}} and {{ variable }} patterns
        foreach ($variables as $key => $value) {
            $content = str_replace(
                ['{{' . $key . '}}', '{{ ' . $key . ' }}'],
                (string) $value,
                $content
            );
        }
        return $content;
    }
}
```

--------------------------------

### Publish filament-mail config file

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Optionally publish the configuration file for filament-mail. This step is not required for basic installation.

```bash
php artisan vendor:publish --tag="filament-mail-config"
```

--------------------------------

### Disable FilamentMailPlugin features

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Disable specific features by passing false to the corresponding methods. This example disables suppression management, analytics charts, and the dashboard page.

```php
FilamentMailPlugin::make()
    ->mailSuppressionResource(false)  // Disable suppression management
    ->analyticsWidget(false)          // Disable analytics charts
    ->dashboard(false)                // Disable dashboard page
```

--------------------------------

### Publish and Run Filament Mail Migrations

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Publish and run the migrations required when using the Unlayer editor. The migration adds the 'body_design' column.

```bash
php artisan vendor:publish --tag="filament-mail-migrations"
php artisan migrate
```

--------------------------------

### Run tests with composer test

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Run the test suite for the package using Composer.

```bash
composer test
```

--------------------------------

### Create Template and Send Notification with MailNotification

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/resources/boost/skills/filament-mail-development/SKILL.md

Creates a mail template with key 'order.confirmed' and sends a notification using MailNotification. The template uses placeholders {{order_id}} and {{name}} in subject and body. Ensure the template key exists and is_active is true before sending.

```php
// 1. Create template in Filament UI or via seeder
MailTemplate::create([
    'key' => 'order.confirmed',
    'name' => 'Order Confirmation',
    'subject' => 'Order #{{order_id}} confirmed',
    'html_body' => '<h1>Thank you, {{name}}!</h1><p>Order #{{order_id}} is confirmed.</p>',
    'is_active' => true,
]);

// 2. Send notification
$user->notify(new MailNotification('order.confirmed', [
    'name' => $user->name,
    'order_id' => $order->id,
]));
```

--------------------------------

### Unlayer Migration Command

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/resources/boost/skills/filament-mail-development/SKILL.md

Command to publish migrations when using the Unlayer editor.

```bash
php artisan vendor:publish --tag="filament-mail-migrations"
```

--------------------------------

### Create Multi-locale Template and Send with Locale Option

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/resources/boost/skills/filament-mail-development/SKILL.md

Creates a multi-locale mail template with translations for English and Portuguese (pt_BR). Sends the notification in Portuguese by passing the 'locale' option to MailNotification. The template key 'auth.welcome' must be active.

```php
$template = MailTemplate::create([
    'key' => 'auth.welcome',
    'name' => 'Welcome',
    'subject' => ['en' => 'Welcome!', 'pt_BR' => 'Bem-vindo!'],
    'html_body' => ['en' => '<h1>Welcome {{name}}</h1>', 'pt_BR' => '<h1>Bem-vindo {{name}}</h1>'],
    'is_active' => true,
]);

// Send in Portuguese
$user->notify(new MailNotification('auth.welcome', ['name' => $user->name], ['locale' => 'pt_BR']));
```

--------------------------------

### Publish and run laravel-mail migrations

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Publish and run the migrations for the required laravel-mail dependency. The package depends on jeffersongoncalves/laravel-mail, so these migrations must be run first.

```bash
php artisan vendor:publish --tag="laravel-mail-migrations"
php artisan migrate
```

--------------------------------

### Configure Filament Mail (config/filament-mail.php)

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Configuration file for the Filament Mail package. Controls which resources, widgets, dashboard, navigation, template editor, preview, and tenant scoping are enabled. The template editor driver defaults to 'rich_editor' and can be overridden via the FILAMENT_MAIL_EDITOR environment variable.

```php
// config/filament-mail.php

return [
    'resources' => [
        'mail_log' => [
            'enabled' => true,
            'label' => 'Mail Log',
            'plural_label' => 'Mail Logs',
        ],
        'mail_template' => [
            'enabled' => true,
            'label' => 'Mail Template',
            'plural_label' => 'Mail Templates',
        ],
        'mail_suppression' => [
            'enabled' => true,
            'label' => 'Suppression',
            'plural_label' => 'Suppressions',
        ],
    ],

    'widgets' => [
        'stats_overview' => true,
        'analytics_chart' => true,
        'delivery_rate_chart' => true,
    ],

    'dashboard' => [
        'enabled' => true,
    ],

    'navigation' => [
        'group' => 'Email',
        'icon' => 'heroicon-o-envelope',
        'sort' => 50,
    ],

    'template_editor' => [
        'driver' => env('FILAMENT_MAIL_EDITOR', 'rich_editor'),
        'locales' => ['en'],
        'default_locale' => 'en',
        'unlayer_project_id' => env('UNLAYER_PROJECT_ID'),
        'merge_tags' => [],
    ],

    'preview' => [
        'max_width' => '800px',
        'sandbox' => true,
    ],

    'tenant_scoping' => false,
];
```

--------------------------------

### Filament Mail Configuration

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/resources/boost/skills/filament-mail-development/SKILL.md

Environment variables to configure the active editor driver and Unlayer project ID.

```text
FILAMENT_MAIL_EDITOR=rich_editor  # or 'unlayer'
UNLAYER_PROJECT_ID=your-project-id
```

--------------------------------

### Register Custom Editor Driver

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/resources/boost/skills/filament-mail-development/SKILL.md

Binding the custom driver in a service provider.

```php
$this->app->bind(TemplateEditorContract::class, MyCustomEditorDriver::class);
```

--------------------------------

### Extend Filament Mail resources via config

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Extend the default Filament Mail resources by creating a custom resource class and updating the 'resources' configuration in config/filament-mail.php. The 'mail_log' key maps to the custom class.

```php
// config/filament-mail.php
'resources' => [
    'mail_log' => [
        'class' => App\Filament\Resources\CustomMailLogResource::class,
    ],
],
```

--------------------------------

### Customize FilamentMailPlugin with navigation and feature toggles

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Customize the plugin by chaining methods to set navigation group, icon, sort order, and enable or disable resources, widgets, dashboard, and tenant scoping. Each method accepts a boolean to toggle the feature.

```php
FilamentMailPlugin::make()
    ->navigationGroup('Email')
    ->navigationIcon('heroicon-o-envelope')
    ->navigationSort(50)
    ->mailLogResource()           // Enable/disable mail log resource
    ->mailTemplateResource()      // Enable/disable template resource
    ->mailSuppressionResource()   // Enable/disable suppression resource
    ->statsWidgets()              // Enable/disable stats widgets
    ->analyticsWidget()           // Enable/disable analytics charts
    ->dashboard()                 // Enable/disable dashboard page
    ->tenantScoping()             // Enable/disable tenant scoping
```

--------------------------------

### Locale-aware Template Getters

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/resources/boost/skills/filament-mail-development/SKILL.md

Retrieving template content for specific locales.

```php
$template->getSubjectForLocale('pt_BR');
$template->getHtmlBodyForLocale('en');
```

--------------------------------

### MailNotification

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Send emails using database templates with variable binding.

```APIDOC
## MailNotification

### Description
Send emails using database templates with variable binding.

### Method
notify

### Endpoint
MailNotification::notify

### Parameters
#### Constructor Parameters
- **templateKey** (string) - Required - The key of the database template to use.
- **variables** (array) - Required - Associative array of variables to bind to the template.
- **metadata** (array) - Optional - Additional metadata such as locale, cc, and attachments.

### Request Example
```php
$user->notify(new MailNotification(
    templateKey: 'auth.welcome',
    variables: [
        'name' => $user->name,
        'login_url' => route('login'),
    ],
));
```

### Response
#### Success Response
- Notification sent successfully.

#### Response Example
No response body returned.
```

--------------------------------

### TemplateEditorContract Interface

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/resources/boost/skills/filament-mail-development/SKILL.md

The core interface for implementing custom email template editors in Filament Mail.

```php
use JeffersonGoncalves\FilamentMail\Contracts\TemplateEditorContract;

interface TemplateEditorContract
{
    public function getFormField(string $fieldName = 'html_body'): Component;
    public function render(string $content, array $variables): string;
}
```

--------------------------------

### Send MailNotification with template variables

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Send emails using database templates with variable binding. Supports simple notifications, locale, cc, attachments, and routing via the Notification facade.

```php
use JeffersonGoncalves\FilamentMail\Notifications\MailNotification;

// Simple notification
$user->notify(new MailNotification(
    templateKey: 'auth.welcome',
    variables: [
        'name' => $user->name,
        'login_url' => route('login'),
    ],
));

// With locale, cc, and attachments
$user->notify(new MailNotification(
    templateKey: 'transactional.invoice',
    variables: [
        'invoice_number' => $invoice->number,
        'total' => number_format($invoice->total, 2, ',', '.'),
        'due_date' => $invoice->due_date->format('d/m/Y'),
    ],
    metadata: [
        'locale' => 'pt_BR',
        'cc' => ['finance@company.com'],
        'attachments' => [storage_path("invoices/{$invoice->number}.pdf")],
    ],
));

// Without a notifiable (via Notification facade)
use Illuminate\Support\Facades\Notification;

Notification::route('mail', $email)->notify(
    new MailNotification('auth.reset-password', ['url' => $resetUrl])
);
```

--------------------------------

### Set Template Editor via Environment Variables

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Environment variables to select the template editor driver. Set FILAMENT_MAIL_EDITOR to 'rich_editor' (default) or 'unlayer' for the visual drag-and-drop editor. When using Unlayer, also set UNLAYER_PROJECT_ID.

```env
# Default: standard Filament RichEditor
FILAMENT_MAIL_EDITOR=rich_editor

# Visual drag-and-drop editor via Unlayer
FILAMENT_MAIL_EDITOR=unlayer
UNLAYER_PROJECT_ID=your-project-id
```

--------------------------------

### Create Custom Template Editor Driver

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Custom template editor driver implementing TemplateEditorContract. The getFormField method returns a custom form field, and render replaces merge tags in the content. Bind the driver in a service provider using $this->app->bind().

```php
use JeffersonGoncalves\FilamentMail\Contracts\TemplateEditorContract;

class MyEditorDriver implements TemplateEditorContract
{
    public function getFormField(string $fieldName = 'html_body'): Component
    {
        return MyCustomField::make($fieldName)->columnSpanFull();
    }

    public function render(string $content, array $variables): string
    {
        foreach ($variables as $key => $value) {
            $content = str_replace(
                ['{{' . $key . '}}', '{{ ' . $key . ' }}'],
                (string) $value,
                $content
            );
        }
        return $content;
    }
}

// In a service provider:
$this->app->bind(TemplateEditorContract::class, MyEditorDriver::class);
```

--------------------------------

### Register FilamentMailPlugin with SpatieTranslatablePlugin

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Register the FilamentMailPlugin in your Filament panel provider. The SpatieTranslatablePlugin is required for multi-locale template editing and provides a locale switcher in the header of all template pages. Configure the locales you need in the defaultLocales() method.

```php
use JeffersonGoncalves\FilamentMail\FilamentMailPlugin;
use LaraZeus\SpatieTranslatable\SpatieTranslatablePlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentMailPlugin::make(),

            // Required for multi-locale template editing
            SpatieTranslatablePlugin::make()
                ->defaultLocales(['en', 'pt_BR', 'es']),
        ]);
}
```

--------------------------------

### Sending MailNotification

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/resources/boost/skills/filament-mail-development/SKILL.md

Sending an email notification with template keys, variables, and metadata.

```php
use JeffersonGoncalves\FilamentMail\Notifications\MailNotification;

$user->notify(new MailNotification(
    templateKey: 'auth.welcome',
    variables: ['name' => $user->name, 'login_url' => route('login')],
    metadata: [
        'locale' => 'pt_BR',
        'cc' => ['admin@company.com'],
        'bcc' => ['archive@company.com'],
        'reply_to' => 'support@company.com',
        'attachments' => [storage_path('file.pdf')],
    ],
));
```

--------------------------------

### HasMailTemplate Trait

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/README.md

Trait for traditional Mailables to build content from database templates.

```APIDOC
## HasMailTemplate Trait

### Description
Use the HasMailTemplate trait for traditional Mailables to build content from database templates.

### Method
buildContent

### Endpoint
Mailable::buildContent

### Parameters
#### Properties
- **templateKey** (string) - Required - The key of the database template to use.
- **templateVariables** (array) - Required - Associative array of variables to bind to the template.

### Request Example
```php
class WelcomeMail extends Mailable
{
    use HasMailTemplate;

    public function __construct(User $user)
    {
        $this->templateKey = 'auth.welcome';
        $this->templateVariables = ['name' => $user->name];
    }

    public function build(): static
    {
        return $this->buildContent();
    }
}
```

### Response
#### Success Response
- Returns the Mailable instance with content built from the template.

#### Response Example
No response body returned.
```

--------------------------------

### HasMailTemplate Trait Usage

Source: https://github.com/jeffersongoncalves/filament-mail/blob/3.x/resources/boost/skills/filament-mail-development/SKILL.md

Implementing the HasMailTemplate trait in a Mailable class.

```php
use JeffersonGoncalves\FilamentMail\Traits\HasMailTemplate;

class InvoiceMail extends Mailable
{
    use HasMailTemplate;

    public function __construct(Invoice $invoice)
    {
        $this->templateKey = 'billing.invoice';
        $this->templateVariables = [
            'number' => $invoice->number,
            'total' => $invoice->formatted_total,
        ];
        $this->templateLocale = 'pt_BR'; // optional
    }

    public function build(): static
    {
        return $this->buildContent();
    }
}
```
Tokens:
Raw