README

A Laravel package to check the spam score of email contents before sending them using the SpamAssassin filter API.

Features

✅ Check email spam scores using SpamAssassin API
✅ Simple and intuitive API
✅ Facade support for easy access
✅ Fully configurable
✅ Supports both "short" and "long" report formats
✅ Works with Laravel 11 and 12
✅ Well tested
✅ PHP 8.3+ support

Requirements

PHP >= 8.3
Laravel ^11.0 | ^12.0

Installation

You can install the package via Composer:

composer require palpalani/laravel-spamassassin-score

The package will automatically register its service provider and facade.

Configuration

You can publish the config file with:

php artisan vendor:publish --tag="laravel-spamassassin-score-config"

This is the contents of the published config file:

return [
    'api' => 'https://spamcheck.postmarkapp.com/filter',

    // Default "long". Must either be "long" for a full report of processing rules, or "short" for a score request.
    'option' => 'long'
];

Configuration Options

api: The SpamAssassin API endpoint URL
option: The report format - either "long" for a full report of processing rules, or "short" for a score request only

Usage

Using the Facade

use palPalani\SpamassassinScore\Facades\SpamassassinScore;

// Get spam score with default configuration
$result = SpamassassinScore::getScore($emailContent);

// The result will contain:
// - 'score': The spam score
// - 'success': Whether the check was successful
// Additional fields when using 'long' option format

Using Dependency Injection

use palPalani\SpamassassinScore\SpamassassinScore;

class EmailController extends Controller
{
    public function __construct(
        private SpamassassinScore $spamassassinScore
    ) {}

    public function checkEmail(Request $request)
    {
        $result = $this->spamassassinScore->getScore($request->input('email'));
        
        if ($result['score'] > 5.0) {
            return response()->json(['message' => 'Email may be spam'], 400);
        }
        
        // Proceed with sending email
    }
}

Using Direct Instantiation

use palPalani\SpamassassinScore\SpamassassinScore;

$spamassassinScore = new SpamassassinScore();
$result = $spamassassinScore->getScore($emailContent);

// Access the score
$score = $result['score'] ?? null;

Example Response

When using the default "long" option, the response includes:

[
    'success' => true,
    'score' => 2.5,
    'rules' => [
        // Full list of rules that matched
    ],
    'description' => '...'
]

When using "short" option, the response is:

[
    'success' => true,
    'score' => 2.5
]

Testing

Run the tests with:

composer test

For test coverage:

composer test-coverage

Code Quality Tools

This package uses several code quality tools:

PHPUnit - Testing framework
Pest - Testing framework (alternative)
Laravel Pint - Code style fixing (powered by PHP CS Fixer)
PHPStan - Static analysis
Larastan - Laravel-specific static analysis (PHPStan extension)

Run static analysis:

composer analyse  # PHPStan

Run code formatting:

composer format  # Laravel Pint

Changelog

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

Contributing

Please see CONTRIBUTING for details on our code of conduct, and the process for submitting pull requests.

palpalani / laravel-spamassassin-score

Maintainers

Details