Use the Command Line

This page shows how to start SpamFoo Client from a terminal and classify saved messages with curl. It is useful for testing, scripts, and sorting a folder of .eml files.

The spamfoo-client program has no classify command. Running it with no command, or with run, starts the local HTTP service, and you classify messages by sending HTTP requests to that service. The service keeps its models loaded between requests, so classifying many files in a row is fast.

The program also has admin commands, such as login-link, activate, and status. See Use SpamFoo Client Commands.

Start the Service

If SpamFoo Client already runs as a service or a Docker container, skip to Check the Service. To start it by hand, run it from its install folder: 

.\spamfoo-client.exe --data-dir=C:\SpamFoo\data
./spamfoo-client --data-dir=/var/lib/spamfoo

The service listens on http://localhost:16253 and runs until you press Ctrl+C. To install it as a Windows service, a systemd service, or a Docker container, see Install SpamFoo Client.

Startup Options

Write each option with an equals sign, such as --data-dir=/var/lib/spamfoo. When you start the service, a space instead of = is not recognized.

Option What It Does
--data-dir=<path> Folder for SpamFoo Client's databases, logs, and personalization data. Defaults to the install folder.
--models-dir=<path> Folder for model files. Defaults to the trained-models folder inside the data directory.
--config-dir=<path> Folder that holds etc/sf.key (the license key) and etc/sf.proxysecret (the proxy secret). Defaults to the data directory. Passing this option also tells SpamFoo Client that a host program, such as SmarterMail, manages it and supplies the proxy secret. Leave it out for a standalone install.
--mode=<mode> embedded (the default) or standalone. See Mode.
--port=<number> The port to listen on. Standalone mode only. Defaults to 16253.
--conf=<path> A settings file to read. See Settings File.
--auto-send-training Turns on automatic training reports, which send data about some classified messages to SpamFoo to help improve the global models. Off unless you pass this option or set SPAMFOO_AUTO_SEND_TRAINING=true. See Automatic Training Reports.

In --data-dir and --models-dir, a ~ is replaced with your home folder. Most other settings are environment variables; see Configure SpamFoo Client.

Check the Service

curl http://localhost:16253/health/ready

A service that can classify mail returns 200 and {"status":"ready","contract":1}. A 503 lists the reasons it isn't ready yet, such as models_loading. If the request fails, check that the service started and that nothing else uses port 16253. See Fix Common Problems.

Proxy secret Add -H "X-SpamFoo-Proxy-Auth: $SPAMFOO_PROXY_SECRET" to each curl command below. See Authenticate Requests for when it's required.

Classify One Message

Post the raw message to /classify-stream: 

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

Use --data-binary, not -d. The -d option strips line breaks and changes the message.

The response is JSON. These are the fields you will look at most (the full response has more): 

{
    "isSpam": false,
    "classification": "promotions",
    "spamProbability": 0.09,
    "displayConfidence": 0.12,
    "shouldEscalate": false,
    "bypassReason": null
}

To test personalization or rules for a specific mailbox, add delivery headers such as X-User-ID, X-Sender-IP, and X-Sender-Email. Start With the Local API explains each header and field.

Classify a Folder of Messages

A loop sends each file in turn. These examples print each file name with its result. 

Get-ChildItem C:\mail\saved\*.eml | ForEach-Object {
    $result = Invoke-RestMethod -Method Post `
        -Uri http://localhost:16253/classify-stream `
        -ContentType "message/rfc822" `
        -InFile $_.FullName
    "{0}: isSpam={1} classification={2}" -f $_.Name, $result.isSpam, $result.classification
}
#!/bin/bash
for file in /path/to/mail/*.eml; do
    result=$(curl -s -X POST http://localhost:16253/classify-stream \
        -H "Content-Type: message/rfc822" \
        --data-binary @"$file")
    echo "$file: $result"
done

This Linux example copies each message into a folder named after its result. It uses jq to read the JSON. 

#!/bin/bash
for file in /path/to/mail/*.eml; do
    result=$(curl -s -f -X POST http://localhost:16253/classify-stream \
        -H "Content-Type: message/rfc822" \
        --data-binary @"$file") || { echo "$file: no result" >&2; continue; }

    if [ "$(echo "$result" | jq -r '.isSpam')" = "true" ]; then
        folder="spam"
    else
        folder=$(echo "$result" | jq -r '.classification | ascii_downcase')
        [ -z "$folder" ] && folder="unclassified"
    fi

    mkdir -p "/path/to/sorted/$folder"
    cp "$file" "/path/to/sorted/$folder/"
done

If SpamFoo Client is busy, it returns 503. In a script, wait the number of seconds in the Retry-After header and retry the file. To keep a large batch from competing with live mail, add -H "X-SpamFoo-Priority: bulk". See Mark Bulk Work.

Classifying files this way records each message in the admin console, the same as live mail.

Send a Correction

You can also send corrections from the command line. Correction requests always need the proxy secret, even from localhost. See Send Corrections Back for examples.

Next Steps