SpamFactory analyzes submitted text and returns a structured spam assessment. It combines independent scoring evidence and reports both the combined result and the state of each available engine. SpamFactory analyzes content only; it does not hide, delete, quarantine, or otherwise moderate content.
Signed-in Tools users can open the standalone testbench at /me/spam. The convenience entry point /spam redirects to that canonical user workspace.
The testbench accepts content plus optional source/language labels and shows the final probability, classification, confidence and state together with each engine's state and safe evidence. SpamAssassin output includes its raw score, required score, normalized probability and matched rule/symbol names. AI output shows bounded provider/model/status/error metadata when available. Internal backend addresses, raw transport attempts, provider request ids, raw provider bodies and credentials are not rendered.
The submitted body is used for the current analysis result but is not persisted by the testbench. SpamFactory's structured audit trail stores safe metadata rather than the full analyzed content by default. The workspace is protected by the normal signed-in web session, CSRF protection and a per-user request rate limit. It performs assessment only and never applies moderation actions.
SpamFactory is discoverable from the signed-in dashboard, /services, and the My Profile services view. There is no separate SpamFactory admin GUI for owner profiles; reusable profiles are managed under /me/spam/profiles and remain strictly owner-scoped.
Signed-in users manage reusable scoring profiles at /me/spam/profiles. A profile can configure SpamAssassin/AI weights, clean/review/spam probability thresholds, deterministic phishing/fraud/malware floors, whether AI is enabled, the AI model, bounded site/content context, classification guidance and optional application tags. Application tags are metadata only. Creating or editing a profile does not activate it for Guestbook, WordPress or any other application.
The /me/spam testbench contains an explicit profile selector. API clients with spam.analyze may add a top-level profile_id to POST /api/spam/analyze. The selected profile must belong to the same Tools user as the web session or API token; a foreign or unavailable profile is rejected. When a profile is selected successfully, the API response includes its id and name. Profile context is not accepted from arbitrary API request context and raw profile context/instructions are not written to SpamFactory audit or operational metadata.
AI profile guidance is treated as bounded owner configuration for classification only. It cannot enable web search/tools, change the provider response schema, override SpamFactory safety rules or make Tools use a global OpenAI credential.
POST /api/spam/analyze requires a user-bound Tools API key with the spam.analyze scope.
Send the credential in the request header:
Authorization: Bearer YOUR_API_TOKEN
X-Api-Key is accepted for compatibility, but new clients should use the bearer header. Tokens in URLs or query strings are not supported by this endpoint.
The spam.analyze scope is self-delegatable to a personal API key. The token remains bound to its Tools user. If AI scoring is enabled, API analysis uses only that user's active non-global provider_openai credential for AI evidence. Tools global OpenAI keys and the OPENAI_API_KEY environment fallback are never used for this endpoint. If the user has no usable OpenAI credential, SpamAssassin can still produce a degraded assessment. Guestbook or unrelated API scopes do not implicitly grant SpamFactory access.
POST /api/spam/analyze
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN
X-Request-ID: example-request-123
{
"content": "Example text to analyze",
"context": {
"source": "guestbook",
"language": "en"
}
}
content is required and may contain up to 100,000 characters. context is optional and deliberately restricted to the safe source and language fields. Arbitrary instructions, credentials, private metadata, or application-specific objects are rejected as context.
X-Request-ID is optional. Tools normalizes a supplied identifier to a bounded safe correlation value and returns it. If the header is omitted or becomes empty after normalization, Tools creates a request id.
A valid API request returns HTTP 200 even when one or more scoring engines are degraded or unavailable. Evidence availability is represented by assessment.state rather than by changing a successful transport response into an HTTP error.
{
"ok": true,
"request_id": "example-request-123",
"assessment": {
"spam_probability": 0.82,
"score": 82,
"classification": "spam",
"confidence": 0.91,
"state": "complete",
"engines": {},
"signals": ["commercial_blast"],
"reason": "Strong spam indicators were detected."
}
}
spam_probability is a value from 0.0 through 1.0 and score is the corresponding rounded 0-100 value. If no configured engine can provide usable evidence, spam_probability and score are null, classification is unknown, and the assessment state is unavailable rather than a fabricated zero score.
Possible assessment and engine states are complete, degraded, disabled, unavailable, and failed. Per-engine evidence is deliberately filtered before it is returned publicly. For example, SpamAssassin may expose score/threshold, backend health and attempt count, but not backend addresses or internal attempt details. AI evidence may expose bounded provider/model/status/error identifiers but not credentials or raw provider bodies.
spam.analyze, or a token that is not bound to a Tools user.Scoring and analysis failures are reported through Tools operational diagnostics with safe service/action/result/error/correlation metadata. Meaningful completed analyses also receive a separate structured audit record. Submitted content, API credentials and raw provider/backend data are not stored in those diagnostic or audit metadata fields by default.
Treat the API token as a server-side secret. Do not expose it in browser JavaScript, URLs, query strings, logs, or public source code. SpamFactory's AI scorer treats submitted content as untrusted data and does not enable web search or provider tools for spam classification.
The API route is intentionally unversioned. Clients should use /api/spam/analyze; no /v1, /v2, or similar SpamFactory URL namespace exists.