# spamex

> spamex is a spam-classification API for form submissions. One HTTPS request from your backend returns a label (spam or ham), a score, the stage that decided and stable reason codes. Base URL: https://api.spamex.dev. Authentication: `Authorization: Bearer <key>`.

Facts that matter when writing an integration:

- Call the API from the server, never from a browser; the key must not be exposed.
- `POST /v1/classify` needs only `message`; send `name`, `email`, `subject`, the visitor's `ip`, and `honeypot`, `form_load_ts`, `submit_ts` when you have them.
- Fail open: on any non-200 response or timeout, deliver the message and log the failure. Use a 5-second timeout.
- Keep the returned `id`; `POST /v1/feedback` with `{id, label}` corrects a verdict.
- `mode: "fast"` never waits on the language model; re-check ids carrying `LLM_SKIPPED` from a queue.
- The complete documentation as one markdown file: https://spamex.dev/llms-full.txt

## Get started

- [Documentation](https://spamex.dev/docs): spamex gives every form submission a verdict and a reason over one HTTP call. Start here.
- [Quickstart](https://spamex.dev/docs/quickstart): Get a key, send one submission, act on the verdict. Five minutes in any language.
- [How verdicts work](https://spamex.dev/docs/how-it-works): The stages a submission passes through, what the score means, and how your feedback changes future verdicts.
- [Handling verdicts](https://spamex.dev/docs/handling-verdicts): Turn a label and a reason into a policy: what to drop, what to review, what to show the visitor, and how to fail safely.

## Guides

- [For form platforms](https://spamex.dev/docs/platforms): Add spam filtering to your own form service. One platform key, a managed key per customer form, verdicts and reasons in your own UI.
- [Integrations](https://spamex.dev/docs/integrations): A WordPress plugin for Contact Form 7 and WPForms, and form handlers for Netlify and Vercel. Install, paste a key, done.
- [Node.js](https://spamex.dev/docs/integrate-node): An Express handler that classifies, then delivers or quarantines. The shape is the same in Next.js, Hono, Fastify or SvelteKit.
- [PHP and WordPress](https://spamex.dev/docs/integrate-php): A plain PHP handler, and WordPress filters for Contact Form 7 and WPForms.
- [Python](https://spamex.dev/docs/integrate-python): A shared client with httpx, then FastAPI, Django and Flask handlers.
- [Fast mode and queues](https://spamex.dev/docs/fast-mode): Keep the visitor's request under a few milliseconds and still get the second opinion before anything is delivered.
- [Data and privacy](https://spamex.dev/docs/data-and-privacy): What spamex stores for each submission, what it never stores, how retention is controlled, and how deletion requests work.

## API reference

- [Authentication](https://spamex.dev/docs/authentication): Bearer keys, the two kinds of key, what each key carries, and rotation.
- [Errors](https://spamex.dev/docs/errors): The error format, every status code the API returns, and how a form handler should react to each.
- [Classify](https://spamex.dev/docs/api-classify): Get a verdict for one form submission. The endpoint that does the work.
- [Feedback](https://spamex.dev/docs/api-feedback): Correct a verdict, one at a time or in bulk. Feedback trains your site's memory and the sender's reputation.
- [Usage](https://spamex.dev/docs/api-usage): Monthly classifications by stage, quota and remaining checks for a key.
- [Submissions](https://spamex.dev/docs/api-submissions): Delete what spamex holds for one submission, for data-deletion requests.
- [Health](https://spamex.dev/docs/api-health): An unauthenticated probe for your own uptime checks.
- [For coding agents](https://spamex.dev/docs/for-agents): The whole documentation as plain markdown, so Claude Code, Cursor, Copilot and friends can integrate spamex without scraping.

## Platform API

- [Site keys](https://spamex.dev/docs/platform-keys): Create, list, update, rotate and revoke the keys a platform issues for its customers' forms.
- [Platform usage](https://spamex.dev/docs/platform-usage): Monthly usage for every site key under a platform key, for billing and dashboards.

## Reference

- [Reason codes](https://spamex.dev/docs/reason-codes): Every code the API can return, what it means, what to do about it, and wording you can show to people.
- [Limits and quotas](https://spamex.dev/docs/limits): Request limits, monthly allowances by plan, payload sizes and timeouts.
- [Changelog](https://spamex.dev/docs/changelog): What changed in the API, newest first. Fields and codes are only ever added; removals get a new major version.
- [Enterprise self-hosting](https://spamex.dev/docs/self-hosting): Run spamex inside your own infrastructure, with the same model, updates and support as the hosted service.

## Optional

- [Pricing](https://spamex.dev/pricing): plans and quotas.
- [Privacy policy](https://spamex.dev/privacy): operator, sub-processors and data handling.