README

Distributed rate limiting for Laravel mail across multiple queue workers.

Problem

Email providers have rate limits:

• Resend: 2/sec (free), 100/sec (pro)
• Postmark: 10/sec
• SES: 14/sec (default)
• Mailgun: Varies by plan

Their SDKs don't handle this. When you dispatch 1,000 notifications, your queue workers blast them out and you hit 429 errors.

Solution

This package provides:

• Distributed throttling via Redis - works across multiple Horizon workers
• Opt-in per class - add a trait to enable throttling
• Config in mail.php - rate limits live with your mailer config
• Dynamic backoff with jitter - prevents thundering herd at scale
• Fail-safe - configurable behavior when Redis is unavailable

Requirements

• PHP 8.2+
• Laravel 10, 11, or 12
• Redis (required for distributed throttling)

Installation

composer require ctsoftwarellc/laravel-mail-throttle

Optionally publish the config:

php artisan vendor:publish --tag=mail-throttle-config

Configuration

Add rate limits to your mailers in config/mail.php:

'mailers' => [
    'resend' => [
        'transport' => 'resend',
        'rate_limit' => env('MAIL_RATE_LIMIT', 2),        // emails per window
        'rate_limit_per' => env('MAIL_RATE_LIMIT_PER', 1), // window in seconds
    ],

    'postmark' => [
        'transport' => 'postmark',
        'rate_limit' => 10,
        'rate_limit_per' => 1,
    ],

    // No rate_limit = no throttling (existing behavior preserved)
    'smtp' => [
        'transport' => 'smtp',
    ],
],

Usage

Notifications

Add the ThrottlesMail trait to your queued notifications:

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;
use Ctsoftwarellc\MailThrottle\Concerns\ThrottlesMail;

class WelcomeNotification extends Notification implements ShouldQueue
{
    use Queueable, ThrottlesMail;

    public function via(object $notifiable): array
    {
        return ['mail'];
    }

    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
            ->subject('Welcome!')
            ->line('Thanks for joining.');
    }
}

Mailables

Add the trait to your queued mailables:

<?php

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Queue\SerializesModels;
use Ctsoftwarellc\MailThrottle\Concerns\ThrottlesMail;

class InvoiceMail extends Mailable implements ShouldQueue
{
    use Queueable, SerializesModels, ThrottlesMail;

    public function content(): Content
    {
        return new Content(view: 'emails.invoice');
    }
}

Custom Rate Limits

Override the config-based limits per class:

use Ctsoftwarellc\MailThrottle\Middleware\ThrottleMail;

class BulkNotification extends Notification implements ShouldQueue
{
    use Queueable;

    public function middleware(): array
    {
        // 1 email per 2 seconds for bulk sends
        return [new ThrottleMail(maxAttempts: 1, perSeconds: 2)];
    }
}

Specify a Different Mailer

public function middleware(): array
{
    // Use postmark's rate limit config
    return [new ThrottleMail(mailer: 'postmark')];
}

How It Works

+-------------+     +-------------+     +-------------+
|  Worker 1   |     |  Worker 2   |     |  Worker 3   |
+------+------+     +------+------+     +------+------+
       |                   |                   |
       +-------------------+-------------------+
                           |
                           v
                 +-------------------+
                 |   Redis Throttle  |
                 |  (Atomic Counter) |
                 +-------------------+
                           |
           +---------------+---------------+
           v                               v
   +---------------+               +---------------+
   | Under limit   |               | At limit      |
   | -> Send email |               | -> Release    |
   +---------------+               |    w/ backoff |
                                   |    + jitter   |
                                   +---------------+

All workers share the same Redis key per mailer, so the rate limit is global across your entire application.

Dynamic Backoff & Jitter

When a job is throttled, the release delay is calculated dynamically:

1. Base delay: Calculated from your rate limit (e.g., 2/sec = 500ms base)
2. Exponential backoff: Increases with retry attempts (1x, 2x, 4x, 8x...)
3. Random jitter: 0-50% random addition to spread out retries

This prevents thundering herd issues when scaling to 10-50+ workers, where all workers would otherwise wake up simultaneously and compete for the same rate limit slots.

Package Config

Publish with php artisan vendor:publish --tag=mail-throttle-config

return [
    // Maximum delay before retrying (caps exponential backoff)
    'max_release_delay' => env('MAIL_THROTTLE_MAX_RELEASE_DELAY', 30),

    // Cap for backoff multiplier (1x, 2x, 4x, 8x max by default)
    'max_backoff_multiplier' => env('MAIL_THROTTLE_MAX_BACKOFF', 8),

    // Random jitter (0.5 = add 0-50% to each delay)
    'jitter_percent' => env('MAIL_THROTTLE_JITTER', 0.5),

    // Send emails anyway if Redis is unavailable?
    'fail_open' => env('MAIL_THROTTLE_FAIL_OPEN', true),

    // Redis key prefix (defaults to cache.prefix or app.name)
    'key_prefix' => env('MAIL_THROTTLE_KEY_PREFIX'),
];

Tuning for High Scale

For deployments with many workers (10-50+):

# Increase max delay to reduce Redis contention
MAIL_THROTTLE_MAX_RELEASE_DELAY=60

# Higher jitter for better distribution
MAIL_THROTTLE_JITTER=0.75

For low-latency requirements:

# Lower max delay for faster throughput
MAIL_THROTTLE_MAX_RELEASE_DELAY=10

# Lower backoff cap
MAIL_THROTTLE_MAX_BACKOFF=4

Multi-Channel Notifications

The middleware only throttles the mail channel. Other channels (SMS, Slack, database) pass through without throttling:

public function via(object $notifiable): array
{
    return ['mail', 'database', 'vonage']; // Only mail is throttled
}

License

MIT License. See LICENSE for details.