Skip to main content

Spam Protection

Freeform includes a variety of robust spam control features to make managing forms easier.

​Javascript Honeypot

Freeform includes its own Honeypot spam protection feature. This is enabled by default, but can be disabled in the Spam Settings. If enabled, you can specify the behavior Freeform takes when a spammy submission is detected with the Spam Protection Behavior setting:

  • Simulate Success (recommended)
    • 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.
  • Reload form
    • This is a less user-friendly approach to legitimate users that are having their submissions flagged as spam for some reason, but at least shows a sign that there's something wrong - which would be more practical if not using the Spam Folder feature.
    • Spammy submissions do not go through at all in this case, but it will increment the Spam Counter in the Forms page in the Freeform control panel.

​Important Information about how the Freeform Honeypot field works

  • Each time a form is loaded, it stores a unique honeypot per session, which has a timestamp, unique name and unique hash value.
    • Both name and hash must match to successfully submit the form or advance to the next page.
    • A user is allowed 100 honeypot values per user session (highly unnecessary but in case your site has a form in a common place like a footer, etc it'll help prevent unwanted blocking of legitimate users).
    • Honeypots are stored in the session for 3 hours, and then are removed.
      • Because this uses the session, this limit is also dependent on the server configuration for session.gc_maxlifetime() in php.ini. Typically the default might be 1440 seconds (24 minutes), but it's possible the default has been altered to something else.
  • When the form opens, the value is wrong by default, and then javascript swaps in the correct value.
  • The honeypot is not a hidden field, but is positioned absolutely with height 0 and width 0, so the field is not visible.
  • This spam protection method requires javascript be enabled for the user's browser, otherwise it will fail.
    • Freeform will automatically insert javascript in the footer of the page. If you prefer to have this load inside the <form></form> tags (for purposes of caching, etc), you can control this with the Freeform Javascript Insertion Location setting.

The Honeypot can also be manually rendered as follows:

{% set form = craft.freeform.form("formHandle") %}
{% set honeypot = craft.freeform.honeypot(form) %}
{{ honeypot.name }}
{{ honeypot.hash }}

​Spam Folder

When the Use Spam Folder setting is enabled, all submissions caught by the Javascript Honeypot or blocked email addresses, keywords and IP addresses will be flagged as spam and stored in the database, but available to manage in a separate menu inside Freeform.

  • Email notifications and API integrations will all be suppressed and queued.

  • When viewing the Spam Folder in the Freeform control panel, you have the ability to delete or approve/allow each submission.

    • Allowing spammy submissions will retroactively fire off email notifications and any API integration data as well.

  • The Spam Folder can be set to have older spammy submissions automatically purged after a period of time. To enable this, enable the Automatically Purge Spam Submissions setting and specify the number of days after submission date it should purge them.

    Enabling this and saving this settings page will begin the purging of submissions flagged as spam, and cannot be undone.

​Spam Blocking

Freeform gives you the ability to block multiple email addresses, keywords and IP addresses. Separate multiples on new lines, and use * for wildcard (except on IP addresses).

  • If the submission fails, it will then match the behavior of the Spam Protection Behavior setting.
  • If you have the Spam Folder feature enabled, spammy submissions will go through to the Spam Folder in the Freeform control panel.
  • You have the option to display errors for fields using a blocked email address or keyword, but we recommend only using this for troubleshooting purposes.

​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.

​Captchas

​reCAPTCHAPro

If you wish to use reCAPTCHA for your forms, enable the reCAPTCHA setting and fill in the reCAPTCHA Site Key and Secret Key. To add reCAPTCHA to your forms, open up and edit each form and drag over the reCAPTCHA special field anywhere you like into your form layout.

reCAPTCHA fields will render automatically like the rest of your fields in your form, but if you're building a form manually, you'd call it like this (using the Hash value for reCAPTCHA field in Property Editor of Composer):

{% set form = craft.freeform.form("composerForm") %}
{% set recaptcha = form.get("JDGnlp8vB") %}

{{ recaptcha.renderInput }}

If you're loading an entire form via AJAX, you'll need to load the reCAPTCHA JS yourself, since it's considered insecure otherwise and the browser blocks it. You should add this script tag anywhere on your page, preferably the footer:

<script
  type="text/javascript"
  src="https://www.google.com/recaptcha/api.js?render=explicit"
></script>
Page Feedback