Guides/ For form platforms
Guides

For form 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.

If you run a form backend or a form builder, your customers’ spam is your support queue. spamex is built to sit inside a service like that. You hold one platform key, create a key per customer form with one call, ask for a verdict before you deliver each submission, and show the reason in your own interface.

1. Get a platform key

Choose the Platform or Scale plan on the dashboard; your key gains platform mode automatically. On another plan, ask us to enable it for an evaluation.

2. Create a key per customer form

When a customer creates a form, create a site key for it. Each site key is fully isolated: its own settings, quota, usage, and its own memory of what that customer marked legitimate. A message one customer marks as spam never changes another customer’s verdicts.

curl
curl -X POST https://api.spamex.dev/v1/partner/keys \
  -H "Authorization: Bearer $PLATFORM_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "form_8f2a (acme-plumbing.com)",
    "site_description": "Family-owned plumbing company in Columbus, Ohio.",
    "honeypot_field": "website",
    "locale": "en"
  }'
Node
const r = await fetch("https://api.spamex.dev/v1/partner/keys", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SPAMEX_PLATFORM_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: `form_${form.id} (${form.domain})`,
    site_description: form.description,
    honeypot_field: "website",
    locale: form.locale ?? "en",
  }),
});
const site = await r.json();
await forms.update(form.id, { spamexKeyId: site.id, spamexKey: encrypt(site.key) }); // shown once
{
  "id": 42,
  "name": "form_8f2a (acme-plumbing.com)",
  "key": "sk_Ljq2ji7x…",
  "key_prefix": "sk_Ljq2ji7x",
  "quota": 250000,
  "rate_limit": 60,
  "locale": "en",
  "honeypot_field": "website",
  "site_description": "Family-owned plumbing company in Columbus, Ohio.",
  "retain_raw_text": false,
  "revoked": false,
  "created_at": "2026-09-05T09:12:44"
}

Store the returned key encrypted against the form. It is shown once. Rotate, update and revoke site keys through the same API when forms change or customers leave; the Platform API reference lists every call.

3. Classify before you deliver

In your delivery pipeline, right before the email or webhook goes out, call /v1/classify with the site’s key. Send the submission fields, the visitor’s IP, and the honeypot and timing fields if your embed collects them. Set a five-second timeout and deliver on failure.

If the call sits on a path that answers the visitor’s browser, use fast mode. It always returns in a few milliseconds and tags the few gray-zone cases with LLM_SKIPPED; re-run only those ids in full mode from your delivery queue before connectors fan out.

Store the verdict id, label and reasons on the submission record.

4. Show your customer the verdict

The response is yours to display. Two patterns work well.

  • A Spam tab. Deliver ham. Put spam in a Spam tab of the customer’s submissions with the reason underneath: “a hidden field was filled in”, “the same message was sent to other sites this week”, “looks like a cold pitch”. Customers trust a filter they can see.
  • A Not spam button. Wire it to /v1/feedback with the site’s key. The message is delivered, the sender gets a good mark for that form, and the customer fixed their own problem without emailing you. Batch both directions with /v1/feedback/batch.

Suggested wording for every code is in the reason code reference.

5. Bill and monitor

GET /v1/partner/usage returns per-form and total usage for a month, split by stage. Use it for your own billing, dashboards and alerts. Per-form quotas default to your platform quota; set a smaller one per form if you sell tiers.

What you can promise your customers

  • No CAPTCHA and nothing visible on the form.
  • A reason for every filtered message, and a one-click way to overrule it.
  • Submissions are stored as fingerprints, not text, unless the customer opts in; sender details are hashed. The same sentence can go in your privacy policy. Details: Data and privacy.
  • If spamex is unreachable, submissions are delivered as normal.

Volume and terms

Platform is $99 a month for 500,000 checks, Scale is $299 for 2,000,000, both with a data-processing agreement. Volumes in between, or above, come with a private deployment in your region on the Dedicated plan; see the slider on the pricing page. See pricing. Above that, or if your procurement needs a conversation first, request a demo.

↑↓ navigate↵ openDocs and blog