README

Laravel Spam

A pragmatic anti-spam toolkit for Laravel applications. Block disposable and throwaway email signups, reject known bad actors via StopForumSpam, and configure your own allow/blocklists — with validation rules, middleware, and a check API.

📖 Table of Contents

• Laravel Spam
  • 📖 Table of Contents
  • Features
  • 🌟 Sponsors
  • 📦 Installation
  • ⚙️ Configuration
  • 🚀 Usage
    • The Spam::check() API
    • Validation rules
    • Route middleware
    • Individual rules
  • 🔄 Keeping the disposable list fresh
  • 📚 API Reference
    • Facade methods
    • Validation rules
    • Middleware
    • Console
  • 🧪 Testing
  • 📋 Changelog
  • 🤝 Contributing
  • 🔒 Security Vulnerabilities
  • 💖 Support This Project
  • ⭐ Star History
  • 📦 Other Packages
  • 📄 License
  • ⚖️ Disclaimer

Features

• 🚫 Block disposable / throwaway email providers (bundled list of 70k+ domains)
• 🌐 StopForumSpam lookups with caching and a fail-open default
• 📋 Configurable blocklists for domains and TLDs
• ✅ Drop-in validation rules for any FormRequest or Validator::make() call
• 🛡️ Route middleware for protecting any endpoint that accepts an email
• 🔍 A single Spam::check() API that returns a typed reason
• 🔄 Artisan command to refresh the disposable-email list from upstream
• 🧪 Zero database tables, zero external auth, zero required API keys

🌟 Sponsors

Your logo here — Become a sponsor and get your logo featured in this README and on our website.

Interested in title sponsorship? Contact us at sponsors@climactic.co for premium placement and recognition.

📦 Installation

You can install the package via composer:

composer require climactic/laravel-spam

Optionally publish the config file:

php artisan vendor:publish --tag="laravel-spam-config"

Optionally publish the bundled disposable-email list to local storage (only needed if you plan to refresh it yourself — see below):

php artisan vendor:publish --tag="laravel-spam-data"

⚙️ Configuration

The config file lives at config/spam.php. Every option is documented inline:

return [
    'default_field' => env('SPAM_DEFAULT_FIELD', 'email'),
    'message' => env('SPAM_MESSAGE', 'This email address is not allowed. Please use a different one.'),

    // `blocked_tlds` / `blocked_domains` accept a comma-separated
    // env override — see the .env snippet below.
    'blocked_tlds' => ['tk', 'ml', 'cf', 'ga', 'gq'],
    'blocked_domains' => [
        // 'example.com',
    ],

    'disposable' => [
        'enabled' => env('SPAM_DISPOSABLE_ENABLED', true),
        'storage_path' => env('SPAM_DISPOSABLE_STORAGE_PATH', storage_path('app/laravel-spam/disposable-domains.json')),
        'source_url' => env('SPAM_DISPOSABLE_SOURCE_URL', 'https://cdn.jsdelivr.net/gh/disposable/disposable-email-domains@master/domains.json'),
        'cache_ttl' => env('SPAM_DISPOSABLE_CACHE_TTL'), // null = forever
    ],

    'stopforumspam' => [
        'enabled' => env('STOPFORUMSPAM_ENABLED', true),
        'frequency' => (int) env('STOPFORUMSPAM_FREQUENCY', 3),
        'cache_ttl' => (int) env('STOPFORUMSPAM_CACHE_TTL', 3600),
        'timeout' => (int) env('STOPFORUMSPAM_TIMEOUT', 5),
    ],
];

Everything is env-driven, so you can tune the package from .env without publishing the config:

SPAM_DEFAULT_FIELD=email
SPAM_MESSAGE="This email address is not allowed. Please use a different one."
SPAM_BLOCKED_TLDS="tk,ml,cf,ga,gq"
SPAM_BLOCKED_DOMAINS="example.com,another.test"

SPAM_DISPOSABLE_ENABLED=true
SPAM_DISPOSABLE_STORAGE_PATH=           # Override the JSON path
SPAM_DISPOSABLE_SOURCE_URL=             # Override the upstream list URL
SPAM_DISPOSABLE_CACHE_TTL=              # null = forever

STOPFORUMSPAM_ENABLED=true
STOPFORUMSPAM_FREQUENCY=3               # Min appearances to count as spam
STOPFORUMSPAM_CACHE_TTL=3600
STOPFORUMSPAM_TIMEOUT=5

No API key required — StopForumSpam lookups are anonymous and this package does not submit reports.

🚀 Usage

The Spam::check() API

Get a structured verdict for any email:

use Climactic\Spam\Facades\Spam;
use Climactic\Spam\Enums\SpamReason;

$result = Spam::check($email);

if ($result->isSpam) {
    Log::warning('Blocked signup', [
        'email' => $email,
        'reason' => $result->reason->value, // 'disposable', 'blocked_tld', …
    ]);
}

SpamReason cases: Clean, InvalidEmail, BlockedDomain, BlockedTld, Disposable, StopForumSpam.

Convenience predicates:

Spam::isSpamEmail($email);        // bool — any spam signal
Spam::isDisposable($email);       // bool
Spam::isBlockedDomain($email);    // bool — exact domain *or* TLD match
Spam::isStopForumSpam($email);    // bool

Validation rules

Use Spam::emailRules() in any FormRequest or inline validator. It returns Laravel's standard email rules plus the three spam rules — append your own extras (like unique:) as needed:

use Climactic\Spam\Facades\Spam;

public function rules(): array
{
    return [
        'email' => Spam::emailRules([
            'unique:'.User::class,
        ]),
    ];
}

Or drop it into an inline validator:

Validator::make($data, [
    'email' => Spam::emailRules(),
])->validate();

Route middleware

Protect any endpoint that accepts an email field with the spam.email middleware alias. A flagged email yields a standard 422 validation response.

Route::post('/register', RegisterController::class)
    ->middleware('spam.email');

Route::post('/contact', ContactController::class)
    ->middleware('spam.email:contact_email'); // custom field name

If no parameter is passed, the middleware reads config('spam.default_field') (default: email).

Individual rules

If you want to reach for a specific rule directly:

use Climactic\Spam\Rules\BlockedEmailDomain;
use Climactic\Spam\Rules\DisposableEmail;
use Climactic\Spam\Rules\StopForumSpamEmail;

$data->validate([
    'email' => [
        'required', 'email',
        app(BlockedEmailDomain::class),
        app(DisposableEmail::class),
        app(StopForumSpamEmail::class),
    ],
]);

🔄 Keeping the disposable list fresh

The package ships with a snapshot of disposable/disposable-email-domains. To refresh from upstream on your own schedule, run:

php artisan spam:update

The command writes to config('spam.disposable.storage_path') (default: storage/app/laravel-spam/disposable-domains.json) and clears the cache. Recommended: schedule it monthly:

use Illuminate\Support\Facades\Schedule;

Schedule::command('spam:update')->monthly();

📚 API Reference

Facade methods

Validation rules

Middleware

Console

🧪 Testing

composer test

📋 Changelog

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

🤝 Contributing

Please see CONTRIBUTING for details. You can also join our Discord server to discuss ideas and get help: Discord Invite.

🔒 Security Vulnerabilities

Please report security vulnerabilities to security@climactic.co.

💖 Support This Project

Laravel Spam is free and open source, built and maintained with care. If this package has saved you development time or helped power your application, please consider supporting its continued development.

⭐ Star History

📦 Other Packages

Other open-source Laravel packages from Climactic:

📄 License

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

⚖️ Disclaimer

This package is not affiliated with Laravel. It's for Laravel but is not by Laravel. Laravel is a trademark of Taylor Otwell. Disposable-domain data is sourced from the disposable/disposable-email-domains community project.