How verdicts work

Every submission goes through the same pipeline. Each stage can end the request with a verdict; the response tells you which one did.

The four stages

1. Memory

Two lookups run before anything else.

• Near-duplicate index. A fingerprint of the message text is compared with messages already classified across every site on spamex. A match with known spam returns DUP_KNOWN_SPAM. A match with a message you marked legitimate returns DUP_KNOWN_HAM, and that one is always ham, whatever the text contains.
• Sender reputation. The visitor’s IP, email address and email domain carry decayed counters of past spam and ham. A sender with a clear recent history of spam is answered with a *_REPUTATION_BAD code. A sender with a history of legitimate messages on your site has the score scaled down and the response carries EMAIL_REPUTATION_GOOD.

Reputation is tenant-scoped by default: what one site learns about a sender only affects that site until at least two independent sites agree. Counters halve every 14 days, so an address is not marked forever.

2. Rules

Deterministic checks on the submission itself. Some are decisive on their own and end the request as spam at stage rules: a filled honeypot, a form submitted under two seconds after it loaded, a URL in the name field, three or more links. Others are soft signals that only nudge the score: a disposable email provider, a risky top-level domain, a name that does not match the address, machine-looking identifiers, learned spam phrases, and text in a script that does not match the site’s locale.

3. Model

A compact text classifier trained on form submissions scores the message together with the soft signals. Its output is calibrated against two thresholds. Below the lower threshold the verdict is ham with ML_HAM; above the upper one it is spam with ML_SPAM. Both zones are held to at least 99 percent precision, which is why the model is allowed to decide alone there.

The model reads the text as it is. Submissions in languages other than English are scored the same way; the script-mismatch rule is the only place where locale matters.

4. Second opinion

Scores between the two thresholds, roughly one submission in twenty, go to a language model together with your site_description. It is asked one question: is this a message the site would want? The answer arrives as LLM_SPAM or LLM_HAM with the model’s confidence as the score. The call has a three-second timeout. If it fails or times out, the response carries LLM_UNAVAILABLE and ML_GRAY_FALLBACK, and the classifier’s nearest label is used.

Reading the response

field	meaning
label	The decision. Always spam or ham; there is no “maybe”, because your code needs a branch to take.
score	Probability of spam in [0, 1] after rules and model are blended. For memory and reputation verdicts it is pinned near 0 or 1. For a language-model verdict it is the model’s stated confidence.
stage	rules when memory, reputation or a hard rule decided, ml for the classifier, llm for the second opinion.
reasons	Every code that contributed, in evaluation order. The first code is usually the one worth showing a user.

Reason codes are stable strings. New ones may be added; none are renamed or reused. The full list, with suggested handling and user-facing wording, is in the reason code reference.

What your feedback changes

A POST /v1/feedback call with the verdict id and the correct label does three things.

1. Your site’s memory. A message you mark ham is remembered for your site and answered DUP_KNOWN_HAM when it recurs. A message you mark spam is remembered as spam for your site.
2. Sender reputation. The sender’s IP, email and domain receive a strong vote in the direction you gave.
3. The shared index. A message you mark ham is removed from the shared spam index, so a false positive is not repeated elsewhere.

No single site can blacklist a sender for everyone. Cross-site effects need two independent sites to agree.

What is stored

By default spamex keeps a hash and a fingerprint of the text, hashed sender identifiers, the verdict and its reasons. The message itself is discarded once the verdict is returned. Each key can opt into retaining raw text for review. The details, and the deletion endpoint, are in Data and privacy.