README

Laravel adapter for nettmail/core — Eloquent models, service provider, queued jobs, and Livewire admin UI for the NettMail email package.

Installation

You can install the package via composer:

composer require nettsite/nettmail-laravel

You can publish and run the migrations with:

php artisan vendor:publish --tag="nettmail-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="nettmail-config"

This is the contents of the published config file:

return [
];

Optionally, you can publish the views using

php artisan vendor:publish --tag="nettmail-views"

The admin UI is mounted at /nettmail (configurable via NETTMAIL_ROUTES_PREFIX) behind the web and auth middleware (configurable via routes.middleware). It includes pages for the dashboard, contacts, lists, segments, campaigns, templates, and settings.

Usage

use NettSite\NettMail\Facades\NettMail;

NettMail::eraseContact($contactId);

Scheduler

NettMail ships several artisan commands that should run on a schedule. Register them in your host app's bootstrap/app.php:

use Illuminate\Console\Scheduling\Schedule;

->withSchedule(function (Schedule $schedule): void {
    // Sends scheduled broadcast campaigns once their send time arrives.
    $schedule->command('nettmail:dispatch-scheduled')->everyMinute();

    // Polls the configured bounce mailbox for DSNs and complaints.
    $schedule->command('nettmail:poll-bounces')->everyFiveMinutes();

    // Purges send logs and events older than `retention.send_log_years`.
    $schedule->command('nettmail:purge')->daily();
})

If you've registered a contact source (see below), keep contacts in sync on a schedule too:

$schedule->command('nettmail:sync-contacts merlin')->hourly();

Contact sources

NettMail keeps its own copy of contacts (nettmail_contacts) and syncs them from your host app via a ContactSourceContract implementation, registered with ContactSourceRegistry.

use Nettsite\NettMail\Core\Contracts\ContactSourceContract;

class MerlinClientContactSource implements ContactSourceContract
{
    public function label(): string
    {
        return 'Merlin clients';
    }

    public function key(): string
    {
        return 'merlin';
    }

    /**
     * @return iterable<array{email: string, first_name?: string, last_name?: string, phone?: string, metadata?: array<string, mixed>, source_id?: string|int}>
     */
    public function contacts(): iterable
    {
        foreach (Client::query()->whereNotNull('email')->cursor() as $client) {
            yield [
                'email' => $client->email,
                'first_name' => $client->first_name,
                'last_name' => $client->last_name,
                'phone' => $client->phone,
                'metadata' => ['client_id' => $client->id],
                'source_id' => $client->id,
            ];
        }
    }

    /**
     * @return array{email: string, first_name?: string, last_name?: string, phone?: string, metadata?: array<string, mixed>, source_id?: string|int}|null
     */
    public function findContact(string|int $sourceId): ?array
    {
        $client = Client::find($sourceId);

        if ($client === null) {
            return null;
        }

        return [
            'email' => $client->email,
            'first_name' => $client->first_name,
            'last_name' => $client->last_name,
            'phone' => $client->phone,
            'metadata' => ['client_id' => $client->id],
            'source_id' => $client->id,
        ];
    }
}

Register it in a service provider's boot() method:

use NettSite\NettMail\Contacts\ContactSourceRegistry;

public function boot(ContactSourceRegistry $registry): void
{
    $registry->register(new MerlinClientContactSource);
}

Then sync contacts on demand or via the scheduler:

php artisan nettmail:sync-contacts merlin

Navigation

Add links to the NettMail admin pages in your host app's navigation. Routes are named nettmail.* and the configured nav group label is available via config('nettmail.nav_group'):

@if (Route::has('nettmail.dashboard'))
    <x-nav-group :label="config('nettmail.nav_group')">
        <x-nav-link :href="route('nettmail.dashboard')" wire:navigate>Dashboard</x-nav-link>
        <x-nav-link :href="route('nettmail.contacts.index')" wire:navigate>Contacts</x-nav-link>
        <x-nav-link :href="route('nettmail.lists.index')" wire:navigate>Lists</x-nav-link>
        <x-nav-link :href="route('nettmail.segments.index')" wire:navigate>Segments</x-nav-link>
        <x-nav-link :href="route('nettmail.campaigns.index')" wire:navigate>Campaigns</x-nav-link>
        <x-nav-link :href="route('nettmail.templates.index')" wire:navigate>Templates</x-nav-link>
        <x-nav-link :href="route('nettmail.settings')" wire:navigate>Settings</x-nav-link>
    </x-nav-group>
@endif

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Nettsite
• All Contributors

License

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