Filament Mail Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require jeffersongoncalves/filament-mail
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="JeffersonGoncalves\FilamentMail\FilamentMailServiceProvider" --tag="filament-mail-config"
   php artisan vendor:publish --provider="JeffersonGoncalves\FilamentMail\FilamentMailServiceProvider" --tag="filament-mail-assets"
   

2. Run Migrations

   php artisan migrate
   

3. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   return [
       // ...
       'plugins' => [
           \JeffersonGoncalves\FilamentMail\FilamentMailPlugin::make(),
       ],
   ];
   

4. First Use Case

   • Navigate to the Mail section in Filament.
   • Use the Templates tab to create a new email template (supports multi-locale editing).
   • Send a test email via the Logs tab to verify the workflow.

Implementation Patterns

Core Workflows

1. Template Management

   • Create/Edit Templates: Use the WYSIWYG editor for HTML content with multi-locale support (e.g., en, pt).

     // Define a template in a migration or seeder
     \JeffersonGoncalves\LaravelMail\Models\Template::create([
         'name' => 'Welcome Email',
         'subject' => 'Welcome to Our Platform',
         'html' => '<h1>Hello, {name}!</h1>',
         'locales' => json_encode(['en' => ['subject' => 'Welcome...'], 'pt' => ['subject' => 'Bem-vindo...']]),
     ]);
     

   • Reusable Components: Store common snippets (headers, footers) as separate templates and embed them using {{ template('footer') }}.

2. Email Sending

   • Via Code:

     use JeffersonGoncalves\LaravelMail\Facades\LaravelMail;
     
     LaravelMail::send([
         'template' => 'welcome_email',
         'to' => 'user@example.com',
         'data' => ['name' => 'John Doe'],
     ]);
     

   • Via Filament UI: Use the Logs tab to manually send emails with pre-filled templates.

3. Analytics & Tracking

   • Dashboard Insights: Monitor open rates, click rates, and bounces in the Analytics tab.
   • Event Hooks: Extend tracking by listening to mail.sent or mail.opened events:

     event(new \JeffersonGoncalves\LaravelMail\Events\MailSent($mail));
     

4. Suppression Lists

   • Manage Opt-Outs: Use the Suppression tab to add/remove emails from suppression lists.
   • Programmatic Control:

     $suppression = \JeffersonGoncalves\LaravelMail\Models\Suppression::create([
         'email' => 'unsubscribed@example.com',
     ]);
     

Integration Tips

• Queue Emails: Configure config/filament-mail.php to queue emails by default:

  'queue' => true,
  

• Custom Mailables: Extend the package’s Mailable class to integrate with existing Laravel mailables:

  use JeffersonGoncalves\LaravelMail\Mailables\Mailable;
  
  class CustomMailable extends Mailable
  {
      public function build()
      {
          return $this->subject('Custom Subject')->view('emails.custom');
      }
  }
  

• Localization: Override locale-specific templates via language files (resources/lang/{locale}/filament-mail.php):

  return [
      'templates' => [
          'welcome_email' => [
              'subject' => 'Personalizado para {locale}',
          ],
      ],
  ];
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If using laravel-mail, ensure the templates and mailables tables are not duplicated. Run:

     php artisan vendor:publish --tag="laravel-mail-migrations" --force
     

     before migrating.

2. Template Caching

   • Clear the view cache after editing templates in the UI:

     php artisan view:clear
     

3. Queue Stuck Emails

   • Monitor queued emails in the Logs tab. Restart the queue worker if emails are stuck:

     php artisan queue:restart
     

4. Multi-Locale Sync

   • Ensure all locales are defined in config/app.php under locales. Missing locales may break template rendering.

Debugging

• Log Inspection: Use the Logs tab to filter emails by status (sent, failed, queued).
• Template Errors: Check the storage/logs/laravel-mail.log for rendering errors.
• Event Debugging: Temporarily disable tracking events in config/filament-mail.php:

  'tracking' => [
      'events' => false,
  ],
  

Extension Points

1. Custom Fields

   • Extend the template editor by adding custom field types (e.g., for dynamic content):

     // app/Providers/FilamentMailServiceProvider.php
     FilamentMail::registerTemplateField(
         'dynamic_content',
         \JeffersonGoncalves\FilamentMail\Fields\DynamicContentField::class
     );
     

2. API Access

   • Expose email endpoints via Filament’s API:

     // routes/api.php
     Route::middleware('auth:sanctum')->post('/send-mail', [\App\Http\Controllers\MailController::class, 'send']);
     

3. Webhook Integration

   • Listen for external webhooks (e.g., Mailgun, SendGrid) to update Filament Mail’s tracking:

     // app/Providers/EventServiceProvider.php
     protected $listen = [
         \JeffersonGoncalves\LaravelMail\Events\MailOpened::class => [
             \App\Listeners\UpdateTracking::class,
         ],
     ];
     

4. Bulk Actions

   • Add bulk suppression or resend functionality to the Logs table:

     // app/Providers/FilamentMailServiceProvider.php
     FilamentMail::tableActions([
         Tables\Actions\BulkAction::make('suppress')
             ->action(function (Collection $records) {
                 $records->each->suppress();
             }),
     ]);
     

Config Quirks

• Default Locale Fallback: Set a fallback locale in config/filament-mail.php:

  'locales' => [
      'fallback' => 'en',
  ],
  

• Asset Paths: Customize the asset path if using a CDN:

  'assets' => [
      'path' => 'cdn.example.com/storage/filament-mail',
  ],