Source: https://help.spamfoo.com/integrations
Last updated: 2026-10-27

***

# 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](https://help.spamfoo.com/integrations/local-api#authenticate).
- **A shared secret:** callers send the proxy secret with their requests. See [Authenticate Requests](https://help.spamfoo.com/api#authentication).

## 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](https://help.spamfoo.com/api/health#ready).
- To tune how many messages run at once, see [Tune Performance](https://help.spamfoo.com/guides/configure#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](https://help.spamfoo.com/integrations/smartermail) |
| **Local API** | You are connecting another mail server, a mail filter, or your own application. | [Start With the Local API](https://help.spamfoo.com/integrations/local-api) |
| **Command line** | You want to test SpamFoo Client, run scripts, or classify a folder of saved messages. | [Use the Command Line](https://help.spamfoo.com/integrations/command-line) |

If another product already handles spam and you only want Email Classifications, see [Use Classification Only](https://help.spamfoo.com/integrations/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](https://help.spamfoo.com/integrations/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](https://help.spamfoo.com/integrations/send-corrections).

The [API Reference](https://help.spamfoo.com/api) lists every endpoint, header, and response field.

## After You Connect

- Open the [admin console](https://help.spamfoo.com/guides/admin-console) at `http://localhost:16253/admin/` and confirm that messages appear as they are classified.
- Set up [log and health monitoring](https://help.spamfoo.com/guides/monitoring) so you notice if the service stops.
- Read [How Corrections Are Used](https://help.spamfoo.com/guides/corrections) to understand what happens to the feedback your integration sends.