thephpx/laravel-error-mailer

A Laravel package that automatically emails 500-level error traces to a configured email address.

dev-main 2026-02-23 11:08 UTC

Requires

• php: ^8.1
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/mail: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Faisal Ahmed

• mailer
• exception
• error
• notification
• laravel
• 500

README

A zero-hassle Laravel package that automatically emails 500-level error stack traces to a configured address every time an unhandled server error occurs. No more checking logs manually.

Features

• 📧 Sends a beautifully formatted error email on 500-level exceptions
• 🔧 Fully configurable via .env — no code changes required
• 🔒 Masks sensitive input (password, token, api_key, etc.) before sending
• 🚦 Throttle support — prevents email flooding for repeated identical errors
• 🚫 Ignore list — skip certain exception classes you don't care about
• 📋 Includes full request context: URL, method, IP, headers, and input
• 🎨 Dark-themed professional HTML email template
• ✅ Laravel auto-discovery (zero manual registration)
• 🧪 Fully tested with Orchestra Testbench

Requirements

Package	Version
PHP	^8.1
Laravel	^10.0 | ^11.0 | ^12.0

Installation

1. Install via Composer

composer require thephpx/laravel-error-mailer

Laravel will auto-discover the service provider. No manual registration needed.

2. Set environment variables in .env

# ─── Required ────────────────────────────────────
# Email address to receive error notifications
ERROR_MAILER_TO=[e-mail]

# ─── Optional (with defaults) ────────────────────
ERROR_MAILER_TO_NAME="Site Administrator"
ERROR_MAILER_FROM=[e-mail]
ERROR_MAILER_FROM_NAME="Laravel Error Mailer"
ERROR_MAILER_SUBJECT="[Error] :app_name — :exception_class"
ERROR_MAILER_ENABLED=true

# Cooldown (minutes) before the same error is emailed again (0 = off)
ERROR_MAILER_THROTTLE=5

# Include request URL / method / IP / headers / input in the email?
ERROR_MAILER_INCLUDE_REQUEST=true

That's it. The package is now active and will email errors automatically.

3. (Optional) Publish the config

php artisan vendor:publish --tag=error-mailer-config

This copies config/error-mailer.php to your application for full customisation.

4. (Optional) Publish the email view

php artisan vendor:publish --tag=error-mailer-views

This copies the Blade template to resources/views/vendor/error-mailer/ so you can customise the email layout.

Configuration Reference

After publishing, open config/error-mailer.php:

return [

    // Master on/off switch
    'enabled'            => env('ERROR_MAILER_ENABLED', true),

    // Recipient
    'to'                 => env('ERROR_MAILER_TO', null),
    'to_name'            => env('ERROR_MAILER_TO_NAME', 'Site Administrator'),

    // Sender (falls back to MAIL_FROM_* values)
    'from'               => env('ERROR_MAILER_FROM', env('MAIL_FROM_ADDRESS')),
    'from_name'          => env('ERROR_MAILER_FROM_NAME', env('MAIL_FROM_NAME')),

    // Subject line — use :app_name, :app_env, :exception_class as placeholders
    'subject'            => env('ERROR_MAILER_SUBJECT', '[Error] :app_name — :exception_class'),

    // Which HTTP status codes trigger an email (empty = ALL exceptions)
    'http_status_codes'  => [500, 502, 503, 504],

    // Exception classes to never email
    'ignored_exceptions' => [],

    // Include request details in the email?
    'include_request'    => env('ERROR_MAILER_INCLUDE_REQUEST', true),

    // Input keys that will be replaced with ***REDACTED*** in the email
    'sensitive_keys'     => ['password', 'password_confirmation', 'token', 'secret', 'api_key'],

    // Throttle: same exception won't be emailed more than once per N minutes
    'throttle_minutes'   => env('ERROR_MAILER_THROTTLE', 5),

];

How It Works

The package hooks into Laravel's exception reporter using ExceptionHandler::reportable().
When an exception is thrown:

1. The package checks if it is enabled.
2. It checks the exception is not in the ignored list.
3. It resolves the HTTP status code — non-HTTP exceptions are treated as 500.
4. It checks whether the status code is in http_status_codes.
5. It checks the throttle cache — same exception within the cooldown window is skipped.
6. It composes a safe email (redacting sensitive keys) and sends it via your configured mail driver.

All of this runs inside a try/catch so the mailer never crashes your application.

Email Preview

The email includes:

Section	Details
Exception class	Full class name
Message	Exception message
Location	File path + line number
Stack trace	Full PHP stack trace
Request details	URL, method, IP, headers, input (with sensitive keys redacted)

Running Tests

composer install
./vendor/bin/phpunit

Changelog

v1.0.0

• Initial release

License

MIT © thephpx (Faisal Ahmed)