spamc-client

PHP client for SpamAssassin's spamd protocol (SPAMC v1.5). Requires PHP 8.2+.

Installation

composer require monadial/spamc-client

Quick Start

use Monadial\SpamcClient\Client\Client;

$client = Client::tcp('localhost');

$response = $client->check($emailMessage);

$response->isSpam();       // bool
$response->getScore();     // float
$response->getThreshold(); // float

Unix Socket

$client = Client::unix('/var/run/spamd.sock');

TCP with SSL

use Monadial\SpamcClient\Connection\SslConfig;

$client = Client::tcp('spamd.example.com', 783, 30, SslConfig::withCaFile('/etc/ssl/certs/ca.pem'));

Commands

All commands are available as convenience methods on the client:

$client->check($message);        // check if spam
$client->symbols($message);      // matched rule names
$client->report($message);       // full spam report
$client->reportIfSpam($message); // report only if spam
$client->process($message);      // message with X-Spam-* headers added
$client->headers($message);      // modified headers only
$client->ping();                 // health check

Spam Results

$response = $client->check($message);

if ($response->isSpam()) {
    echo "Spam! Score: {$response->getScore()} / {$response->getThreshold()}";
}

// Or use the structured result
$result = $response->spamResult();
if ($result !== null) {
    echo "Margin: {$result->margin()}"; // positive = spam
}

Training (TELL)

use Monadial\SpamcClient\Header\ActionHeader;
use Monadial\SpamcClient\Protocol\MessageClass;

// Report spam
$client->tell($message, MessageClass::Spam, ActionHeader::setLocal());

// Report ham
$client->tell($message, MessageClass::Ham, ActionHeader::setLocal());

Error Handling

All exceptions implement SpamcException:

SpamcException (interface)
├── ConnectionException
│   └── TimeoutException
├── ParseException
└── RequestException

use Monadial\SpamcClient\Exception\SpamcException;

try {
    $response = $client->check($message);
    $response->raiseForStatus(); // throws RequestException on non-success status
} catch (SpamcException $e) {
    // handle error
}

Documentation

• Getting Started
• Connection Options
• Commands
• Training (TELL)
• Error Handling
• Advanced Usage

License

MIT