===============
LIBRARY RULES
===============
From library maintainers:
- Send mail through Mailroom with MAIL_MAILER=mailroom, then open /mailroom to read it. Do not set up Mailpit, MailHog, Mailtrap or an SMTP container in an application that has Mailroom.
- Mailroom is off in production unless MAILROOM_ENABLED=true. Only set that when the user asks: it stores every email, password reset links included.
- Outside the local environment, grant access with Gate::define('viewMailroom', fn (?User $user) => ...) or Mailroom::auth(fn (Request $request) => ...).
- Read addresses through $message->addressesFor(AddressRole::To), sender() and envelopeSender(), and eager-load with('addresses') when reading many messages.
- Delete captured mail through the model, php artisan mailroom:prune or mailroom:clear, never a query-builder delete, which leaves the stored .eml and attachment files behind.
- Configure forwarding (MAILROOM_FORWARD_MAILER) or the spam check (MAILROOM_SPAM_DRIVER) only when the user asks: they are the only ways captured mail leaves the application.

### Run the Mailroom Installer

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/README.md

Run the installer command to set up the package. After installation, open /mailroom to view emails.

```bash
php artisan mailroom:install
```

--------------------------------

### Create tables from package

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/installation.md

Runs migrations directly from the package without the installer. Equivalent to the installer's migrate step.

```bash
php artisan migrate
```

--------------------------------

### Install unattended with all options

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/installation.md

Runs the installer without prompts, publishing config, setting the mailer, and migrating. Use in CI, Dockerfile, or provisioning scripts.

```bash
php artisan mailroom:install --no-interaction --set-mailer --migrate
```

--------------------------------

### Install without publishing or migrating

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/installation.md

Runs the installer without publishing config or running migrations. Use when you want to touch nothing.

```bash
php artisan mailroom:install --no-config --no-migrate
```

--------------------------------

### Set mailer in .env

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/installation.md

Appends MAIL_MAILER=mailroom to your .env file to send mail through Mailroom.

```bash
echo "MAIL_MAILER=mailroom" >> .env
```

--------------------------------

### Install Laravel Mailroom via Composer

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/README.md

Install the package as a dev dependency using Composer. Requires PHP 8.2+ and Laravel 12 or 13 (11 on v0.10).

```bash
composer require --dev ebbbang/laravel-mailroom
```

--------------------------------

### Enable forwarding with MAILROOM_FORWARD_MAILER

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/forwarding.md

Set this environment variable to a mailer that can deliver (e.g., smtp) to enable the Forward button on each message. Without it, the route is not registered and the button explains the setup instead of offering a form.

```dotenv
MAILROOM_FORWARD_MAILER=smtp
```

--------------------------------

### Preview prune without deleting

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/production.md

See what would be deleted without actually deleting anything.

```bash
php artisan mailroom:prune --pretend
```

--------------------------------

### Publish Mailroom views

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/configuration.md

Publishes the view files to resources/views/vendor/mailroom. Use this command to customize the UI.

```bash
php artisan vendor:publish --tag=mailroom-views
```

--------------------------------

### Prune with --days option

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/production.md

Choose the age for one run using --days.

```bash
php artisan mailroom:prune --days=30
```

--------------------------------

### Set MAILROOM_DISK and enable Mailroom on Laravel Cloud

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/advanced.md

Required for Laravel Cloud and other ephemeral platforms. Set MAILROOM_DISK to persistent object storage and MAILROOM_ENABLED=true because Cloud environments carry APP_ENV=production even when staging.

```dotenv
MAIL_MAILER=mailroom
MAILROOM_DISK=<your object storage disk>
MAILROOM_ENABLED=true
```

--------------------------------

### Enable Mailroom on Staging with Environment Variables

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/staging.md

Set these environment variables to enable Mailroom on a staging environment. Requires an object storage disk for captured mail.

```dotenv
MAIL_MAILER=mailroom
MAILROOM_ENABLED=true
MAILROOM_DISK=<your object storage disk>
```

--------------------------------

### Prune with --hours option

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/production.md

Choose the age for one run using --hours.

```bash
php artisan mailroom:prune --hours=6
```

--------------------------------

### Bound forwarding with allowed domains and rate limit

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/forwarding.md

On a shared staging box, these variables restrict where mail can go and how often. MAILROOM_FORWARD_ALLOWED takes a comma-separated list of whole addresses or @domain; empty means anywhere (default). MAILROOM_FORWARD_RATE_LIMIT caps forwards per minute, counted per signed-in user and otherwise per IP; ten by default, null removes the ceiling.

```dotenv
MAILROOM_FORWARD_MAILER=smtp
MAILROOM_FORWARD_ALLOWED=@yourcompany.com
MAILROOM_FORWARD_RATE_LIMIT=10
```

--------------------------------

### Publish Mailroom config

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/configuration.md

Publishes the configuration file to config/mailroom.php. Use this command to customize settings.

```bash
php artisan vendor:publish --tag=mailroom-config
```

--------------------------------

### Enable Mailroom in production with MAILROOM_ENABLED

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/production.md

Opt in explicitly to use Mailroom in production. Without this, the mailroom transport refuses to be constructed and routes are not registered, so /mailroom returns 404. Enabling stores full email contents in the database and on disk.

```dotenv
MAILROOM_ENABLED=true
```

--------------------------------

### Eager-load addresses relation

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/advanced.md

Eager-load the addresses relation when querying many messages to avoid N+1 queries.

```php
MailroomMessage::query()->with('addresses')->latest()->take(50)->get();
```

--------------------------------

### Enable Postmark spam driver with MAILROOM_SPAM_DRIVER

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/spam-check.md

Set this environment variable to turn on the Spam Check pane. The feature is off until a driver is set, and the route that sends mail does not exist until then.

```dotenv
MAILROOM_SPAM_DRIVER=postmark
```

--------------------------------

### Add auth middleware

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/access-control.md

Add 'auth' to the middleware stack to put the mailbox behind your application's existing login. Your own login flow handles the redirect.

```php
'middleware' => ['web', 'auth', Authorize::class],
```

--------------------------------

### Prune via model:prune

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/production.md

The model is Prunable, so this works too. Deletes go through model events to remove raw .eml and attachment blobs.

```bash
php artisan model:prune --model="Ebbbang\Mailroom\Models\MailroomMessage"
```

--------------------------------

### Protect Mailroom with Authentication Middleware and Gate

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/staging.md

Add authentication middleware and a gate to restrict access to the Mailroom mailbox. The gate checks if the user is on the QA team.

```php
'middleware' => ['web', 'auth', Authorize::class],

Gate::define('viewMailroom', fn (?User $user) => $user?->isQaTeam());
```

--------------------------------

### Clear all mail and files

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/production.md

Delete everything, including stored files.

```bash
php artisan mailroom:clear
```

--------------------------------

### Run mailroom:prune with default retention

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/production.md

Deletes messages older than prune.retention_days (default 7 days).

```bash
php artisan mailroom:prune
```

--------------------------------

### Define viewMailroom gate

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/access-control.md

Define a gate named 'viewMailroom' to control mailbox access. The parameter is nullable so guests are evaluated, allowing this to work without auth middleware.

```php
Gate::define('viewMailroom', fn (?User $user) => $user?->isAdmin());
```

--------------------------------

### Set auth callback

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/access-control.md

Use a callback for access control that a gate cannot express. The callback receives the request and returns a boolean.

```php
Mailroom::auth(fn (Request $request) => $request->ip() === '10.0.0.1');
```

--------------------------------

### Read addresses from stored message

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/advanced.md

Access sender, recipient, and envelope addresses from the stored message. Roles include From, To, Cc, Bcc, ReplyTo, EnvelopeFrom, and EnvelopeTo. The includes() check is case-insensitive.

```php
use Ebbbang\Mailroom\Support\AddressRole;

$message = $event->message;

$message->sender()?->address;                              // "orders@acme.test"
$message->addressesFor(AddressRole::To)->display();        // "Rachel Okonkwo <rachel@example.test>, sam@example.test"
$message->addressesFor(AddressRole::Cc, AddressRole::Bcc)->emails(); // every Cc, then every Bcc
$message->addressesFor(AddressRole::To)->includes('Rachel@Example.test'); // true, case-insensitive
$message->envelopeSender()?->address;                      // the SMTP envelope's MAIL FROM
```

--------------------------------

### Listen to MessageStored event

Source: https://github.com/ebbbang/laravel-mailroom/blob/main/docs/advanced.md

Use this listener to access the stored MailroomMessage and Symfony's SentMessage after a message is stored. Laravel's MessageSent does not carry a reference to the stored row.

```php
use Ebbbang\Mailroom\Events\MessageStored;

Event::listen(function (MessageStored $event) {
    $event->message;      // the stored MailroomMessage
    $event->sentMessage;  // Symfony's SentMessage
});
```