powermailcaptcha 

Extension key

powermailcaptcha

Package name

traw/powermailcaptcha

Version

2.2.1

Language

en

Author

Thomas Rawiel

License

This document is published under the Creative Commons BY 4.0 license.

Rendered

Wed, 27 May 2026 15:54:58 +0000

Captcha extension for EXT:powermail

Table of Contents:

Installation 

Install this extension via composer:

composer require traw/powermailcaptcha

or add it to your extension's composer.json file:

"require": {
    "typo3/cms-core": "^12 || ^13",
    "traw/powermailcaptcha": "^2.0"
}

Configuration 

• Include powermailcaptcha Typoscript.
• Setup the Captcha type of your choice
• Add a field of the type Powermailcaptcha to your powermail form

Typoscript Reference 

plugin.tx_powermail.settings.setup.spamshield._enable = 1

This is an overview of the available Typoscript constants. They are also available in the Constant Manager.

Hints 

Required: Make sure powermail spamshield is enabled:

plugin.tx_powermail.settings.setup.spamshield._enable = 1

---

Optional: Keep up to date if powermail recognize spam (TypoScript setup):

# Get an email if spam was recognized
plugin.tx_powermail.settings.setup.spamshield.email = spamreceiver@yourdomain.de

# Write to a logfile when spam was recognized
plugin.tx_powermail.settings.setup.spamshield.logfileLocation = typo3temp/logs/powermailSpam.log

---

Optional: Remove the default captcha field by adding the following to your Page TSConfig:

TCEFORM.tx_powermail_domain_model_field.type.removeItems := addToList(captcha)

---

Required: If you override powermail's partial Partial/Form/Page.html in your own extension, make sure to add the variable languageIso to the f:render of the Fields:

<f:render partial="Form/Field/{vh:String.Upper(string:field.type)}" arguments="{field:field, languageIso:languageIso}"/>

Extend Captcha Providers 

CAPTCHA validation can be extended and customized via two events:

final class MyCaptchaConfigurationListener
{
    public function __invoke(CaptchaConfigurationEvent $event): void
    {
        $configuration = $event->getConfiguration();

        $configuration['mycaptcha'] = [
            'siteVerifyUri' => 'https://example.com/verify',
            'verifyMethod' => 'POST',
            'responseKey' => 'my-captcha-response',
            'secretParameter' => 'secret',
            'responseParameter' => 'token',
        ];

        $event->setConfiguration($configuration);
    }
}

$defaultCaptchaConfiguration = [
    'recaptcha' => [
        'siteVerifyUri' => 'https://www.google.com/recaptcha/api/siteverify',
        'verifyMethod' => 'GET',
        'responseKey' => 'g-recaptcha-response',
        'secretParameter' => 'secret',
        'responseParameter' => 'response',
    ],
    'friendlycaptcha' => [
        'siteVerifyUri' => 'https://api.friendlycaptcha.com/api/v1/siteverify',
        'verifyMethod' => 'POST',
        'responseKey' => 'frc-captcha-solution',
        'secretParameter' => 'secret',
        'responseParameter' => 'solution',
    ],
    'hcaptcha' => [
        'siteVerifyUri' => 'https://hcaptcha.com/siteverify',
        'verifyMethod' => 'POST',
        'responseKey' => 'h-captcha-response',
        'secretParameter' => 'secret',
        'responseParameter' => 'response',
    ],
    'cloudflare' => [
        'siteVerifyUri' => 'https://challenges.cloudflare.com/turnstile/v0/siteverify',
        'verifyMethod' => 'POST',
        'responseKey' => 'cf-turnstile-response',
        'secretParameter' => 'secret',
        'responseParameter' => 'response',
    ],
    'procaptcha' => [
        'siteVerifyUri' => 'https://api.prosopo.io/siteverify',
        'verifyMethod' => 'POST',
        'responseKey' => 'procaptcha-response',
        'secretParameter' => 'secret',
        'responseParameter' => 'token',
    ],
];

final class MyExpectedResponseListener
{
    public function __invoke(ExpectedResponseEvent $event): void
    {
        $configuration = $event->getConfiguration();
        $result = $event->getResult();

        if (($configuration['captchaMethod'] ?? null) === 'mycaptcha') {
            $event->setResponse(
                ($result->status ?? null) === 'valid'
                && ($result->score ?? 0) > 0.5
            );
        }
    }
}

Supported Captcha Types 

Google reCAPTCHA 

• Register your domain to https://www.google.com/recaptcha/about/
• Add sitekey and secretkey to the Typoscript constants
• In TypoScript Constants, set the captcha method to recaptcha (This is the default)

Friendly Captcha 

• Register your domain to https://docs.friendlycaptcha.com/#/installation
• Add sitekey and secretkey to the Typoscript constants
• In TypoScript Constants, set the captcha method to friendlycaptcha

hCaptcha 

• Register your domain to https://docs.hcaptcha.com/
• Add sitekey and secretkey to the Typoscript constants
• In TypoScript Constants, set the captcha method to hcaptcha

Cloudflare Turnstile 

• Register your domain to https://www.cloudflare.com/products/turnstile/
• Add sitekey and secretkey to the Typoscript constants
• In TypoScript Constants, set the captcha method to cloudflare

Prosopo Procaptcha 

• Register your domain to https://www.prosopo.io/
• Add sitekey and secretkey to the Typoscript constants
• In TypoScript Constants, set the captcha method to procaptcha

Supported languages 

Depending on your website language, not all languages are supported for every Captcha-Method.

Read

• Google Recaptcha https://developers.google.com/recaptcha/docs/language
• Friendly Captcha http://docs.friendlycaptcha.com/#/widget_api?id=data-lang-attribute
• hCaptcha https://docs.hcaptcha.com/languages/
• Cloudflare Turnstile https://developers.cloudflare.com/turnstile/reference/supported-languages/
• Prosopo Procaptcha https://github.com/prosopo/captcha/tree/main/packages/common/src/locales

for further information on supported language codes.

PSR-14 events 

The PSR-14 event BeforeVerifyRequestEvent has been added in order to manipulate the additional request options that are sent to the Site-Verify-URL

The CaptchaConfigurationEvent has been introduced to make the default CAPTCHA provider configuration extensible, allowing listeners to adjust or extend provider-specific settings (e.g. endpoints, parameter names, request methods) before they are applied.

The ExpectedResponseEvent has been introduced to map provider-specific response formats to a unified boolean outcome, ensuring consistent validation handling across different CAPTCHA methods.

Implementing an event listener in your extension

Older versions 

For TYPO3 11 and older powermail versions, please install traw/powermailcaptcha ^1.0

Requirements:

"php": "^7.4 || ^8.0",
"in2code/powermail": "^9.0 ||  ^10.5 || ^11.0 || ^12.0"

Sitemap