Forms
Spam Protection
CAPTCHA, honeypot fields, content checks, an AI second opinion and trusted senders to keep spam out.
On this page
- CAPTCHA
- Setup
- How CAPTCHA tokens reach StaticForm
- Use the JavaScript helper if you’d rather not handle this yourself
- reCAPTCHA Enterprise
- Minimum score
- Honeypot
- Setup
- Language Detection
- Setup
- Allowed Domains
- Setup
- How it works
- Request Header Analysis
- IP-Based Analysis
- Content Analysis
- AI Second Opinion
- Turning it on or off
- What is sent
- Trusted Senders
- What you can add
- Protect a domain with a secret code
- How it works
- Through the API
- Spam Management
StaticForm includes multiple layers of spam protection that work together to block unwanted submissions: CAPTCHA, honeypot fields and allowed domains you configure, automatic request, IP, email and content checks, and an optional AI second opinion for the messages the rules are unsure about. Senders you trust can skip the spam filter through trusted senders.
For a practical comparison of layers, read reCAPTCHA alternatives for contact forms. New to the terms? The glossary explains CAPTCHA, the honeypot field and bot detection.
CAPTCHA
StaticForm supports the following CAPTCHA providers:
| Provider | Description |
|---|---|
| reCAPTCHA v3 | Google’s invisible CAPTCHA, no user interaction needed |
| reCAPTCHA v2 | Google’s classic “I’m not a robot” checkbox |
| reCAPTCHA Enterprise | Google Cloud’s reCAPTCHA Enterprise, with score-based (invisible) or checkbox keys |
| hCaptcha | Privacy-focused alternative to reCAPTCHA |
| Turnstile | Cloudflare’s CAPTCHA, fast and privacy-friendly |
Setup
- Get a site key and secret key from your CAPTCHA provider
- In your form settings, select the CAPTCHA type and enter the secret key (both reCAPTCHA v2 and v3 use the reCAPTCHA option, where you pick the key type; reCAPTCHA Enterprise has its own option and needs more details)
- Add the CAPTCHA script and widget to your frontend
- On submit, send the resulting token to StaticForm under the field name the provider expects (see below)
How CAPTCHA tokens reach StaticForm
When a CAPTCHA is enabled on a form, StaticForm expects every submission to include a token field in the POST body. The field name depends on the provider:
| Provider | Form-data field |
|---|---|
| reCAPTCHA v2 / v3 / Enterprise | g-recaptcha-response |
| Cloudflare Turnstile | cf-turnstile-response |
| hCaptcha | h-captcha-response |
If the field is missing or the token fails verification, the submission is rejected with a CAPTCHA error.
How the token gets there depends on which provider you use:
-
reCAPTCHA v2, Turnstile, and hCaptcha all render a widget into your page (a checkbox or invisible challenge). Once the user solves it, the provider’s script automatically injects a hidden
<input>with the right name and value into the surrounding<form>. As long as the widget lives inside the form, a regular HTML submit or anew FormData(form)call will pick the token up automatically. You don’t have to write any JavaScript. -
reCAPTCHA v3 is invisible and has no widget, so there is no hidden input. You have to call
grecaptcha.execute(siteKey, { action })yourself, get back a token, and append it to your form data asg-recaptcha-responsebefore submitting. -
reCAPTCHA Enterprise depends on the type of key you created in Google Cloud. A checkbox key renders a widget that injects the hidden input, like reCAPTCHA v2. A score-based key is invisible, like reCAPTCHA v3: call
grecaptcha.enterprise.execute(siteKey, { action })yourself and send the token asg-recaptcha-response.
In short: for the three widget-based providers, dropping the right <div> inside your form is enough. For reCAPTCHA v3, you have to wire up the token injection in JavaScript.
Use the JavaScript helper if you’d rather not handle this yourself
If you don’t want to manage scripts, widgets, and token plumbing by hand, the StaticForm JavaScript helper does it for you. It supports all five providers, auto-loads the provider’s <script> tag for you, programmatically generates a fresh reCAPTCHA v3 token on every submit, picks up the token from the rendered widget for v2/Turnstile/hCaptcha, and resets the widget after each submission so users can submit again:
// reCAPTCHA v3 (invisible, generates tokens programmatically)
StaticForm.attach(form, {
endpoint: 'https://api.staticform.app/api/v1/forms/YOUR_FORM_ID',
captcha: { type: 'recaptcha-v3', siteKey: 'YOUR_SITE_KEY' },
});
// reCAPTCHA Enterprise with a score-based key (invisible)
StaticForm.attach(form, {
endpoint: 'https://api.staticform.app/api/v1/forms/YOUR_FORM_ID',
captcha: { type: 'recaptcha-enterprise', siteKey: 'YOUR_SITE_KEY' },
});
// reCAPTCHA v2 / Turnstile / hCaptcha
// (render the provider's widget inside your form, then:)
StaticForm.attach(form, {
endpoint: 'https://api.staticform.app/api/v1/forms/YOUR_FORM_ID',
captcha: { type: 'turnstile' }, // or 'recaptcha-v2' or 'hcaptcha'
});
See the JavaScript helper docs for the full setup (script tags, widget markup, and config) of each provider.
reCAPTCHA Enterprise
reCAPTCHA Enterprise lives in Google Cloud, not in the classic reCAPTCHA admin console, and it has no secret key. Instead StaticForm asks Google to assess each token, using your own Google Cloud project. Because you can create several keys, the credentials are stored per form. In the CAPTCHA settings of the form, pick reCAPTCHA Enterprise and enter:
| Setting | Where to find it |
|---|---|
| reCAPTCHA key ID | The ID of the key under Keys in the reCAPTCHA console. It is the same value you use as the site key on your page (render=KEY or data-sitekey). |
| Google Cloud project ID | The ID (not the name) of the project that owns the key, for example my-project-123. |
| Google Cloud API key | An API key from APIs & Services > Credentials in the same project. Restrict it to the reCAPTCHA Enterprise API so it can do nothing else. |
Enable the reCAPTCHA Enterprise API in the project first. The key’s domain list in Google Cloud must include the site that hosts your form. You can paste the key’s full name (projects/my-project-123/keys/6Lc...) into the key ID field to fill in the project ID as well. When you save, StaticForm checks the three values with Google and tells you which one is wrong (an API key Google does not accept, a project it cannot find, or the API not being enabled yet).
On submit, the token goes to StaticForm in the g-recaptcha-response field, the same field reCAPTCHA v2 and v3 use. StaticForm creates an assessment for it, and the submission is accepted only when Google reports the token as valid for your key. A token that was made for a different key, was already used, or is older than two minutes is rejected. Pick the key type in the CAPTCHA settings: for a score-based key, the score Google gives the visitor must also reach the form’s minimum score (see Minimum score).
Use a score-based key with the helper script (type: 'recaptcha-enterprise' and your siteKey), which loads enterprise.js?render=KEY and calls grecaptcha.enterprise.execute() for you. A checkbox key works too: put <div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div> inside the form and the helper reads the widget’s token.
Minimum score
reCAPTCHA v3 and score-based reCAPTCHA Enterprise keys never show a challenge. Google gives every visitor a score from 0.0 (very likely a bot) to 1.0 (very likely a person), and StaticForm rejects the submission when the score is below the form’s minimum score. The minimum starts at 0.5, Google’s recommended threshold, and you can change it in the CAPTCHA settings of the form. A token without a score is rejected as well, so make sure the key type matches the key you created: a reCAPTCHA v2 or checkbox key needs the checkbox key type, which checks the challenge and no score.
Honeypot
A honeypot is a hidden field that real users won’t fill out but spam bots will. If the field has a value, the submission is flagged as spam.
Setup
Enable the honeypot in your form settings and choose a field name (default: website_url). Then add a hidden field to your HTML:
<div style="display: none;" aria-hidden="true">
<input type="text" name="website_url" tabindex="-1" autocomplete="off" />
</div>
Tip: Use a field name that looks like a real field (like
website_url) to trick bots into filling it out.
Language Detection
Language detection analyzes the text content of submissions and flags those that don’t match your expected languages.
Setup
- Enable language detection in your form settings
- Set your expected languages using ISO 639-2/T codes (3-letter, e.g.
eng,deu,fra) - Optionally specify which fields to check (defaults to all free text fields: plain text and text area fields without an email, number or website rule)
This is useful if your form targets a specific audience and you want to filter out submissions in unexpected languages.
Allowed Domains
If your form only lives on your own websites, you can list those domains and StaticForm will treat submissions sent from anywhere else as spam. This is optional and disabled by default. This stops people from copying your form to another site or posting to your endpoint from a page you don’t control.
Setup
- Open Spam Protection in your form settings and expand Allowed Domains
- Enable Only accept submissions from allowed domains
- Add each domain your form is embedded on, for example
example.com
A domain also covers its subdomains, so example.com allows www.example.com and shop.example.com. You can paste a full URL such as https://www.example.com/contact; StaticForm keeps only the domain.
How it works
Browsers send the address of the page a form is submitted from in the Origin header. StaticForm compares that domain with your list:
- Domain on the list: the check passes.
- Domain not on the list: the submission is marked as spam.
- No
Originheader: every modern browser sends one with a form submission, but spam scripts often leave it out. The submission gets a raised spam score, and the AI second opinion decides whether it is genuine. If theRefererheader points to a site that is not on your list, the submission is marked as spam.
Test submissions from the StaticForm dashboard are always allowed. The check is skipped for server-side submission mode, since requests from your server carry no browser headers.
Request Header Analysis
For client-side submissions, StaticForm inspects the request headers. Real browsers send a consistent set of headers that automated HTTP clients do not, so a submission that doesn’t look like it came from a browser is treated as spam. This runs automatically and requires no configuration.
Important when testing: If you test a client-side form with
curl,wget, Postman, HTTPie,python-requests,axios,node-fetch, a headless browser, or any similar tool, the submission will almost certainly be classified as spam. This is expected behaviour, not a bug. The API still answers200 OKand the submission is stored, but it lands in the spam list, and submit actions such as email notifications and webhooks are skipped.Test your form from a real browser instead. Open the page, fill in the fields, and submit it the way a visitor would. That is the only way to see what actually happens with real traffic. If a command-line test submission never reached your inbox, look in the spam list in the dashboard: that is where it went.
IP-Based Analysis
For client-side submissions, StaticForm performs IP-based analysis to detect known spam sources. This runs automatically and requires no configuration.
Note: IP-based analysis is skipped for server-side submission mode since server IPs are expected.
Content Analysis
Alongside the layers above, StaticForm scores the content of each submission. This automatically catches the unsolicited sales pitches that get past CAPTCHA and honeypots, such as cold outreach for services, lead-generation offers, and get-rich-quick or gambling promotions. It weighs several signals together rather than reacting to any single word, so a genuine message that happens to mention a price or a meeting link is not flagged on its own. It also checks the name fields of your form: a real name doesn’t contain digits, so a name like Olga1995 raises the spam score. The name fields are the ones added with the Name quick-add button, plus existing fields called name, first_name, last_name or similar, which were marked automatically when this check was extended. Digits that were copied from another field, such as a phone number a browser appended to the name, are ignored. This runs automatically with no configuration, and like everything else it only contributes to the spam score, so you can always review and override the result in the dashboard.
Four more automatic checks target the bots that fill in forms in bulk:
- Bot-shaped submissions. A single run-together name such as
RobertInfabnext to a bot-style phone number, a name that is repeated in another field, and strings of random capital and lowercase letters are typical for form-filling bots, and rarely occur in real messages. - Link shorteners and paste sites. A link through a link shortener or a paste site, such as
bit.lyortelegra.ph, with or withouthttps://, raises the score steeply. A link in a field that is marked as a website address is not checked, because it is the visitor’s own site. - Known spam senders. When a submission is confirmed as spam by its content or by the AI second opinion (never by IP lists alone), StaticForm remembers a one-way hash of the email addresses and phone numbers in it for 30 days. The same sender trying again on any form is flagged. Only the hash is kept, never the address or number, and marking the original submission as legitimate removes it again.
- Many different messages. The same email address or phone number sending three different messages within 24 hours, to any form, raises the score. Sending the same message twice does not count, and neither does a multi-step form whose earlier steps have no free text. Only one-way hashes are kept, for two days.
AI Second Opinion
Rule-based checks are fast, but they can be wrong about borderline messages: a genuine quote request that happens to include a link, a short “call me back” note, or a message in an unexpected language. For those cases StaticForm can ask an AI classification model for a second opinion.
The AI only looks at submissions the rules are unsure about: something raised the score, but nothing definitive such as a honeypot hit or an invalid email domain. Clear spam and clean submissions are never sent. It reads the submitted fields together with what the rule-based checks found and your form’s allowed-domain and language settings, and answers one question: is this a genuine message from a person who wants to reach the site owner?
- If the AI is confident the message is genuine, it lowers the spam score so the submission lands in your inbox and your submit actions run as normal.
- If the AI is confident the message is spam, it raises the spam score so the submission is blocked, even when the rules only saw a weak signal.
- If the AI cannot tell, the original score stands.
Either way the review is shown with the submission in the dashboard, including the AI’s own spam likelihood and the score before the override, so you can always see why a message was let through or blocked. You can still mark any submission as spam or legitimate yourself.
Turning it on or off
The AI second opinion is on by default for forms created from October 2, 2026. Forms that existed before then keep it off until you turn it on, so no submission data from an existing form is sent anywhere new without your say.
To change it, open the form, go to Spam, expand AI Second Opinion and check or uncheck Enable AI second opinion, then save. Through the API, set enableAiSpamReview when creating or updating a form.
What is sent
When it is enabled, the text fields of a borderline submission (each truncated to 2,000 characters) are sent to an external AI model together with the form name. File uploads, CAPTCHA tokens and the honeypot field are never sent, and neither are submissions that are clearly spam or clearly clean.
To keep specific fields out of the review, for example fields with health information, ID numbers or other sensitive personal details, pick them under Fields to Exclude (aiSpamReviewExcludedFields in the API). Excluded fields are never sent. If every filled-in field is excluded, or the submission has no filled-in free text field (a plain text or text area field without an email, number or website rule), the submission is not reviewed and its rule-based score stands. The AI provider is listed as a sub-processor in our Data Processing Agreement.
Trusted Senders
If messages from a customer, a partner or your own team keep landing in spam, add their email address or their domain to your trusted senders. A submission from a trusted sender skips StaticForm’s spam check, lands in your inbox and your submit actions run as normal. This is optional and disabled by default.
Trusted senders change StaticForm’s own spam check for new submissions. They do not change the spam folder in your email, and submissions that are already in spam stay there: open those and mark them as legitimate.
You can trust senders in three places, and they add up:
- One form: open the form, go to Spam Protection and expand Trusted Senders.
- All your forms: go to Settings, Spam protection. This covers every form you own, including the forms in workspaces you own.
- A workspace: open the workspace and use its Trusted senders card. This covers every form in the workspace. Only the workspace owner can change it.
Turn on the switch, add entries and save. A list can hold up to 100 entries. On a form, the entries from your account and workspace settings are shown too; they stay trusted even when the form’s own switch is off.
What you can add
| Entry | Trusts | Example |
|---|---|---|
| An email address | Only that address | jan@example.com |
| A domain (the part after the @) | Every address at the domain and its subdomains | example.com trusts jan@example.com and jan@mail.example.com |
| A domain with a secret code | Only addresses at the domain that carry the code after a plus sign | code k3v9q2xa on example.com trusts jan+k3v9q2xa@example.com |
Protect a domain with a secret code
Anyone can type any email address into a form. If you trust example.com, a spammer who guesses that domain gets through as well, and trusting a public provider such as gmail.com trusts everyone. The dashboard warns you when you add a bare domain.
A secret code closes that gap. Many email services, such as Gmail, Outlook and iCloud, deliver jan+anything@example.com to jan@example.com. Only people who know the code can add it, so a spammer who types an address at example.com still gets the normal spam check.
- Under Add a trusted sender, type the domain, for example
example.com. - StaticForm asks how to trust it. Choose With a secret code (recommended). StaticForm creates the code for you.
- Click Share next to the code, then Copy message, and send it to the people you trust. The message asks them to add the code to their email address, right before the @:
jan@example.combecomesjan+k3v9q2xa@example.com. Click the code itself to copy just the code. - Save.
People without the code still go through the normal spam check. Replies to these submissions go to the address with the code, so check with your contact that their email service accepts it. If the code gets out, click the New code button (the circular arrows next to Share), save, and send the new code; the old one stops working.
A domain you already trust without a code is marked Anyone can use this and has a Require code button. StaticForm asks you to confirm first, because after saving, people at that domain need the code to skip the spam check.
If you type a public email provider such as gmail.com, outlook.com, icloud.com, gmx.de or ziggo.nl, you probably meant one person: type their full address instead. Trusting everyone at a public provider is not possible, because anyone can sign up there; single addresses and a secret code are. StaticForm recognizes about 100 public providers, the same list its other spam checks use.
How it works
StaticForm reads the fields that have the Email validation rule. When one of them holds a trusted address, the content, IP, email and reputation checks are skipped and so is the AI second opinion: the submission gets a spam score of zero. The form needs at least one field with the Email rule for this to work.
These checks still apply to trusted senders, because they are settings you chose for every submission rather than guesses about the content:
- CAPTCHA
- the honeypot field
- allowed domains
- the server secret of a server-side form
Through the API
A domain with a secret code is written as +code@domain, for example +k3v9q2xa@example.com.
- A form:
enableSenderAllowlistandsenderAllowlistwhen creating or updating it. - All your forms:
PUT /api/v1/users/me/settings/trusted-senderswithenableSenderAllowlistandsenderAllowlist. - A workspace:
PUT /api/v1/workspaces/{workspaceId}/trusted-senderswith the same body.
The MCP tools are update_form, update_my_trusted_senders and update_workspace_trusted_senders.
Spam Management
All submissions include a spam probability score. In the dashboard you can:
- View spam scores and detection categories for each submission
- Manually mark submissions as spam or legitimate
- View separate spam and legitimate submission lists
Files uploaded with a submission that is blocked as spam are kept, but they don’t count toward your storage while the submission is spam, so a wave of spam cannot fill it. If you mark such a submission as legitimate, its files count toward your storage again, even when that takes you over your limit; new uploads are then refused until space frees up. A submission that is still spam a year after it was blocked loses its uploaded files; the rest of the submission is kept. The spam list and the submission details show when that will happen.

