Classify a Message

Send a raw message to get a spam verdict and an Email Classification in one call. This is the endpoint a mail server calls while it delivers mail.

When to Use It

• Use it for every incoming message you want SpamFoo to judge.
• To get only an Email Classification with no spam or phishing checks, use Classify Without Spam Checks.

SpamFoo Client records each verdict for the admin console. It also caches verdicts: the same message sent again with the same headers returns the cached verdict until a correction clears the cache.

Request

The body is the raw message (raw .eml content), sent unchanged. See Send the Message in the Request Body.

SpamFoo Client reads X-SpamFoo-Boundary and X-SpamFoo-Auth-Results only from requests that send the correct proxy secret, even from loopback. X-SpamFoo- headers inside the message itself are never read as instructions, so a sender can't use them to change the result.

Skip Email Classification

Send X-SpamFoo-Classify: false when you only need the spam verdict. Spam and phishing checks still run.

• The response has the same fields, but classification is an empty string and tabsProbs is an empty array, even for spam and phishing. Use isSpam, bypassReason, and phishingReason instead.
• Values are case-insensitive. Any value other than one true or false returns 400.
• If the license includes Email Classification but not spam detection, the request returns 403 with "features": ["spam"].

Mark Bulk Work

Send X-SpamFoo-Priority: bulk when the request isn't part of live mail delivery, such as when you classify the messages already in a mailbox. Bulk requests have their own, smaller limit on how many can be held at once (one less than Max Concurrency, and at least 1), so they can't crowd out live mail.

• When the bulk limit is full, the request gets 503 with "code": "server_busy", "priority": "bulk", and Retry-After: 2. Wait and send it again.
• Any other value, or no header, is live delivery.
• The bulkIntake counts in Check Health show how the bulk limit is used.

Set a Deadline

Send X-SpamFoo-Deadline-Ms when your process stops waiting after a set time, such as an SMTP session timeout. The time counts from when SpamFoo Client reads the header, so time spent sending the message counts against it.

• When SpamFoo Client expects the wait for a free classification slot to be longer than the time left, it answers right away with 503 and "code": "deadline_exceeded". It also stops waiting when the deadline passes in the queue, and skips work for a caller that has disconnected.
• The body is {"error": "Classification deadline exceeded", "code": "deadline_exceeded", "deadlineMs": 5000, "queueDepth": 8} with Retry-After: 1. Deliver the message normally.
• Once classification starts, it runs to the end. The deadline covers only the wait.
• The value is a whole number of milliseconds from 1 to 600000. Any other value, or the header sent more than once, returns 400.
• Without the header, nothing changes. A wait that reaches the normal queue timeout first still returns queue_timeout.

Check Several Recipients at Once

A mail server that checks a message during the SMTP session sees all of its recipients at once. Send one X-SpamFoo-Recipient header per recipient, or one header with a comma-separated list, to check the message once for all of them.

• Each value is a recipient address. Add ; user=<id> when that mailbox's user ID isn't the address, such as X-SpamFoo-Recipient: [email protected]; [email protected]. A value without a valid address returns 400.
• The models run once. The top-level answer is the verdict without any user's corrections or mailbox rules, so X-User-ID and X-Recipient-Email are ignored on these calls.
• The answer adds recipients, with one entry per recipient, and recipientsTruncated. Only the first 100 recipients are used. When there are more, recipientsTruncated is true, so don't treat the list as complete.
• Each entry's userId is the user= value, or else the address, changed to the owning user when your address map lists it as an alias.
• Each entry's rule says whether an allow or block rule applies to the sender for that recipient: action is allow or block, and scope is mailbox or domain for rules an administrator set, or user for the user's own spam rule. It's null when no rule applies.
• Send X-SpamFoo-Personalize: per-recipient to add each recipient's own verdict and stampHeaders, with that user's corrections and rules applied. Without X-SpamFoo-Recipient it has no effect. Any other value returns 400.
• When recipients get different verdicts, how to act is up to you. Per-recipient verdicts aren't recorded for the admin console. Only a call for one mailbox, with X-User-ID, is.

"recipients": [
    {
        "address": "[email protected]",
        "userId": "[email protected]",
        "rule": { "action": "block", "scope": "user" },
        "verdict": { ... },
        "stampHeaders": [ ... ]
    }
],
"recipientsTruncated": false

Reuse a Scan for Each Mailbox

A mail server that checks a message once during the SMTP session, and then again for each mailbox at delivery, can skip most of the second check:

1. Send the first request without X-User-ID, and add X-SpamFoo-Scan: keep. The answer includes a scanId.
2. For each mailbox, send the same message with X-User-ID and X-SpamFoo-Scan-Id set to that scanId.

• When SpamFoo Client still holds the scan, it runs only that user's steps: impersonation checks for their domain, their rules and corrections, and their classification corrections. The answer adds "scanReused": true. Otherwise it checks the message in full, as if the header were absent.
• X-SpamFoo-Scan is ignored on a request with X-User-ID. Any value other than keep returns 400.
• The answer can leave out scanId, such as when a rule decided the message or the license doesn't include spam detection. Classify each mailbox normally then.
• Scans are kept in memory for up to 15 minutes, and a restart drops them. SpamFoo Client can drop the oldest sooner when it holds many.
• A scan is tied to the message body, not its headers. Headers your mail server adds on the way to the mailbox, and LF line endings in place of CRLF, don't break it. A scanId sent with a different message only causes a full check.
• A reused result keeps the scores the message got in the first scan, including the phishing detection model's score.
• The first scan counts toward the admin console statistics and sender reputation. Results built on it are recorded for each mailbox but not counted again.

Share Your Authentication Results

If your mail server already checks SPF, DKIM, and DMARC (the checks that confirm a message came from the domain it claims), it can tell SpamFoo Client its results. SpamFoo Client then treats those results as trusted, and can skip its own DNS lookups when your results are clear. Without these headers, SpamFoo Client doesn't trust any Authentication-Results, ARC-Authentication-Results, Received-SPF or X-SmarterMail- header in the message, because a sender can add one. It runs its own checks instead when the request has X-Sender-IP and X-Sender-Email, and otherwise reports authentication as unknown.

• X-SpamFoo-Boundary: authserv-id=<id>, such as X-SpamFoo-Boundary: authserv-id=mx.example.com. Your mail server adds Authentication-Results headers to the top of each message, using <id> as its authserv-id (the name at the start of the header value, usually the server's host name). SpamFoo Client trusts the run of Authentication-Results headers with that id at the top of the message. It stops at the first header with another id or at the next Received header. The id is up to 255 characters from A-Z a-z 0-9 . - _ :.
• X-SpamFoo-Boundary: authserv-id=<id>; relays=<cidr>,..., such as authserv-id=mx.example.com; relays=172.22.1.0/24,fd4d:6169:6c63:6f77::/64. Use this when you can't send X-Sender-IP. List your own mail hosts (up to 16 IPv4 or IPv6 ranges or addresses). When the request has no X-Sender-IP, SpamFoo Client reads the Received headers from the top, skips each hop that came from one of your relays, and uses the IP of the first hop from outside them as the sender IP. Your mail server must add the topmost Received header. If SpamFoo Client can't read a trustworthy IP, the message is classified with no sender IP. This works on /classify-stream only.
• X-SpamFoo-Boundary: none. Trust no authentication results in the message.
• X-SpamFoo-Auth-Results. Your results for this message in the Authentication-Results format, such as spf=pass smtp.mailfrom=example.com; dkim=pass header.d=example.com; dmarc=pass header.from=example.com. It must include at least one spf, dkim, or dmarc result, and be at most 2048 characters. These results take the place of the ones in the message. You can send it with or without X-SpamFoo-Boundary.

A value SpamFoo Client can't read is treated as none, and the request is still classified. Send each header at most once. These headers change which authentication results SpamFoo Client trusts, and so senderAuthenticated and the three auth scores in the result. They don't change how the models read the message.

What SpamFoo Client Checks

SpamFoo Client stops at the first check that decides the message. bypassReason in the response tells you which one it was.

1. Allow and block rules an administrator set for the recipient's mailbox or domain.
2. Whether the message can be parsed. A message that cannot be parsed is treated as spam.
3. Phishing checks: links to known phishing sites, impersonation of protected people (when the license includes SpamFoo Anti-Phishing), and sender domains that misspell well-known domains.
4. The user's own past spam and not-spam corrections, when X-User-ID is sent.
5. SpamFoo's permanent allow and block entries for the sender's domain or IP address.
6. The global spam models. For mail that is not spam, the Email Classification model, or the user's own classification corrections.
7. The Anti-Phishing model, when the license includes SpamFoo Anti-Phishing and an administrator has not turned it off.

Allow and block rules that apply to all mail are checked after the models run. A system-wide allow rule gives way when the user's own corrections for the same sender say the message is spam. See Manage Spam Rules and Senders and Protect Against Phishing.

How the License Changes the Result

See Use Classification Only for an integration built on a classification-only license.

Response

A successful request returns 200 with a JSON object. This example is a message that is not spam:

{
    "isSpam": false,
    "classification": "transactions",
    "spamProbability": 0.031,
    "displayConfidence": 0.027,
    "spamLevel": null,
    "textSpamScore": 0.052,
    "metaSpamScore": 0.018,
    "confidenceMargin": 0.469,
    "tabsProbs": [0.08, 0.86, 0.04, 0.02],
    "entropy": 0.138,
    "disagreement": 0.034,
    "shouldEscalate": false,
    "bypassReason": null,
    "spamBypassReason": null,
    "knnThresholdShift": 0,
    "reputationBypass": false,
    "phishingReason": null,
    "phishingScore": null,
    "phishingThreatType": null,
    "phishingEncoderVersion": null,
    "senderAuthenticated": true,
    "spfScore": 1,
    "dkimScore": 1,
    "dmarcScore": 1,
    "attribution": "FromDmarc",
    "dmarcRecord": "RecordPresent",
    "attributedFromDomain": "example.com",
    "attributedEnvelopeDomain": null,
    "envelopeAttribution": "EnvelopeSpf",
    "verdict": {
        "spam": false,
        "spamLevel": null,
        "classification": "transactions",
        "confidence": 0.973,
        "personalized": false,
        "decidedBy": "model",
        "phishing": null
    },
    "stampHeaders": [
        ["X-SpamFoo-Status", "ok"],
        ["X-SpamFoo-Spam", "no"],
        ["X-SpamFoo-Classification", "transactions"],
        ["X-SpamFoo-Confidence", "0.97"],
        ["X-SpamFoo-Personalized", "no"]
    ]
}

verdict and stampHeaders are the simplest fields to act on. See Verdict. Ignore any field you don't know, because new fields can be added.

Verdict

All verdict values are lowercase, so you can compare them as plain text.

Stamped Headers

stampHeaders lists headers you can add to the copy of the message you deliver, so mail filters and Sieve scripts can act on the verdict. Add them in the order given. Remove any X-SpamFoo- headers that arrived with the message first. Otherwise a sender could write X-SpamFoo-Spam: no and fool a filter.

Spam Levels

SpamFoo Client grades each spam verdict, so every mail server sees the same grade for the same message. The grade says how strict a spam cutoff the message still counts as spam at:

• high: spam even at the strictest cutoff. Spam decided by something other than the global models, such as a rule, the user's corrections, a SpamFoo permanent block entry, or a phishing check, is also high.
• medium: spam at the normal cutoff, but not the strictest one.
• low: spam only at the loosest cutoff.

The Spam Sensitivity setting on System > Settings decides which grades count as spam at all. Conservative marks only high as spam, Recommended marks medium and high, and Aggressive marks all three. A message that is not spam has no grade.

SpamFoo Client only grades. Your integration decides what to do with each grade. A recommended starting point:

Bypass Reasons

Errors

Example

curl -X POST http://localhost:16253/classify-stream \
    -H "Content-Type: message/rfc822" \
    -H "X-SpamFoo-Proxy-Auth: $SPAMFOO_PROXY_SECRET" \
    -H "X-User-ID: [email protected]" \
    -H "X-Sender-IP: 203.0.113.50" \
    -H "X-Sender-Email: [email protected]" \
    -H "X-Recipient-Email: [email protected]" \
    -H "X-SpamFoo-Log-ID: queue-4F2A91" \
    --data-binary @message.eml

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

using var http = new HttpClient { BaseAddress = new Uri("http://localhost:16253") };

await using var eml = File.OpenRead("message.eml");
var content = new StreamContent(eml);
content.Headers.ContentType = new MediaTypeHeaderValue("message/rfc822");

using var request = new HttpRequestMessage(HttpMethod.Post, "/classify-stream") { Content = content };
request.Headers.Add("X-SpamFoo-Proxy-Auth", Environment.GetEnvironmentVariable("SPAMFOO_PROXY_SECRET"));
request.Headers.Add("X-User-ID", "[email protected]");
request.Headers.Add("X-Sender-IP", "203.0.113.50");
request.Headers.Add("X-Sender-Email", "[email protected]");
request.Headers.Add("X-Recipient-Email", "[email protected]");
request.Headers.Add("X-SpamFoo-Log-ID", "queue-4F2A91");

using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadFromJsonAsync<JsonElement>();
var isSpam = result.GetProperty("isSpam").GetBoolean();
var classification = result.GetProperty("classification").GetString();
Console.WriteLine($"isSpam={isSpam} classification={classification}");

import os

import requests

headers = {
    "Content-Type": "message/rfc822",
    "X-SpamFoo-Proxy-Auth": os.environ.get("SPAMFOO_PROXY_SECRET", ""),
    "X-User-ID": "[email protected]",
    "X-Sender-IP": "203.0.113.50",
    "X-Sender-Email": "[email protected]",
    "X-Recipient-Email": "[email protected]",
    "X-SpamFoo-Log-ID": "queue-4F2A91",
}

with open("message.eml", "rb") as eml:
    response = requests.post(
        "http://localhost:16253/classify-stream",
        data=eml,
        headers=headers,
        timeout=60,
    )

response.raise_for_status()
result = response.json()
print(f"isSpam={result['isSpam']} classification={result['classification']}")