Skip to main content
formsieve Docs Support
All docs pages

How it works

This page follows one form submission from the visitor's click to the entry in your admin, and lists exactly what leaves your site.

The path of one submission

  1. The visitor submits the form. Formsieve runs inside Gravity Forms' own spam check, the gform_entry_is_spam filter, at priority 50: after Gravity Forms' honeypot (priority 1) and before Gravity Forms' built-in Akismet check (priority 90). If the honeypot, or another tool that hooks in before Formsieve, has already flagged the submission as spam, Formsieve leaves it alone and makes no API call. Akismet runs after Formsieve and only sees submissions that Formsieve allowed.
  2. Skip rules. Nothing is checked, not even by the free local pre-filters below, when Formsieve is off for the form, when the fsv_gf_should_check filter says so, or when the plugin is not set up yet (no route, no key or no consent; Test mode needs none of them). Those submissions are delivered and logged as "not checked".
  3. The visitor submits the form. Formsieve runs inside Contact Form 7's own spam check, the wpcf7_spam filter, at priority 20, after Contact Form 7's reCAPTCHA and Turnstile (priority 9) and its Akismet and Disallowed Comment Keys checks (priority 10). If one of them has already flagged the submission as spam, Formsieve leaves it alone and makes no API call.
  4. Skip rules. Until an API key is saved or Test mode is on, Formsieve for CF7 is inactive: it adds no hidden fields, runs no checks and writes no log rows. It also skips a form with Formsieve switched off (again without a log row). Submissions the fsv_cf7_should_check filter excludes, and, once a key is saved, submissions while the route or consent is missing, are not checked at all (not even by the free local pre-filters below), delivered and logged as "not checked".
  5. Free local pre-filters, cheapest first, stopping at the first decision: allowlist → honeypot → time-to-submit → per-IP rate limit → blocklists → trivial content → replay cache → heuristics. See Pre-filters. A submission stopped here costs nothing.
  6. Cost guards. If the hourly or monthly cap is reached (caps count every request sent, retries included), the circuit breaker is open or the provider reported no credit, Formsieve does not call the API and applies your fail mode (deliver by default). See Cost and caps.
  7. One HTTPS call to Jev through the route you chose (TypeSafe direct, Vercel AI Gateway, OpenRouter or a custom base URL). The request asks one main question ("is this spam?", with structured criteria) and five short supporting questions (category, attempts to manipulate the classifier, relevance to your site, deceptive urgency, coherent text). Timeout: 3 seconds, with at most one quick retry.
  8. Decision. The answers become one probability p between 0 and 1, which your thresholds turn into allow, review or block. See Verdict bands and actions.
  9. Outcome and explanation. A blocked entry is marked as spam (or discarded, or refused with a validation message, as you choose per form), and the entry gets a note, a Formsieve panel and entry meta. Review-band notifications to the site owner get a "[Possible spam NN%]" subject prefix.
  10. Outcome and explanation. A blocked submission gets Contact Form 7's native spam status and a spam-log line, no mail is sent, and Flamingo (if installed) stores the message with the details. For the review band, the site owner's mail gets a "[Possible spam NN%]" subject prefix.
  11. Log. A row with numbers and identifiers only (never the message) is written to Formsieve's decision log, which feeds the dashboard.
  12. Your corrections teach it. Marking an entry "Spam" or "Not Spam" (Gravity Forms) or moving a Flamingo message to Spam or back to the Inbox labels the log row and updates the learned sender lists. See Feedback loop.

The probability is never sent back to the visitor's browser.

What is sent, and what is not

Only after an administrator has chosen a route, entered a key and given consent on the consent screen.

Sent to the route you chose:

  • your site name, the site description you wrote and the site languages;
  • the form's name and the per-form context text, if you wrote one;
  • the label, type and value of each ordinary field in the submission (for example name, subject, message, company, choices), with phone numbers redacted by default, HTML removed and each value capped (2,000 characters, 4,000 for the message, whose beginning and end are kept, about 12 KB in total; a value longer than 20,000 characters is already cut on your server before any check);
  • the domain of the sender's e-mail address (for example example.com), never the full address (you can switch even the domain off);
  • with every request, the Formsieve version and your WordPress and PHP versions (in the User-Agent header);
  • numeric signals computed on your server: number of links and their domains (only from fields that may be sent), whether a phone number is present, seconds from page load to submit, submissions from the same IP in the last hour (a count, not the IP, and only while the rate limit is on), the writing systems used (script mix), message length (as submitted), and whether the sender was previously marked "spam" or "not spam" by you. These are the only signals sent; the other local hints (repeated values, crypto addresses, prompt-injection patterns and so on) never leave your site.

Never sent: the visitor's IP address, browser user agent and cookies, the full e-mail address, passwords, payment and card fields, file uploads, hidden fields, consent and CAPTCHA fields, and fields that look like health, national ID, passport, driving-licence, bank or card data (detected by label and type and excluded automatically, with a warning on forms that look medical or legal). You can exclude more fields per form.

Stored on your site by Formsieve: settings, the key (obfuscated at rest, autoload off), a consent record, and the decision log (time, form, verdict, score, category, model, route, request ID, latency, tokens, cost, HMAC hashes of the IP and e-mail address, your label). The log never contains what the visitor typed. It is deleted after 90 days by default (Privacy kit). The submission itself is stored by Gravity Forms as an entry or by Flamingo, when it is installed (Contact Form 7 stores nothing itself).

Where it goes: see Data processing by route. Every route ends at TypeSafe AI, Inc. in the United States; a gateway route adds the gateway as a second recipient.

Why a probability, and why three bands

Jev answers with calibrated probabilities rather than a yes/no guess, so a score of 0.97 and a score of 0.55 can be treated differently. Formsieve blocks only confident spam, delivers the uncertain middle with a tag so a borderline lead still reaches you, and lets everything else through. Calibration explains which model version the thresholds were set for and how Formsieve notices when a route answers with a different one.