README

A Laravel package that checks every recipient before a mail goes out, logs every outgoing mail, processes signed Mailtrap webhook events (delivery, bounce, spam, reject) and adds an inbox page to inspect it all. Validation and logging work with any Laravel mailer; only the webhook needs Mailtrap.

Unofficial. This is an independent open-source package, not an official Mailtrap product. It is not made, supported or endorsed by Mailtrap.

Features

• Recipient check before sending: format and MX lookup for every To, Cc and Bcc address; a blocked address aborts the send with a TransportException
• Blocking per address: EmailValidation::markAsBlocked() stops mail to one address, never to its whole domain
• Mail log: one mail_logs row per recipient, optionally linked to a model through X-Mail-* headers, with query scopes and pruning
• Signed webhook: POST /api/webhooks/mailtrap checks the Mailtrap-Signature header (HMAC-SHA256) and updates logs and address verdicts
• Events: MailBlocked and MailtrapEventReceived for your own listeners
• Inbox page: a Livewire/Flux page to search, inspect and clean up the mail log, closed by a viewMailtrap gate
• Commands: mailtrap:install (setup wizard), mailtrap:webhook (creates the webhook and stores its secret), mailtrap:test (health check with exit code)

Requirements

• PHP 8.2 or higher
• Laravel 11, 12 or 13
• Only for the inbox page: livewire/livewire ^3.7.4 or ^4.0 and livewire/flux ^2.11 (the free edition is enough)

Installation

composer require darvis/mailtrap
php artisan mailtrap:install

The wizard runs the migrations and walks you through the Mailtrap tokens, the mailer, the webhook, validation and the inbox page. It writes every answer to .env, so run it on every server. See Installation for the manual steps and every setting.

Who can open the inbox page

Outside the local environment the inbox at /mailtrap answers 403 until your application defines the viewMailtrap gate, the way Laravel Horizon does it. Add this to AppServiceProvider::boot() and adapt the condition to your users:

use App\Models\User;
use Illuminate\Support\Facades\Gate;

Gate::define('viewMailtrap', fn (?User $user) => $user?->is_admin === true);

Set MAILTRAP_UI_MIDDLEWARE=web,auth as well, so a guest is sent to your login page; the wizard writes that for you. MAILTRAP_UI_ENABLED=false switches the page off.

Quick start

After installation every outgoing mail is validated and logged; you do not call the package to send mail.

// routes/web.php

use Darvis\Mailtrap\Models\EmailValidation;
use Darvis\Mailtrap\Models\MailLog;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Route;
use Symfony\Component\Mailer\Exception\TransportException;

Route::get('/mail-demo', function () {
    // Stop all mail to one address (never to the whole domain).
    EmailValidation::markAsBlocked('complainer@example.com', 'Spam complaint');

    try {
        Mail::raw('Hello', fn ($message) => $message->to('complainer@example.com')->subject('Demo'));
    } catch (TransportException $e) {
        // "Email address complainer@example.com is blocked: Spam complaint"
    }

    return ['blocked_logs' => MailLog::toRecipient('complainer@example.com')->blocked()->count()]; // 1
});

Check the setup at any time with a real address of your own:

php artisan mailtrap:test you@yourdomain.com

Documentation

Full documentation: https://arviddejong.github.io/mailtrap/

• Installation: the steps, the two Mailtrap tokens, every setting, and how to check that it works
• Quick start: a complete mailable that is logged and linked to a model
• Sending, blocking and mail logs: what happens on every send, the verdicts, scopes and events
• Email validation: every method of the EmailValidation model
• Webhook: signature checking, status codes and mailtrap:webhook
• Inbox page and health check: who can open the inbox, and mailtrap:test
• Testing: tests without DNS lookups or a mail server
• Troubleshooting: error messages with cause and fix
• FAQ

Laravel Boost

The package ships Laravel Boost resources: a guideline and a mailtrap-development skill. Run php artisan boost:install, or php artisan boost:update --discover in a project that already uses Boost.

Testing

composer test      # Pest
composer lint      # Pint, check only
composer format    # Pint, fixes
composer analyse   # Larastan

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

Security

Please report a security problem privately, see SECURITY.md.

License

MIT, see LICENSE.