How Integration Works

This page explains how a mail server or your own application hands mail to SpamFoo Client and acts on the result, and how to pick an integration method.

Understand the Local Service

SpamFoo Client (spamfoo-client) runs as an HTTP service on the same machine as your mail server, or next to it in a Docker container. Every integration talks to it over HTTP on port 16253.

  • Local decisions: SpamFoo Client classifies each message with models that run on your server. It may ask SpamFoo's online services about a sender's domain reputation to improve the result, but it doesn't require it. Classification keeps working when the internet connection is down.
  • Raw message in, JSON out: you send the raw message (the full .eml content, headers and body exactly as received) and get a JSON result back.
  • Localhost by default: the service listens on localhost only. Callers on other machines need extra setup, described in Start With the Local API.
  • A shared secret: callers send the proxy secret with their requests. See Authenticate Requests.

Follow a Message Through

  1. A message arrives at your mail server over SMTP.
  2. Your mail server posts the raw message to POST /classify-stream, along with optional headers that describe the delivery, such as the connecting IP address and the recipient.
  3. SpamFoo Client checks allow and block rules, the recipient's personalization, and its local models.
  4. SpamFoo Client returns a JSON result with a spam verdict (isSpam) and an Email Classification (classification: Primary, Transactions, Updates, or Promotions).
  5. Your mail server delivers the message to the inbox, files it under a classification, or moves it to the junk folder.
  6. When the recipient later corrects a result (for example, marks a message as not spam), your mail server sends the correction back so SpamFoo Client learns that user's preferences.

Plan for a Busy or Stopped Service

SpamFoo Client classifies a limited number of messages at a time and queues the rest. If a request waits too long, or too many requests are already in progress, it returns 503 Service Unavailable.

  • Treat a 503, a timeout, or a refused connection as "no verdict" and deliver the message without classification.
  • To check whether SpamFoo Client is ready before you send mail, call GET /health/ready. See Check Health.
  • To tune how many messages run at once, see Tune Performance.

Choose an Integration Method

All methods use the same local API. The difference is who writes the calls.

Method Use It When Where to Start
SmarterMail You run SmarterMail. SpamFoo is built in, including classification, user corrections, and the dashboard. SmarterMail Overview
Local API You are connecting another mail server, a mail filter, or your own application. Start With the Local API
Command line You want to test SpamFoo Client, run scripts, or classify a folder of saved messages. Use the Command Line

If another product already handles spam and you only want Email Classifications, see Use Classification Only.

Build Your Own Integration

A complete custom integration does three things:

  • Classify each incoming message with POST /classify-stream and act on the result. See Start With the Local API.
  • Identify the recipient with the X-User-ID header, so SpamFoo Client can personalize results for each mailbox.
  • Send corrections when a user marks spam, rescues a message from junk, or moves a message to another classification. See Send Corrections Back.

The API Reference lists every endpoint, header, and response field.

After You Connect