Custom Integration: Watched Folder

In development: Watched folder integration is being developed and is not available in the current release. This page describes how it is expected to work, and the details may change. Until it ships, use the Local API instead.

SpamFoo will be able to monitor a directory for incoming .eml files and classify them automatically. This is the simplest integration method for mail servers that can write messages to a directory but cannot make HTTP calls or run external commands during delivery.

How It Works

  1. You configure SpamFoo to watch a specific directory
  2. Your mail server (or another process) drops .eml files into that directory
  3. SpamFoo detects new files, classifies each message, and writes the result back
  4. Your mail server reads the classification result and routes the message accordingly

This approach decouples the mail server from SpamFoo entirely. The mail server does not need to know about SpamFoo's API or wait for a response. The tradeoff is that classification is asynchronous, so there is a small delay between the file being written and the result being available.

Setup

Configure the watched directory through the admin dashboard at http://localhost:16253/admin or through environment variables. SpamFoo needs read access to the input directory and write access to the output location.

Directory Structure

A typical setup uses separate directories for incoming files and results: 

/var/spool/spamfoo/
    incoming/       # Mail server drops .eml files here
    results/        # SpamFoo writes classification results here

When SpamFoo classifies a file, it writes a corresponding result file (e.g., message.eml.json) containing the classification output in the same JSON format as the Local API response.

When to Use This

  • Your mail server supports a delivery queue or spool directory but not HTTP calls or external commands
  • You want to decouple classification from mail delivery (async processing is acceptable)
  • You are integrating with a legacy system that can only interact through the filesystem

If your mail server can make HTTP calls, the Local API is preferred because it provides synchronous results and avoids filesystem overhead.

File Permissions

Make sure the SpamFoo process has:

  • Read access to the incoming directory
  • Write access to the results directory
  • Matching user/group with the mail server process if both need access to the same files

On Linux, a shared group is the simplest approach: 

sudo groupadd mailfilter
sudo usermod -aG mailfilter spamfoo
sudo usermod -aG mailfilter postfix
sudo chgrp mailfilter /var/spool/spamfoo/incoming /var/spool/spamfoo/results
sudo chmod 770 /var/spool/spamfoo/incoming /var/spool/spamfoo/results

Next Steps

  • See the Local API guide if your server supports HTTP calls
  • Review Configuration for directory paths and performance settings
  • Set up feedback to improve classification over time