Customize the Built-in CAPTCHA Page

When you use MailPoet’s built-in CAPTCHA to protect your subscription forms, visitors who need to verify they are not a robot will see a CAPTCHA challenge. Starting with MailPoet 5.18, this challenge appears directly inside your subscription form when JavaScript is enabled, so visitors never leave the page. If a visitor’s browser has JavaScript disabled, they are redirected to a separate CAPTCHA page instead. You can customize this fallback page to match the look and feel of your website.

Prerequisites

  • MailPoet version 5.16.2 or later (5.18 or later recommended for the best experience).
  • The built-in CAPTCHA must be enabled. To check, go to MailPoet > Settings > Advanced and confirm that CAPTCHA is set to Built-in CAPTCHA (default).

How the Built-in CAPTCHA Works

When a visitor submits your MailPoet subscription form and needs to complete a CAPTCHA verification, MailPoet handles it in one of two ways:

  • JavaScript enabled (most visitors): The CAPTCHA challenge appears inline, directly within the subscription form. The visitor can type the characters, refresh the image, or listen to an audio version — all without leaving the page. This behavior was introduced in MailPoet 5.18.
  • JavaScript disabled (fallback): The visitor is redirected to a dedicated CAPTCHA page. By default, MailPoet uses an auto-generated page called MailPoet Page, which applies your active theme’s standard page template. You can replace this with a custom page by following the steps below.

Create a Custom CAPTCHA Page

1. Create a new WordPress page

  1. In your WordPress dashboard, go to Pages > Add New.
  2. Give the page a title, for example, “Verify You’re Human.”
  3. Add any content you would like visitors to see around the CAPTCHA form, such as a brief explanation or your site branding.
  4. Insert the [mailpoet_page] shortcode where you want the CAPTCHA form to appear. This shortcode tells MailPoet where to render the CAPTCHA challenge on the page.
  5. Click Publish to make the page live.

Note: The page must contain the [mailpoet_page] shortcode for the CAPTCHA form to display. You can add your own content above or below the shortcode, but do not remove it.

2. Select the page in MailPoet settings

  1. Go to MailPoet > Settings > Advanced.
  2. Scroll down to the Built-in CAPTCHA page setting. This option only appears when the built-in CAPTCHA is enabled.
  3. Use the dropdown to select the WordPress page you created in the previous step.
  4. Click the Preview link to see how the page looks. In preview mode, a placeholder message is displayed in place of the actual CAPTCHA form.
  5. Click Save settings.

That is all you need to do. Visitors who have JavaScript disabled will now see your custom page instead of the default one when they need to verify they are not a robot.

Reverting to the Default Page

If you prefer to go back to MailPoet’s default auto-generated CAPTCHA page, return to MailPoet > Settings > Advanced, select the default MailPoet Page from the Built-in CAPTCHA page dropdown, and save your settings.

Good to Know

  • Logged-in Editors and Administrators are not shown the CAPTCHA challenge. To test it, use a logged-out browser session or an incognito window.
  • The [mailpoet_page] shortcode is shared across several MailPoet pages (such as the Confirmation and Unsubscribe pages). On the CAPTCHA page, it renders the CAPTCHA form specifically.
  • The custom CAPTCHA page will not display as intended if viewed directly from the WordPress page editor or the site frontend. Use the Preview link in MailPoet > Settings > Advanced to see a proper preview.
  • If you use the SG Optimizer plugin and the CAPTCHA is not visible for logged-out users, try disabling the Minify the HTML Output option under Frontend Optimizations.

Related Articles