README

Laravel Pulse Mail

Track and monitor emails sent from your Laravel application directly in your Laravel Pulse dashboard.

This package provides a custom Pulse widget that displays sent emails with details including recipients, subjects, mailable classes, and send counts. Perfect for monitoring email activity and debugging mail-related issues in production.

Features

📧 Track all sent emails - Automatically records emails sent via Laravel Mail
🎯 Detailed information - Shows recipient, subject, mailable class, and send count
⚙️ Configurable filtering - Exclude specific emails or mailables from tracking
📊 Sample rate control - Track a percentage of emails for high-volume applications
🕐 Time-based filtering - Uses Pulse's built-in date filtering
🎨 Consistent UI - Matches Pulse's design language

Requirements

PHP 8.3+
Laravel 10.x, 11.x, or 12.x
Laravel Pulse 1.x

Installation

Step 1: Install the Package

Install the package via Composer:

composer require oltrematica/laravel-pulse-mail

Step 2: Publish Configuration Files

Publish the package configuration file:

php artisan vendor:publish --tag=pulse-mail-config

If you haven't already published the Pulse dashboard view, publish it as well:

php artisan vendor:publish --tag=pulse-dashboard

Step 3: Configure Pulse Recorder

Add the mail recorder to your config/pulse.php file in the recorders array:

'recorders' => [
    // ... other recorders

    \Oltrematica\Pulse\Mail\Recorders\MailSentRecorder::class => [
        'enabled' => env('PULSE_MAIL_ENABLED', true),
    ],
],

Step 4: Add Widget to Dashboard

Add the mail-sent widget to your Pulse dashboard in resources/views/vendor/pulse/dashboard.blade.php:

<x-pulse>
    <livewire:pulse.servers cols="full" />

    <livewire:pulse.usage cols="4" rows="2" />

    <livewire:pulse.queues cols="4" />

    <livewire:pulse.cache cols="4" />

    {{-- Custom: Mail Sent Widget --}}
    <livewire:pulse.mail-sent cols="8" />

    <livewire:pulse.slow-queries cols="8" />

    <livewire:pulse.slow-jobs cols="4" />

    <livewire:pulse.slow-requests cols="full" />

    <livewire:pulse.exceptions cols="6" />

    <livewire:pulse.slow-outgoing-requests cols="6" />
</x-pulse>

You can customize the widget size using the cols and rows attributes. Common configurations:

cols="full" - Full width
cols="8" - 2/3 width
cols="6" - Half width
cols="4" - 1/3 width

Configuration

The config/pulse-mail.php file provides several options:

return [
    // Maximum number of emails to display in the widget
    'limit' => env('PULSE_MAIL_LIMIT', 10),

    // Email addresses to exclude from tracking
    'ignore' => [
        'to' => [
            // 'test@example.com',
        ],
    ],

    // Mailable classes to exclude from tracking
    'ignore_mailables' => [
        // \App\Mail\TestEmail::class,
    ],

    // Sample rate (0-1): 1 = track all emails, 0.5 = track 50%
    'sample_rate' => env('PULSE_MAIL_SAMPLE_RATE', 1),
];

Usage

Once installed and configured, the package will automatically start tracking emails sent through Laravel's Mail facade or Mailable classes. The widget will display:

To: Email recipient address(es)
Subject: Email subject line
Mailable: The Mailable class used (if applicable)
Count: Number of times this email was sent during the selected period

Filtering

The widget respects Pulse's time-based filtering. Use the Pulse dashboard controls to filter emails by time period (last hour, 24 hours, 7 days, etc.).

Ignoring Specific Emails

To exclude certain emails from tracking, add them to the configuration:

// Ignore by recipient
'ignore' => [
    'to' => [
        'test@example.com',
        'noreply@example.com',
    ],
],

// Ignore by Mailable class
'ignore_mailables' => [
    \App\Mail\TestEmail::class,
    \App\Mail\InternalNotification::class,
],

Sample Rate

For high-volume applications, you can track only a percentage of emails:

// Track 50% of emails
'sample_rate' => 0.5,

// Or use environment variable
'sample_rate' => env('PULSE_MAIL_SAMPLE_RATE', 1),

Viewing Emails in Real-Time

Laravel Pulse uses an ingest system that processes recorded data asynchronously. After sending emails, you need to run the Pulse ingest process to see them in the dashboard:

Option 1: Manual Ingest (Development)

Run this command to process pending data once:

php artisan pulse:check

Option 2: Automatic Ingest (Recommended)

Run the Pulse worker in the background to automatically process data:

php artisan pulse:work

For development environments, add pulse:work to your concurrent processes. For example, if using concurrently in your composer dev script:

"dev": [
    "npx concurrently \"php artisan serve\" \"php artisan queue:listen\" \"php artisan pulse:work\" \"npm run dev\""
]

Option 3: Production Setup

In production, configure a supervisor process to keep pulse:work running continuously. See the Laravel Pulse documentation for details.

Code Quality

The project includes automated tests and tools for code quality control.

Rector

Rector is a tool for automating code refactoring and migrations. It can be run using the following command:

composer refactor

PhpStan

PhpStan is a tool for static analysis of PHP code. It can be run using the following command:

composer analyse

Pint

Pint is a tool for formatting PHP code. It can be run using the following command:

composer format

Automated Tests