dynamik-dev / laravel-mail-preview

v0.3.0 2026-10-08 19:00 UTC

Requires

• php: ^8.3
• illuminate/contracts: ^10.0||^11.0||^12.0||^13.0
• spatie/laravel-package-tools: ^1.16
• spatie/php-structure-discoverer: ^2.3

Requires (Dev)

• larastan/larastan: ^2.9||^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^7.10.0||^8.1.1
• orchestra/testbench: ^8.22.0||^9.0.0||^10.0.0||^11.0.0
• pestphp/pest: ^2.0||^3.0||^4.0
• pestphp/pest-plugin-arch: ^3.0||^4.0
• pestphp/pest-plugin-laravel: ^2.0||^3.0||^4.0
• phpstan/extension-installer: ^1.3||^2.0
• phpstan/phpstan-deprecation-rules: ^1.1||^2.0
• phpstan/phpstan-phpunit: ^1.3||^2.0

MIT

• Chris Arter

• laravel
• DynamikDev
• laravel-mail-preview

Published on Packagist.org on 2026-10-13 13:58 UTC

README

A utility for viewing emails in your browser as you develop with Laravel. This package allows you to preview your mailables without actually sending emails, making it easier to develop and test your email templates.

// Make any mailable previewable
#[Previewable]
class WelcomeEmail extends Mailable
{
    public static function toPreview(): self
    {
        return new self(User::factory()->make());
    }
}

Then, view it instantly at 👀 http://your-app.test/mail/welcome-email

Table of Contents

• How to use
  • 1. Make Your Mailable Previewable
  • 2. View Your Email Preview
  • 3. Custom Preview Slugs
  • 4. Custom Listing Titles
• Installation
• Requirements
• Configuration
  • Environment Variables
• Security
• Testing
• Contributing
• Credits
• License

Think of it like Factories for your emails.

How to use

1. Make Your Mailable Previewable

To make a mailable previewable, add the #[Previewable] attribute and a static toPreview() method:

use DynamikDev\MailPreview\Attributes\Previewable;

#[Previewable]
class WelcomeEmail extends Mailable
{
    public static function toPreview(): self
    {
        return new self(
            User::factory(['name' => 'Chris Arter'])->make()
        );
    }
}

Why an attribute? This package is installed with --dev, so it is absent when you deploy with composer install --no-dev. PHP ignores attributes whose class doesn't exist until they're read, so your mailable still loads and sends normally in production.

The DynamikDev\MailPreview\Contracts\Previewable interface is still supported, but a class implementing it fails to load when the package isn't installed. Only use the interface if you install the package as a regular (non-dev) dependency.

2. View Your Email Preview

Once you've made your mailable previewable, you can view it in your browser at:

http://your-app.test/mail/welcome-email

The URL slug is automatically generated from your class name:

• WelcomeEmail → welcome-email
• OrderConfirmationMail → order-confirmation-mail
• TestMailable → test-mailable

3. Custom Preview Slugs

You can also define a custom preview slug by adding a static property to your mailable:

#[Previewable]
class WelcomeEmail extends Mailable
{
    public static string $previewSlug = 'welcome';
    
    // ... rest of your mailable code
}

Now you can access it at: http://your-app.test/mail/welcome

4. Custom Listing Titles

The listing page at http://your-app.test/mail shows each mailable by its slug. To show a friendlier title instead, add the #[PreviewableTitle] attribute:

use DynamikDev\MailPreview\Attributes\Previewable;
use DynamikDev\MailPreview\Attributes\PreviewableTitle;

#[Previewable]
#[PreviewableTitle('Welcome Email')]
class WelcomeEmail extends Mailable
{
    public static function toPreview(): self
    {
        return new self;
    }
}

The title is not inherited, so a subclass shows its own slug unless it has its own #[PreviewableTitle].

Installation

You can install the package via Composer:

composer require dynamik-dev/laravel-mail-preview --dev

The package will automatically register itself with Laravel.

Requirements

• PHP 8.3+
• Laravel 10.x, 11.x, 12.x, or 13.x

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="DynamikDev\MailPreview\MailPreviewServiceProvider"

This will create a config/mail-preview.php file with the following options:

return [
    // Enable or disable the mail preview
    'enabled' => env('MAIL_PREVIEW_ENABLED', false),
    
    // The route prefix for the mail preview
    'route_prefix' => env('MAIL_PREVIEW_ROUTE_PREFIX', 'mail'),
    
    // The path to discover mailables in
    'discover_path' => env('MAIL_PREVIEW_DISCOVER_PATH', base_path('app')),
];

Environment Variables

The preview routes are only registered when MAIL_PREVIEW_ENABLED is true. It defaults to false, so add it to your local .env file.

These are the available options:

MAIL_PREVIEW_ENABLED=true
MAIL_PREVIEW_ROUTE_PREFIX=mail
MAIL_PREVIEW_DISCOVER_PATH=/path/to/your/app

Security

Important: This package should only be enabled in development environments. The mail preview routes expose your email templates and could potentially leak sensitive information.

Make sure to:

1. Leave MAIL_PREVIEW_ENABLED unset (or false) in production so the routes are never registered
2. Add the preview routes to your middleware if needed
3. Consider using authentication middleware for the preview routes

Testing

Run the test suite:

composer test

Contributing

Please see CONTRIBUTING.md for details.

Credits

• Chris Arter
• All Contributors

License

The MIT License (MIT). Please see License File for more information.