Mautic Multi-CAPTCHA Plugin Installation and Configuration Guide

Unfiltered form submissions create noise, distort reporting, and undermine marketing automation. The Mautic Multi-CAPTCHA plugin offers a direct way to protect forms using Google reCAPTCHA, hCaptcha, or Cloudflare Turnstile—without any custom code. Each CAPTCHA type appears as a native Mautic form field, allowing administrators to enhance security in minutes while preserving a smooth user experience.

Why Install This Plugin?

Core Benefits

1. Strong spam protection

• Blocks automated submissions
• Reduces fake contacts and poor-quality leads
• Prevents bots from damaging your email reputation

2. Privacy-focused alternatives

• hCaptcha and Cloudflare Turnstile offer privacy-aligned options
• Suitable for organisations that minimise Google reliance
• Helps strengthen compliance with GDPR and POPIA requirements

3. Flexible implementation

• Assign different CAPTCHA types to different form types
• Choose visible or invisible modes where supported
• Works with progressive profiling, conditional fields, and all standard Mautic form logic

4. Fully native experience

• No code changes or overrides required
• Managed entirely through the Mautic plugin interface
• Maintained as a standard bundle within your installation

When This Plugin Is Useful

• You are receiving high-volume spam submissions
• Your organisation prefers non-Google verification services
• You need to compare success rates across CAPTCHA vendors
• You operate on shared hosting where server-side customisations are limited

Installation Requirements

Before installing, confirm that your environment meets the following:

• Mautic version: Designed for Mautic 6+

  • Mautic 5 may work but is not tested or supported
• PHP version: PHP 8.1+ is required
• Access: Either SSH for Composer installation or FTP/SFTP for manual installation
• Permissions: Web server user (www-data, apache, etc.) must have read/write access to plugin directories

Installation Methods

Composer Installation (Recommended)

This is the most reliable method. Composer handles dependencies automatically and simplifies updates. Github Repo.

Steps

1. SSH into your server and navigate to your Mautic root directory

2. Install the plugin:

   composer require firemultimedia/mautic-multi-captcha-bundle
   

3. Clear Mautic cache:

   php bin/console cache:clear
   

4. In Mautic, go to Settings → Plugins → Install/Upgrade Plugins

5. Confirm that the following appear:

   • Mautic hCaptcha Integration
   • Mautic Google reCAPTCHA Integration
   • Mautic Cloudflare Turnstile Integration

Manual Installation (FTP Method)

Use this if SSH access is unavailable. Github Repo.

Steps

1. Create the plugin directory:

   {mautic_root}/plugins/MauticMultiCaptchaBundle/
   

   The name must be exactly MauticMultiCaptchaBundle — case-sensitive and with no spaces.

2. Download the ZIP file from GitHub and extract it locally

3. Upload all files into the folder using FTP/SFTP

4. Clear cache:

   • If you have SSH:

     php bin/console cache:clear
     

   • If not: delete the contents inside var/cache/

     Do not delete the cache folder itself — only the items inside it.

5. Go to Settings → Plugins → Install/Upgrade Plugins

6. Set correct file permissions:

   • Directories: 755
   • Files: 644
   • Owned by your web server user

Configuration

Each CAPTCHA service must be configured independently.

Google reCAPTCHA

1. Create keys: https://www.google.com/recaptcha/admin/create
2. In Mautic: Settings → Plugins → Google reCAPTCHA Integration
3. Enter Site Key and Secret Key
4. Choose reCAPTCHA v2 or v3
5. Add the Google reCAPTCHA field to your form and adjust its Properties

Note:

• reCAPTCHA v3 produces a score (0.0–1.0)
• Use scores ≥ 0.5 as a typical passing threshold

hCaptcha

1. Register your domain: https://dashboard.hcaptcha.com/sites/new
2. In Mautic: Settings → Plugins → hCaptcha Integration
3. Enter your keys
4. Add hCaptcha to any form and configure its properties

Cloudflare Turnstile

1. Create a widget in your Cloudflare dashboard
2. In Mautic: Settings → Plugins → Cloudflare Turnstile Integration
3. Enter Site Key and Secret Key
4. Add the field to your form

Note: Cloudflare is a US-based company, but Turnstile is designed to be privacy-aligned and lightweight.

Choosing Between Installation Methods

Maintenance

Routine Tasks

1. Monitor CAPTCHA effectiveness

• Check form submission logs monthly
• Look for spikes in failed validations

2. Update the plugin

• Composer:

  composer update firemultimedia/mautic-multi-captcha-bundle
  

• Manual: download latest ZIP and re-upload files

3. Rotate API keys annually

• Improves security
• Update keys in Mautic immediately to avoid rejected submissions

4. Clear cache after updates

• Required after every upgrade or code change

5. No cron jobs required

• This plugin works entirely through client-side validation

Pitfalls and Best Practices

Common Pitfalls

1. Incorrect folder name

• Prevents plugin detection
• Must be exactly MauticMultiCaptchaBundle

2. Cache not cleared

• New plugins fail to appear until cache is cleared

3. Missing or incorrect API keys

• Submissions fail silently
• Always test keys in a staging form first

4. Version mismatch

• Plugin is designed for Mautic 6+
• Mautic 5 may work but is not tested or supported

5. File permissions

• Incorrect ownership may trigger 500 errors

Best Practices

1. Test in staging first to avoid breaking live forms
2. Start with one CAPTCHA service to simplify troubleshooting
3. Use reCAPTCHA v3 for a frictionless user experience
4. Use visible CAPTCHA challenges for high-risk forms (contact, registration)
5. Use private browsing to test without cached sessions
6. Back up your installation before any plugin update

Final Notes & Next Steps

This plugin adds minimal overhead (typically 50–200ms) and provides a robust, configurable way to secure Mautic forms. For GDPR-aligned setups, hCaptcha and Turnstile offer strong alternatives to Google’s behavioural tracking model.

For bug reports or feature requests, submit issues on the Github Repo.