Laravel Email Preference Center

composer require lchris44/laravel-email-preference-center

php artisan vendor:publish --tag=email-preferences-config
php artisan migrate

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Lchris44\EmailPreferenceCenter\Traits\HasEmailPreferences;

class User extends Authenticatable
{
    use HasEmailPreferences;
}

'categories' => [
    'security' => [
        'label'       => 'Security Alerts',
        'description' => 'Password changes, login alerts, and account activity.',
        'required'    => true,   // Users cannot unsubscribe from required categories
    ],
    'marketing' => [
        'label'       => 'Marketing Emails',
        'description' => 'Product updates, promotions, and newsletters.',
        'required'    => false,
    ],
    'digest' => [
        'label'       => 'Activity Digest',
        'description' => 'A summary of your recent activity.',
        'required'    => false,
        'frequency'   => ['instant', 'daily', 'weekly', 'never'],
    ],
],

php artisan email-preferences:seed

<?php

namespace App\Notifications;

use Illuminate\Notifications\Notification;
use Illuminate\Notifications\Messages\MailMessage;
use Lchris44\EmailPreferenceCenter\Attributes\EmailCategory;

#[EmailCategory('marketing')]
class NewsletterNotification extends Notification
{
    public function via(object $notifiable): array
    {
        return ['email-preferences'];  // ← replaces 'mail'
    }

    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
            ->subject('Your Weekly Newsletter')
            ->line('Here is what\'s new this week...');
    }
}

return [

    /*
    |----------------------------------------------------------------------
    | Email Categories
    |----------------------------------------------------------------------
    | Define your application's email categories. Each category can be
    | toggled on/off and can optionally support frequency control.
    */
    'categories' => [
        'security' => [
            'label'       => 'Security Alerts',
            'description' => 'Password changes, login alerts, and account activity.',
            'required'    => true,
        ],
        'marketing' => [
            'label'       => 'Marketing Emails',
            'description' => 'Product updates, promotions, and newsletters.',
            'required'    => false,
            'frequency'   => ['instant', 'daily', 'weekly', 'never'],
        ],
    ],

    /*
    |----------------------------------------------------------------------
    | Table Names
    |----------------------------------------------------------------------
    */
    'table_names' => [
        'preferences' => 'email_preferences',
        'logs'        => 'email_preference_logs',
    ],

    /*
    |----------------------------------------------------------------------
    | Auto Scheduling
    |----------------------------------------------------------------------
    | Automatically register digest schedule commands. Set to false if
    | you want to register the schedules yourself.
    */
    'auto_schedule' => env('EMAIL_PREFERENCES_AUTO_SCHEDULE', true),

    /*
    |----------------------------------------------------------------------
    | Digest Schedules (Cron expressions)
    |----------------------------------------------------------------------
    */
    'digest_schedules' => [
        'daily'  => env('EMAIL_PREFERENCES_DAILY_SCHEDULE', '0 8 * * *'),   // 08:00 daily
        'weekly' => env('EMAIL_PREFERENCES_WEEKLY_SCHEDULE', '0 8 * * 1'),  // 08:00 Monday
    ],

    /*
    |----------------------------------------------------------------------
    | Signed URL Expiry
    |----------------------------------------------------------------------
    */
    'signed_url_expiry_days' => env('EMAIL_PREFERENCES_URL_EXPIRY_DAYS', 30),

    /*
    |----------------------------------------------------------------------
    | Digest Mailable
    |----------------------------------------------------------------------
    | The mailable used to send digest emails. Must accept:
    | (mixed $notifiable, Collection $items, string $frequency)
    */
    'digest_mailable' => \Lchris44\EmailPreferenceCenter\Mail\DigestMail::class,

    /*
    |----------------------------------------------------------------------
    | Digest Queue
    |----------------------------------------------------------------------
    | Set a queue name to dispatch digests asynchronously, or null for sync.
    */
    'digest_queue' => env('EMAIL_PREFERENCES_DIGEST_QUEUE', null),

    /*
    |----------------------------------------------------------------------
    | Notification Category Map
    |----------------------------------------------------------------------
    | Map third-party notification classes to categories when you cannot
    | add a PHP attribute or implement the interface yourself.
    */
    'notification_categories' => [
        // \Vendor\BillingNotification::class => 'billing',
    ],

];

public function via(object $notifiable): array
{
    // Use 'email-preferences' instead of 'mail'
    return ['email-preferences', 'database'];
}

use Lchris44\EmailPreferenceCenter\Attributes\EmailCategory;

#[EmailCategory('marketing')]
class NewsletterNotification extends Notification
{
    // ...
}

use Lchris44\EmailPreferenceCenter\Contracts\HasEmailCategory;

class MarketingNotification extends Notification implements HasEmailCategory
{
    public function emailCategory(): string
    {
        return 'marketing';
    }
}

'notification_categories' => [
    \Vendor\Package\BillingNotification::class => 'billing',
    \Vendor\Package\ReceiptNotification::class => 'billing',
],

// User has no preference row for 'marketing'
$user->prefersEmail('marketing');   // true  — opt-in by default
$user->emailFrequency('marketing'); // 'instant' — default frequency

// Check if a user wants emails in a category
$user->prefersEmail('marketing');  // bool

// Get current frequency setting
$user->emailFrequency('digest');  // 'instant' | 'daily' | 'weekly' | 'never'

// Subscribe a user to a category
$user->subscribe('marketing', 'admin');

// Unsubscribe a user from a category
$user->unsubscribe('marketing', 'api');

// Set digest frequency
$user->setEmailFrequency('digest', 'weekly', 'preference_center');
// Frequency options: 'instant' | 'daily' | 'weekly' | 'never'

// Get all preferences for a user
$user->emailPreferences;

// Get the audit log
$user->emailPreferenceLogs;

// Query a specific preference
$user->emailPreferences()
    ->where('category', 'marketing')
    ->first();

use Lchris44\EmailPreferenceCenter\Support\SignedUnsubscribeUrl;

$url = SignedUnsubscribeUrl::generateForCenter($user);

// Include this URL in your emails
return (new MailMessage)
    ->line('Manage your email preferences:')
    ->action('Email Preferences', $url);

<!-- In any email template -->
<a href="{{ $preferenceCenterUrl }}">
    Manage email preferences
</a>

php artisan vendor:publish --tag=email-preferences-views

<?php

namespace App\Mail;

use Illuminate\Mail\Mailable;
use Lchris44\EmailPreferenceCenter\Traits\BelongsToCategory;

class NewsletterMail extends Mailable
{
    use BelongsToCategory;

    public function __construct(
        protected $notifiable,
        protected string $category = 'marketing'
    ) {}

    public function build()
    {
        // BelongsToCategory automatically appends:
        // List-Unsubscribe: <https://app.test/email-preferences/unsubscribe?...>
        // List-Unsubscribe-Post: List-Unsubscribe=One-Click
        return $this->view('emails.newsletter');
    }
}

use Lchris44\EmailPreferenceCenter\Support\SignedUnsubscribeUrl;

$unsubscribeUrl = SignedUnsubscribeUrl::generate($user, 'marketing');

#[EmailCategory('digest')]
class OrderShippedNotification extends Notification
{
    public function via(object $notifiable): array
    {
        return ['email-preferences'];
    }

    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
            ->subject('Your order has shipped')
            ->line('Order #1234 is on its way.')
            ->action('Track order', url('/orders/1234'));
    }
}

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

use Lchris44\EmailPreferenceCenter\Jobs\DigestQueue;

DigestQueue::dispatch(
    notifiable: $user,
    category:   'digest',
    type:       'order_shipped',
    payload:    [
        'subject' => 'Your order has shipped',
        'lines'   => ['Order #1234 is on its way.'],
    ]
);

php artisan vendor:publish --tag=email-preferences-mailable

'digest_mailable' => \App\Mail\MyDigestMail::class,
// Constructor must accept: ($notifiable, Collection $items, string $frequency)

EMAIL_PREFERENCES_DIGEST_QUEUE=emails

// Was the user subscribed at a specific point in time?
$wasSubscribed = $user->wasSubscribedTo('marketing', '2026-01-01');  // bool

// Get the most recent consent record for a category
$log = $user->lastConsentFor('marketing');
// $log->action     => 'subscribed'
// $log->via        => 'preference_center'
// $log->ip_address => '192.168.1.1'
// $log->user_agent => 'Mozilla/5.0...'
// $log->created_at => Carbon instance

// Query all logs directly
$user->emailPreferenceLogs()
    ->where('category', 'marketing')
    ->orderBy('created_at', 'desc')
    ->get();

use Lchris44\EmailPreferenceCenter\Events\PreferenceUpdated;
use Lchris44\EmailPreferenceCenter\Events\UserUnsubscribed;

protected $listen = [
    PreferenceUpdated::class => [
        \App\Listeners\SyncPreferencesToCrm::class,
    ],
    UserUnsubscribed::class => [
        \App\Listeners\NotifyMarketingTeam::class,
    ],
];

# Send all queued daily digest items
php artisan email-preferences:send-digests daily

# Send all queued weekly digest items
php artisan email-preferences:send-digests weekly

# Normal use — skips rows that already exist
php artisan email-preferences:seed

# Target a specific model (defaults to App\Models\User)
php artisan email-preferences:seed --model=App\\Models\\Organization

# Reset everyone to weekly digest
php artisan email-preferences:seed --frequency=weekly --force