README

A Laravel package that intercepts and stores all outgoing emails in your database during development and staging. View and manage caught emails through a built-in web interface.

Features

📨 Automatically catches all outgoing emails in specified environments
🎨 Beautiful web interface to view caught emails
🔍 View HTML and text email bodies
📧 See all email metadata (subject, from, to, cc, bcc, headers)
🗑️ Delete individual emails or clear all at once
⚡ Real-time polling for new emails
🔒 Environment-based control
🎯 Configurable route prefix and middleware

Requirements

PHP >= 8.4
Laravel >= 11.x

Installation

1. Install via Composer

composer require proshore/laravel-mailcatch

2. Publish Configuration (Optional)

php artisan vendor:publish --tag=mailcatch-config

3. Publish and Run Migrations

php artisan vendor:publish --tag=mailcatch-migrations
php artisan migrate

Configuration

The package publishes a config/mailcatch.php file with the following options:

return [
    // Enable or disable the package
    'enabled' => env('CATCH_MAIL_ENABLED', true),

    // Environments where emails should be caught
    'allowed_environments' => ['local', 'staging'],

    // Route prefix for the mailbox UI
    'route_prefix' => '__mailbox',

    // Middleware applied to mailbox routes
    'middleware' => ['web'],

    // Maximum length for email body (to prevent database bloat)
    'max_body_length' => 500000,

    // Enable real-time polling for new emails
    'enable_polling' => env('CATCH_MAIL_ENABLE_POLLING', true),
    
    // Polling interval in milliseconds
    'polling_interval' => env('CATCH_MAIL_POLLING_INTERVAL', 10000),
];

Environment Variables

You can control the package behavior via .env:

CATCH_MAIL_ENABLED=true
CATCH_MAIL_ENABLE_POLLING=true
CATCH_MAIL_POLLING_INTERVAL=10000

Usage

Viewing Caught Emails

Once installed, visit the mailbox interface in your browser:

http://your-app.test/__mailbox

The interface will show all caught emails with:

Email subject
From/To addresses
Date/time sent
Read/unread status

Click on any email to view:

Full email details
HTML preview
Text version
All headers
CC and BCC recipients

Sending Test Emails

The package automatically catches all emails sent in allowed environments:

use Illuminate\Support\Facades\Mail;
use App\Mail\WelcomeEmail;

Mail::to('user@example.com')->send(new WelcomeEmail());

The package listens to Laravel's MessageSent event to catch emails. The actual email will still be sent according to your mail configuration, but a copy will be stored in the database for viewing in the mailbox interface.

API Endpoints

The package provides API endpoints for programmatic access:

GET /__mailbox/api/emails - List all emails
GET /__mailbox/api/emails/{id} - Get specific email
POST /__mailbox/api/emails/{id}/read - Mark email as read
DELETE /__mailbox/api/emails/{id} - Delete specific email
DELETE /__mailbox/api/emails - Delete all emails

Accessing the Model

You can also interact with caught emails programmatically:

use Proshore\MailCatch\Models\CatchedMail;

// Get all emails
$emails = CatchedMail::all();

// Get unread emails
$unread = CatchedMail::whereNull('read_at')->get();

// Find specific email
$email = CatchedMail::find(1);

// Access email properties
echo $email->subject;
echo $email->html_body;
print_r($email->to);

Customization

Custom Route Prefix

Change the route prefix in the config file:

'route_prefix' => 'dev/emails',

Now access the mailbox at http://your-app.test/dev/emails

Add Authentication

Protect the mailbox with middleware:

'middleware' => ['web', 'auth', 'admin'],

Disable in Production

The package only catches emails in specified environments. Make sure production is not in the list:

'allowed_environments' => ['local', 'staging'],

Testing

Run the test suite:

composer test

Run code analysis:

composer analyze

Format code:

composer format

proshore / laravel-mailcatch

Maintainers

Details