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

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

Method	Description
`Spam::check(string $email): SpamResult`	Full check; returns `{isSpam, reason}`
`Spam::isSpamEmail(string $email): bool`	True if any signal fires
`Spam::isDisposable(string $email): bool`	True if the domain is in the disposable list
`Spam::isBlockedDomain(string $email): bool`	True if the domain or TLD is blocklisted
`Spam::isStopForumSpam(string $email): bool`	True if StopForumSpam flags the email
`Spam::emailRules(array $extra = []): array`	Email validation rules; append extras

Validation rules

Rule	Class
Blocked domain / TLD	`Climactic\Spam\Rules\BlockedEmailDomain`
Disposable email	`Climactic\Spam\Rules\DisposableEmail`
StopForumSpam lookup	`Climactic\Spam\Rules\StopForumSpamEmail`

Middleware

Alias	Class	Parameter
`spam.email`	`Climactic\Spam\Http\Middleware\BlockSpamEmails`	Request field (defaults to config)

Console

Command	Description
`spam:update`	Refresh the disposable-email list

🧪 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:

Package	Description
climactic/laravel-credits	Ledger-based credit system for virtual currencies, reward points, and credit-based features.
climactic/laravel-polar	Seamless Polar.sh integration for subscriptions, payments, and webhooks.
climactic/laravel-altcha	Drop-in ALTCHA proof-of-work spam protection — privacy-first, self-hosted, no third-party services.

📄 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.

climactic / laravel-spam

Maintainers

Package info

Fund package maintenance!

Statistics

Security

README

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

climactic / laravel-spam

Maintainers

Package info

Fund package maintenance!

Statistics

Security

README

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

The `Spam::check()` API