### Install Backstage Mails

Source: https://context7.com/backstagephp/mails/llms.txt

Use Composer to install the package and run the necessary artisan commands to publish migrations and configuration.

```bash
composer require backstage/mails

# Publish and run migrations
php artisan vendor:publish --tag="mails-migrations"
php artisan migrate

# Optionally publish the config file
php artisan vendor:publish --tag="mails-config"
```

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

### Install Backstage Mails via Composer

Source: https://github.com/backstagephp/mails/blob/main/README.md

Use this command to add the Backstage Mails package to your Laravel project.

```bash
composer require backstage/mails
```

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

### Configure Custom Access Control for Mails Plugin

Source: https://github.com/backstagephp/mails/blob/main/README.md

Implement custom logic to define which users can manage mail resources within the Filament panel. This example combines role and permission checks.

```php
use Backstage\Mails\MailsPlugin;
use Illuminate\Support\Facades\Auth;

$panel
    ->plugins([
        MailsPlugin::make()
            ->canManageMails(function () {
                $user = Auth::user();

                // Allow access for users with specific roles
                if ($user->hasRole('admin') || $user->hasRole('supervisor')) {
                    return true;
                }

                // Allow access for users with specific permissions
                if ($user->hasPermissionTo('manage mails')) {
                    return true;
                }

                // Restrict access for all other users
                return false;
            }),
    ]);

```

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

### Publish and Run Mail Migrations

Source: https://github.com/backstagephp/mails/blob/main/README.md

Publish the package's migration files and then run them to set up the necessary database tables for logging emails.

```bash
php artisan vendor:publish --tag="mails-migrations"
php artisan migrate
```

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

### Run Package Tests

Source: https://github.com/backstagephp/mails/blob/main/README.md

Execute the package's test suite using Composer. This command runs all defined tests to ensure the package is functioning correctly.

```bash
composer test
```

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

### Publish Mail Configuration

Source: https://github.com/backstagephp/mails/blob/main/README.md

Publish the configuration file for Backstage Mails to customize its behavior.

```bash
php artisan vendor:publish --tag="mails-config"
```

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

### Retrieve and Process Mail Attachments

Source: https://context7.com/backstagephp/mails/llms.txt

Demonstrates how to load attachments for a specific mail model, iterate through them to access metadata, and download the file content.

```php
<?php

use Backstage\Mails\Laravel\Models\Mail;
use Backstage\Mails\Laravel\Models\MailAttachment;

// Get mail with attachments
$mail = Mail::with('attachments')->find(1);

// Check if mail has attachments
if ($mail->attachments->count() > 0) {
    foreach ($mail->attachments as $attachment) {
        echo $attachment->filename;  // Original filename
        echo $attachment->mime;      // MIME type (e.g., application/pdf)
        echo $attachment->size;      // Size in bytes
        echo $attachment->uuid;      // Unique identifier

        // Download file from storage
        $fileContents = $attachment->downloadFileFromStorage();

        // Format file size for display
        $formattedSize = match(true) {
            $attachment->size >= 1073741824 => number_format($attachment->size / 1073741824, 2) . ' GB',
            $attachment->size >= 1048576 => number_format($attachment->size / 1048576, 2) . ' MB',
            $attachment->size >= 1024 => number_format($attachment->size / 1024, 2) . ' KB',
            default => $attachment->size . ' bytes',
        };
    }
}
```

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

### Publish Mail Views

Source: https://github.com/backstagephp/mails/blob/main/README.md

Optionally, publish the package's views if you need to customize the appearance of the mail logging interface.

```bash
php artisan vendor:publish --tag="mails-views"
```

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

### Add Mails Plugin to Filament PanelProvider

Source: https://github.com/backstagephp/mails/blob/main/README.md

Integrate the MailsPlugin into your Filament panel by adding it to the `PanelProvider`.

```php
use Backstage\Mails\MailsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(MailsPlugin::make());
}
```

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

### Generate Mail Preview and Attachment URLs

Source: https://context7.com/backstagephp/mails/llms.txt

Access system-registered routes to generate URLs for mail previews and attachment downloads, including support for tenant-aware applications.

```php
<?php

use Backstage\
Mails\
Laravel\
Models\
Mail;
use Backstage\
Mails\
Laravel\
Models\
MailAttachment;

// Get mail preview URL
$mail = Mail::find(1);
$previewUrl = route('mails.preview', ['mail' => $mail->id]);

// Get attachment download URL
$attachment = MailAttachment::find(1);
$downloadUrl = route('mails.attachment.download', [
    'mail' => $attachment->mail_id,
    'attachment' => $attachment->id,
    'filename' => $attachment->filename,
]);

// In tenant-aware applications, routes include the tenant
$previewUrl = route('filament.admin.mails.preview', [
    'tenant' => $tenant->id,
    'mail' => $mail->id,
]);
```

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

### Customize Configuration Options

Source: https://context7.com/backstagephp/mails/llms.txt

Modify the mails.php configuration file to override default resources or adjust navigation settings.

```php
<?php

// config/mails.php
return [
    // Override default resources with custom implementations
    'resources' => [
        'mail' => \App\Filament\Resources\MailResource::class,
        'event' => \App\Filament\Resources\EventResource::class,
        'suppression' => \App\Filament\Resources\SuppressionResource::class,
    ],

    // Customize navigation placement
    'navigation' => [
        'group' => 'Communications', // Navigation group name
        'sort' => 10,                // Navigation order
    ],
];
```

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

### Configure Mail Resources in PHP

Source: https://github.com/backstagephp/mails/blob/main/README.md

Customize resource classes by overriding the MailResource or EventResource in the mails config file. Ensure your custom resource extends the original.

```php
return [
    'resources' => [
        'mail' => \App\Filament\Resources\MailResource::class,
        'event' => \App\Filament\Resources\EventResource::class,
        'suppression' => \App\Filament\Resources\SuppressionResource::class
    ],
];
```

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

### Register MailsPlugin in PanelProvider

Source: https://context7.com/backstagephp/mails/llms.txt

Add the MailsPlugin to your Filament panel configuration to enable the mail management interface.

```php
<?php

namespace App\Providers\Filament;

use Backstage\Mails\MailsPlugin;
use Filament\Panel;
use Filament\PanelProvider;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->default()
            ->id('admin')
            ->path('admin')
            ->plugin(MailsPlugin::make());
    }
}
```

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

### Register Mail Statistics Widget

Source: https://context7.com/backstagephp/mails/llms.txt

Include the MailStatsWidget in custom Filament dashboards to display email performance metrics.

```php
<?php

namespace App\
Filament\
Widgets;

use Backstage\
Mails\
Resources\
MailResource\
Widgets\
MailStatsWidget;

// The widget is automatically included in ListMails page
// It shows: Delivered %, Opened %, Clicked %, Bounced %

// To include in a custom dashboard, register the widget:
class DashboardController
{
    public function getWidgets(): array
    {
        return [
            MailStatsWidget::class,
        ];
    }
}

// The widget requires the user to have mail management permissions
// Access is controlled by MailsPlugin::get()->userCanManageMails()
```

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

### Configure Access Control

Source: https://context7.com/backstagephp/mails/llms.txt

Use the canManageMails method to define custom authorization logic for accessing mail resources.

```php
<?php

use Backstage\Mails\MailsPlugin;
use Illuminate\Support\Facades\Auth;

$panel->plugins([
    MailsPlugin::make()
        ->canManageMails(function () {
            $user = Auth::user();

            // Allow access for users with specific roles
            if ($user->hasRole('admin') || $user->hasRole('supervisor')) {
                return true;
            }

            // Allow access for users with specific permissions
            if ($user->hasPermissionTo('manage mails')) {
                return true;
            }

            // Restrict access for all other users
            return false;
        }),
]);
```

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

### Extend MailResource

Source: https://context7.com/backstagephp/mails/llms.txt

Create a custom resource class by extending the base MailResource to override labels or access logic.

```php
<?php

namespace App\Filament\Resources;

use Backstage\Mails\Resources\MailResource as BaseMailResource;
use Illuminate\Support\Facades\Auth;

class MailResource extends BaseMailResource
{
    protected static ?string $navigationGroup = 'Email Management';

    protected static ?int $navigationSort = 5;

    public static function canAccess(): bool
    {
        // Custom access logic
        return Auth::user()->can('view-emails');
    }

    public static function getNavigationLabel(): string
    {
        return 'Sent Emails';
    }

    public static function getLabel(): ?string
    {
        return 'Email';
    }
}
```

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

### Track and Query Email Events

Source: https://context7.com/backstagephp/mails/llms.txt

Use the EventType enum to filter mail events and access detailed metadata like IP address, browser, and location.

```php
<?php

use Backstage\
Mails\
Laravel\
Enums\
EventType;
use Backstage\
Mails\
Laravel\
Models\
MailEvent;

// Available event types
$eventTypes = [
    EventType::DELIVERED,     // Email successfully delivered
    EventType::OPENED,        // Email was opened
    EventType::CLICKED,       // Link in email was clicked
    EventType::SOFT_BOUNCED,  // Temporary delivery failure
    EventType::HARD_BOUNCED,  // Permanent delivery failure
    EventType::COMPLAINED,    // Marked as spam
    EventType::UNSUBSCRIBED,  // User unsubscribed
    EventType::ACCEPTED,      // Email accepted by mail server
];

// Query events for a specific mail
$mail = Mail::find(1);
$events = $mail->events()->orderByDesc('occurred_at')->get();

// Get all bounce events
$bounceEvents = MailEvent::where('type', EventType::HARD_BOUNCED)
    ->orWhere('type', EventType::SOFT_BOUNCED)
    ->get();

// Event contains detailed information
foreach ($events as $event) {
    echo $event->type->value;      // Event type
    echo $event->occurred_at;      // When it happened
    echo $event->ip_address;       // User's IP address
    echo $event->browser;          // Browser used
    echo $event->platform;         // Platform (desktop/mobile)
    echo $event->city;             // User's city
    echo $event->country_code;     // User's country
    echo $event->link;             // Clicked link (for click events)
}
```

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

### Query Mail Model Scopes

Source: https://context7.com/backstagephp/mails/llms.txt

Use built-in query scopes on the Mail model to filter emails by status or calculate delivery statistics.

```php
<?php

use Backstage\Mails\Laravel\Models\Mail;

// Get all unsent emails
$unsentMails = Mail::unsent()->get();

// Get all sent emails
$sentMails = Mail::sent()->get();

// Get delivered emails
$deliveredMails = Mail::delivered()->get();

// Get opened emails
$openedMails = Mail::opened()->get();

// Get clicked emails (user clicked a link)
$clickedMails = Mail::clicked()->get();

// Get bounced emails
$softBouncedMails = Mail::softBounced()->get();
$hardBouncedMails = Mail::hardBounced()->get();

// Get complained emails (marked as spam)
$complainedMails = Mail::complained()->get();

// Calculate email statistics
$totalMails = Mail::count();
$deliveryRate = Mail::delivered()->count() / $totalMails * 100;
$openRate = Mail::opened()->count() / $totalMails * 100;
$bounceRate = (Mail::softBounced()->count() + Mail::hardBounced()->count()) / $totalMails * 100;
```

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

### Resend Emails Programmatically

Source: https://context7.com/backstagephp/mails/llms.txt

Use the ResendMail action to trigger a resend to original or custom recipients.

```php
<?php

use Backstage\
Mails\
Laravel\
Actions\
ResendMail;
use Backstage\
Mails\
Laravel\
Models\
Mail;

// Find the mail to resend
$mail = Mail::find(1);

// Resend to original recipients
$resendAction = new ResendMail();
$resendAction->handle(
    $mail,
    to: array_keys($mail->to),
    cc: array_keys($mail->cc ?? []),
    bcc: array_keys($mail->bcc ?? [])
);

// Resend to different recipients
$resendAction->handle(
    $mail,
    to: ['newrecipient@example.com', 'another@example.com'],
    cc: ['manager@example.com'],
    bcc: []
);
```

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

### Unsuppress Email Addresses

Source: https://context7.com/backstagephp/mails/llms.txt

Dispatch the MailUnsuppressed event to remove an address from the suppression list after resolving delivery issues.

```php
<?php

use Backstage\
Mails\
Laravel\
Events\
MailUnsuppressed;
use Backstage\
Mails\
Laravel\
Models\
Mail;
use Backstage\
Mails\
Laravel\
Models\
MailEvent;

// Find the suppressed event
$event = MailEvent::where('type', 'hard_bounced')
    ->whereNull('unsuppressed_at')
    ->first();

// Get the email address and mailer info
$email = key($event->mail->to);
$mailer = $event->mail->mailer === 'smtp' && filled($event->mail->transport)
    ? $event->mail->transport
    : $event->mail->mailer;
$streamId = $event->mail->stream_id ?? null;

// Dispatch the unsuppress event
event(new MailUnsuppressed($email, $mailer, $streamId));
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.