Feedback & Training

SpamFoo improves its classification accuracy over time by learning from user corrections. When a user marks an email as spam (or marks a spam email as not spam), or moves an email to a different classification, SpamFoo uses that correction to adjust its behavior for future messages.

How Feedback Works

When a correction is submitted, SpamFoo processes it through three layers:

  1. Pattern memory: SpamFoo creates a mathematical representation (embedding) of the corrected email and stores it in a per-user memory. When future emails arrive, SpamFoo compares them against this memory using k-nearest-neighbor matching. If a new email is similar enough to a corrected one, the correction influences the classification.
  2. Global model improvement: Aggregated corrections are sent to SpamFoo's Global API. These are used to retrain the base ML models that ship to all SpamFoo installations. See Local-First Processing for details on how this data is protected.

Layer 1 is per-user and takes effect immediately on the local installation. Layer 2 is global and takes effect when updated models are published.

Types of Corrections

Spam Corrections

When a user marks an email as spam, or moves a spam email out of the junk folder, SpamFoo records whether the message should be classified as spam or not spam. This affects both the per-user personalization and the global model training data.

Classification Corrections

When a user moves an email from one classification to another (for example, dragging a newsletter from Primary to Updates), SpamFoo records the correct class for that message. Users can also create explicit sender rules in the SpamFoo Dashboard so that all future messages from a sender go to a specific tab.

Submitting Feedback

How feedback reaches SpamFoo depends on your integration:

  • SmarterMail: Feedback is automatic. When users mark messages as spam/not spam or move them between tabs, SmarterMail sends the correction to SpamFoo in the background. No setup required.
  • Other integrations: Your mail server or application needs to call SpamFoo's feedback API when users take corrective actions. See the Local API feedback endpoints for request formats.

Personalization Data

SpamFoo stores per-user personalization data locally in the {data-dir}/personalization/users/ directory. This includes:

  • Sender rules (auto-created from corrections, or manually created by users)
  • Pattern memory (email embeddings from corrections, stored in a compact binary format)

Personalization data stays on your server and is not sent to SpamFoo's servers. To keep it across reinstallations, include the personalization/ directory in your backups. If a user requests data deletion, their personalization data can be cleared through the API or admin console.

How Effective is Feedback?

The impact of corrections depends on the type and volume:

  • Sender rules are deterministic. Once created, they always override the ML model for that sender. This is the most immediate form of personalization.
  • Pattern memory is probabilistic. It works best when the user submits corrections for a variety of messages. A single correction has limited impact, but multiple corrections for similar message types produce noticeable improvement.
  • Global model updates improve the baseline for all users. These updates are released periodically and benefit everyone, even users who do not submit corrections themselves.

What Administrators Should Know

  • Feedback processing is lightweight and does not affect mail delivery performance. Corrections are queued and processed in the background.
  • If SpamFoo is temporarily unavailable when a correction is submitted, the correction is attempted later. If it is still unavailable, the correction is still applied to your installation, just not added to the global model. Mail delivery is not affected.
  • You can view correction statistics and personalization rule counts in the admin console.
  • Per-user personalization data can be cleared if needed. See the Local API for the data deletion endpoints.