Read and Change Settings

Read SpamFoo Client's saved settings, or change them from a script. These endpoints change the same settings as the System > Settings page in the admin console, plus a few that aren't on it.

• Both endpoints require the proxy secret, even from loopback, and have no license check. See Authenticate Requests.
• A request with the proxy secret is treated as a system administrator. Do not send X-User-ID on these requests. With it, the request is treated as a dashboard user and returns 403.
• For the keys you can send, see Settings You Can Change.

Read Settings

Returns every setting saved in SpamFoo Client's local database, grouped by the part of the key before the first dot. A key with no dot is grouped under General.

{
    "Backup": [
        {
            "key": "Backup.HourOfDay",
            "value": "2",
            "valueType": "Int",
            "updatedUtc": "2026-10-01T09:15:42.1234567Z",
            "updatedBy": "local"
        }
    ],
    "Retention": [
        {
            "key": "Retention.DayAggregatesDays",
            "value": "30",
            "valueType": "String",
            "updatedUtc": "2026-10-07T14:02:11.7654321Z",
            "updatedBy": "local"
        }
    ]
}

• Missing keys: a setting that has never been saved isn't listed, and SpamFoo Client uses its default. Some defaults are saved when SpamFoo Client first starts, so those are listed.
• Internal keys: the response can include keys SpamFoo Client manages itself, such as the Migration group. Do not change them.

Change Settings

Saves one or more settings. Send a JSON object whose names are setting keys and whose values are strings. The request needs Content-Type: application/json.

{
    "Retention.DayAggregatesDays": "30",
    "Backup.Enabled": "true"
}

• Send every value as a string, such as "30" or "true". A JSON number or true without quotes returns 400.
• Keys you leave out don't change. You only need to send the settings you're changing.
• All or nothing: if any value fails a check, the request returns 400 and nothing is saved.
• Few values are checked. SpamFoo Client checks only the values listed under Errors. Other values are saved as sent, so check the allowed values in Settings You Can Change first.
• Key names aren't checked. A misspelled key is saved and then ignored. Read the settings back to confirm a change.
• When changes apply: saved values are used right away, with no restart. They win over environment variables and command-line options, except that SPAMFOO_GPU still overrides Features.GpuAcceleration.

Change Response

A successful request returns 200 with the number of keys saved.

{
    "updated": 2
}

Settings You Can Change

Send these keys to PUT /admin/api/settings. When a setting is also on System > Settings in the admin console, its Settings page line shows the card and field where it appears.

Scan Queue

These settings control where messages wait to be scanned. Mail being delivered waits in the spool queue and gets first claim on the scanning slots. Requests to Classify Without Spam Checks wait in the background queue.

Spam Filtering

Model Processing

Dashboard Display

Scan History and Message Content

Mail Totals

SpamFoo Client keeps per-minute, per-hour, and per-day mail totals for the dashboard charts. Only this API can change how long they are kept.

Backups

Errors

Example

This example keeps 30 days of per-day totals, then reads the settings back to confirm the change.

curl -X PUT http://localhost:16253/admin/api/settings \
    -H "Content-Type: application/json" \
    -H "X-SpamFoo-Proxy-Auth: $SPAMFOO_PROXY_SECRET" \
    -d '{"Retention.DayAggregatesDays": "30"}'

curl http://localhost:16253/admin/api/settings \
    -H "X-SpamFoo-Proxy-Auth: $SPAMFOO_PROXY_SECRET"

using System.Net.Http.Json;
using System.Text.Json;

var secret = Environment.GetEnvironmentVariable("SPAMFOO_PROXY_SECRET")
    ?? throw new InvalidOperationException("Set SPAMFOO_PROXY_SECRET.");

using var http = new HttpClient { BaseAddress = new Uri("http://localhost:16253") };
http.DefaultRequestHeaders.Add("X-SpamFoo-Proxy-Auth", secret);

var changes = new Dictionary<string, string> { ["Retention.DayAggregatesDays"] = "30" };
using var response = await http.PutAsJsonAsync("/admin/api/settings", changes);
response.EnsureSuccessStatusCode();

var settings = await http.GetFromJsonAsync<Dictionary<string, JsonElement[]>>("/admin/api/settings");
var saved = settings!["Retention"]
    .First(s => s.GetProperty("key").GetString() == "Retention.DayAggregatesDays");
Console.WriteLine($"Per-day totals kept: {saved.GetProperty("value").GetString()} days");

import os

import requests

SPAMFOO_URL = "http://localhost:16253"
HEADERS = {"X-SpamFoo-Proxy-Auth": os.environ["SPAMFOO_PROXY_SECRET"]}

response = requests.put(
    f"{SPAMFOO_URL}/admin/api/settings",
    json={"Retention.DayAggregatesDays": "30"},
    headers=HEADERS,
    timeout=30,
)
response.raise_for_status()

response = requests.get(f"{SPAMFOO_URL}/admin/api/settings", headers=HEADERS, timeout=30)
response.raise_for_status()
saved = next(
    s for s in response.json()["Retention"] if s["key"] == "Retention.DayAggregatesDays"
)
print(f"Per-day totals kept: {saved['value']} days")