API Reference

SpamFoo exposes a local HTTP API on port 16253 for classification, feedback, personalization, and system management. This page provides an overview of the API. See the individual endpoint pages for request and response details.

Basics

Property Value
Base URL http://localhost:16253
Authentication None (localhost only by default)
Content type (JSON endpoints) application/json
Content type (stream endpoints) message/rfc822 (raw email body)
Response format JSON

Endpoint Patterns

Most endpoints come in two variants:

  • JSON (file path): Send a JSON body with the path to an .eml file on disk. Use this when SpamFoo has filesystem access to the email.
  • Stream (binary): Send the raw email content as the request body with metadata in HTTP headers. Use this when SpamFoo does not have access to the file, or to avoid writing to disk.

Stream endpoints are named with a -stream suffix (e.g., /classify vs /classify-stream).

Coming soon: The JSON (file path) variants are not available yet. Use the -stream variants to send the raw message content for now.

Endpoints

Classification

See Scanning API for full request and response details.

Method Endpoint Description
POST /classify Classify an email by file path (spam + tabs). Coming soon; use /classify-stream.
POST /classify-stream Classify an email by streaming raw content
POST /classify/diagnostic Full diagnostic classification by file path. Coming soon; use /classify/diagnostic-stream.
POST /classify/diagnostic-stream Full diagnostic classification by stream
POST /tabs/classify Tabs-only classification by file path (skip spam detection). Coming soon; use /tabs/classify-stream.
POST /tabs/classify-stream Tabs-only classification by stream
POST /classify/embed-text Generate a text embedding (384-dimensional vector)

Feedback

See Corrections API for full request and response details.

Method Endpoint Description
POST /feedback Submit a spam/ham correction by file path. Coming soon; use /feedback-stream.
POST /feedback-stream Submit a spam/ham correction by stream
POST /tabs/feedback Submit a tab correction by file path. Coming soon; use /tabs/feedback-stream.
POST /tabs/feedback-stream Submit a tab correction by stream

Personalization

Method Endpoint Description
POST /personalization/rules/create Create a spam/ham rule for a user. Coming soon; use /personalization/rules/create-stream.
POST /personalization/rules/create-stream Create a spam/ham rule by stream
GET /personalization/rules?userId={id} List a user's personalization rules
DELETE /personalization/rules/remove Remove a specific rule
DELETE /personalization/data Delete all personalization data for a user
POST /personalization/tabs/rules/create Create a tab classification rule. Coming soon; use /personalization/tabs/rules/create-stream.
POST /personalization/tabs/rules/create-stream Create a tab rule by stream
GET /personalization/tabs/rules?userId={id} List a user's tab classification rules
DELETE /personalization/tabs/rules/remove Remove a tab rule
DELETE /personalization/tabs/data Delete all tab personalization for a user
GET /personalization/knn/stats?userId={id} KNN memory statistics for a user
GET /personalization/tabs/knn/stats?userId={id} Tabs KNN statistics for a user

System

Method Endpoint Description
GET /health Service health, queue state, and model reload status

Error Handling

Status Meaning
200 Success
400 Bad request (missing required fields, file not found, or unparseable email)
503 Queue timeout. SpamFoo is overloaded. Deliver the email without classification.

Error responses include a JSON body with an error field describing the problem.

Admin API

The admin console at /admin is backed by a set of API endpoints under /admin/api/. These provide access to statistics, overrides, settings, logs, and system management. They are intended for the admin console UI but can be called directly if you need programmatic access to monitoring data.