Custom Integration: Command Line

SpamFoo runs as a local HTTP service. There is no separate command line classification mode. Instead, you start the service once, then send emails to it from the command line with standard tools like curl. This works well for testing, scripting, and batch processing of email archives.

Starting the Service

If you installed SpamFoo as a system service, it is already running and you can skip to Verify the Service is Running. To start it by hand, run: 

./spamfoo-client --data-dir=/var/lib/spamfoo --models-dir=/var/lib/spamfoo/models

The service starts an HTTP server on http://localhost:16253 and keeps running until you stop it (press Ctrl+C).

Argument Description
--data-dir Where SpamFoo stores its database, logs, and personalization data. Defaults to the application directory.
--models-dir Where the ML model files are located.
--config-dir Where configuration files are located. Defaults to the data directory.
--debug Enables debug logging for troubleshooting.

A ~ at the start of a path expands to your home directory. See Configuration for environment variables and other settings.

Verify the Service is Running

curl http://localhost:16253/health

A healthy service returns 200 with a JSON body that includes "status": "healthy". If the request fails, check that the service started and that nothing else is using port 16253. See Common Issues for help.

Classifying an Email

Send the raw .eml content to the /classify-stream endpoint: 

curl -X POST http://localhost:16253/classify-stream \
    -H "Content-Type: message/rfc822" \
    --data-binary @message.eml

SpamFoo returns a JSON result: 

{
    "isSpam": false,
    "spamProbability": 0.12,
    "classification": "primary",
    ...
}

You can pass optional headers (X-Sender-IP, X-Sender-Email, X-User-ID) to improve accuracy and enable per-user personalization. See the Local API guide for the full request and response reference. Classifying by file path is coming soon; stream the content for now.

Batch Processing

Because the service keeps its models loaded in memory between requests, you can classify a directory of .eml files with a simple shell loop: 

#!/bin/bash
for file in /path/to/emails/*.eml; do
    result=$(curl -s -X POST http://localhost:16253/classify-stream \
        -H "Content-Type: message/rfc822" \
        --data-binary @"$file")
    echo "$file: $result"
done

To act on the results, parse the JSON with a tool like jq. This example sorts messages into folders by their classification: 

#!/bin/bash
for file in /path/to/emails/*.eml; do
    class=$(curl -s -X POST http://localhost:16253/classify-stream \
        -H "Content-Type: message/rfc822" \
        --data-binary @"$file" | jq -r '.classification')
    mkdir -p "/path/to/sorted/$class"
    cp "$file" "/path/to/sorted/$class/"
done

If SpamFoo is under heavy load it may return a 503 when its request queue is full. In scripts, treat a 503 as a signal to wait and retry.

Testing a Classification Decision

To see how SpamFoo reached a decision for a specific message, use the diagnostic endpoint. It returns a detailed breakdown including per-model scores and timing: 

curl -X POST http://localhost:16253/classify/diagnostic-stream \
    -H "Content-Type: message/rfc822" \
    --data-binary @message.eml

See Diagnostic Tools for more ways to investigate classification results.

Next Steps