Spam Protection
Freeform includes a variety of robust spam control features to make managing forms easier.
reCAPTCHA
hCaptcha
Turnstile
Honeypot
Javascript Test
AI Spam Analysis
Blocked Keywords
Blocked Emails
Blocked IP Addresses
Block Gibberish
Snaptcha
HoneypotImproved in 5.0+
Freeform includes its own Honeypot spam protection feature. This is enabled by default, but can be disabled in the Other area of the Integrations settings. You can then enable/disable per form.
It works by inserting an input in the form that is invisible to a regular user. A regular user will not see or be able to add a value to the field, leaving it empty and passing the test. If the bot enters a value in the input, the test will fail.
Javascript TestImproved in 5.0+
In Freeform 5.9+, the Javascript Test became available to the Express edition of Freeform.
Freeform includes its own Javascript Test spam protection feature. When enabled, it will help fight spambots more aggressively by requiring that users have javascript enabled for their browser to submit the form. This is disabled by default, but can be enabled in the Other area of the Integrations settings. You can then enable/disable per form.
It works by inserting an input in the form that is invisible to a regular user with a random value. The javascript loaded into the page then automatically removes the value from the input, allowing the test to pass. If the user or bot doesn't have javascript enabled, the value will not be removed from the input and will fail the test.
Spam Behavior
The following spam protection behavior settings are available and apply to all spam settings and integrations.
Spam Protection Behavior
Select the behavior you'd like Freeform to take when it detects a submission as being spam.
- Simulate SuccessRecommended
- If you have the Spam Folder feature enabled, spammy submissions will go through to the Spam Folder in the Freeform control panel.
- An error is not displayed so as not to give away the spam controls.
- Display Errors (for debugging)
- Useful for troubleshooting if you're experiencing some issues with submissions being flagged as spam.
Bypass All Spam Checks for Logged in Users
When enabled, Freeform will not run any spam protection measures for logged in users.
Spam Folder
When the Spam Folder setting is enabled, all submissions caught by any spam measure (including Honeypot, reCAPTCHA, keyword blocking, etc) will be stored in the database but marked as spam. They will then be available to manage in a separate menu inside Freeform.
Enabling the Spam Folder feature will not retroactively bring back any previously blocked spam submissions. Any submissions that have been blocked in the past (without Spam Folder setting on) are never recorded in the database.
Spam Reasons
If Freeform flags a submission as spam, it will provide specific reasons for the flagging. These reasons can help you determine why the submission failed and assist you in resolving any configuration errors or issues. You can find the detailed spam reasons in the right column of the submission detail page. Additionally, a summary of the reasons is displayed as a column in the index listing view of the Freeform Spam Folder. You also have the option to filter submissions based on the reason for the spam flag.
Spam BlockingImproved in 5.5+
If Freeform detects any blocked keywords/values in the form submission, it will flag it as spam. It will then go into the spam folder (if configured) or show an error at the top of the form (not recommended).
Freeform's spam blocking features are now handled as integrations. Previously, whenever Craft's allowAdminChanges was set to false, it was no longer possible for users to modify blocked keywords, emails and IP addresses. This has been rectified by moving them from the settings to integration types. Users can now create pre-built sets of spam blocks, share them across forms, and manage each individually per form.
To configure spam blocking, visit the Settings > Integrations > Spam Blocking section.
Available Options
- AI Spam AnalysisProNew in 5.12+
- Email AddressesImproved in 5.13+
- Keywords
- IP AddressesImproved in 5.13+
- GibberishNew in 5.13+
Syntax
- Add each rule on a new line.
- Use
*for wildcard matches (except on IP addresses), e.g.cat*will flagcat,cats,category, etc.- When blocking individual characters (e.g. Russian letters) or partial words or strings, be sure to put the wildcard at the start and end of the value, e.g.:
*й*,*Д*,*url=http*, etc.
- When blocking individual characters (e.g. Russian letters) or partial words or strings, be sure to put the wildcard at the start and end of the value, e.g.:
- To block phrases, wrap quotes around the keywords (e.g.
"generate new leads").
Email Address BlockingImproved in 5.13+
This option allows you to block specific email addresses or domains used in Email field types.
- Check MX RecordNew in 5.13+
- Email addresses will be validated against their domain's MX records to ensure the domain can receive mail.
- Display Errors about Blocked Emails under each Email Field
- Enable this if you'd like field-based errors to display under the email field(s) that the user has entered blocked emails for. Not recommended for regular use, but helpful if trying to troubleshoot submission issues.
- Blocked Email Addresses
- Enter email addresses you would like blocked from being used in Email fields. Use asterisks for wildcards (e.g.
*@hotmail.ru), and separate multiples on new lines. - The values entered here will apply to all forms that use this integration. Additionally, form-specific blocks can be set inside the form builder.
- Enter email addresses you would like blocked from being used in Email fields. Use asterisks for wildcards (e.g.
Keyword Blocking
This option allows you to block specific words used in fields.
- Display Errors about Blocked Keywords under each Field
- Enable this if you'd like field-based errors to display under the field(s) that the user has entered blocked keywords for. Not recommended for regular use, but helpful if trying to troubleshoot submission issues.
- Blocked Keywords
- Enter keywords you would like blocked from being used in all text and textarea fields. Use quotes for phrases (e.g.
"generate new leads"), asterisks for wildcards (e.g.lead*), and separate multiples on new lines. When attempting to block individual characters (e.g. Russian letters) or partial words or strings, be sure to make good use of the wildcard character by placing one before and after (e.g.*й*or*Д*). - The values entered here will apply to all forms that use this integration. Additionally, form-specific blocks can be set inside the form builder.
- Enter keywords you would like blocked from being used in all text and textarea fields. Use quotes for phrases (e.g.
IP Address BlockingImproved in 5.13+
This option allows you to block specific IP addresses or ranges, including DNS block lists.
- Blocked IP Addresses
- Enter IP addresses you would like blocked. Separate multiples on new lines.
- The values entered here will apply to all forms that use this integration. Additionally, form-specific blocks can be set inside the form builder.
- Check DNS Block ListsNew in 5.13+
- IP addresses will be checked against the DNS block lists provided below to help detect spam and abusive activity.
- Default DNS Block Lists
- Enter the DNS block lists you'd like to use. Add one per line.
- The values entered here will apply to all forms that use this integration. Additionally, form-specific blocks can be set inside the form builder.
Gibberish BlockingNew in 5.13+
This option allows you to block Gibberish values when entered into fields, e.g. dfsjghdfjkghdsdfg or sdfg5769d9gd.
- Gibberish Word Minimum Length
- Minimum word length used to detect gibberish. Lower values increase sensitivity but may flag valid words.
- Allowed Terms
- Enter words or abbreviations that should be ignored by gibberish detection. Add one per line (e.g.,
RFP,ABB,KUKA, or other technical terms). - The values entered here will apply to all forms that use this integration. Additionally, form-specific blocks can be set inside the form builder.
- Enter words or abbreviations that should be ignored by gibberish detection. Add one per line (e.g.,
Throttling
If your site is being attacked by spammers or you're concerned about it, you can enable the Form Submission Throttling setting. This will globally (affecting all users) prevent spam or attacks by limiting the number of times all forms can be submitted within a given timeframe.
This feature is intended for extreme conditions, such as preventing your site from going down if attacked by a spammer. It should NOT be used as a 'fine-tuning' spam measure, as it applies to ALL users. For example, if you set it to '1 per minute', once one user submits any form, any other user will not be able to submit a form within that timeframe. A more realistic value for smaller websites is something like 50 per minute. Use extreme caution for larger and more active sites.
Captchas
Freeform currently supports the following Captcha services:
In Freeform 5.9+, all captcha options became available to all editions of Freeform.
reCAPTCHA
The options below are compatible with the Enterprise API and the Classic legacy keys:
hCaptcha
Turnstile
Setup Guides
If you're interested in using any of the following captchas, please click on the applicable button below.
Snaptcha
Freeform is compatible with the Snaptcha plugin if you wish to use it for spam protection.
When using AJAX-based forms, you'll need to refresh Snaptcha after each submission to allow users to resubmit the form (for example, if validation fails or they submit multiple times). The Snaptcha docs provide a guide for this in their AJAX Requests documentation.
To handle this automatically, add the following JavaScript after your form or the {{ form.renderClosingTag }} tag in your template:
{% js %}
document.addEventListener('freeform-ajax-after-submit', async () => {
const snaptchaInput = document.querySelector('input[name="snaptcha"]');
if (snaptchaInput) {
const nameResponse = await fetch('/actions/snaptcha/field/get-field-name');
const valueResponse = await fetch('/actions/snaptcha/field/get-field-value');
snaptchaInput.name = await nameResponse.text();
snaptchaInput.value = await valueResponse.text();
}
});
{% endjs %}
This script listens for Freeform's freeform-ajax-after-submit event and refreshes the Snaptcha field's name and value, ensuring the form can be submitted again without requiring a full page reload.