Form Filters

This page documents filters for customizing form processing — from the action URL to the final email.

Filter	Description
unblock/form/action	Form action URL
unblock/form/client_ip	Client IP address used for rate limiting
unblock/form/fields	Sanitized form fields before email
unblock/form/allowed_extensions	Allowed file extensions for attachments
unblock/form/send_email	Whether to send the default email notification
unblock/form/email	Email arguments before wp_mail()

form/action

Filter the form action URL injected into data-unbk-form forms.

apply_filters( 'unblock/form/action', string $action_url );

Parameter	Type	Description
$action_url	string	REST endpoint URL. Default: rest_url( 'unblock/v1/form' )

Example: Custom Endpoint

add_filter( 'unblock/form/action', function( $action_url ) {

    return home_url( '/custom-form-handler/' );

} );

form/client_ip

Filter the client IP address used for rate limiting form submissions.

By default, $_SERVER['REMOTE_ADDR'] is used. If your server is behind a reverse proxy (Cloudflare, Fastly, etc.), use this filter to return the real client IP from a trusted header.

apply_filters( 'unblock/form/client_ip', string $ip, \WP_REST_Request $request );

Parameter	Type	Description
$ip	string	Client IP address. Default: $_SERVER['REMOTE_ADDR']
$request	\WP_REST_Request	REST request object

Example: Cloudflare

add_filter( 'unblock/form/client_ip', function( $ip, $request ) {

    $cf_ip = $request->get_header( 'CF-Connecting-IP' );

    return $cf_ip ? $cf_ip : $ip;

}, 10, 2 );

Example: Generic Reverse Proxy

add_filter( 'unblock/form/client_ip', function( $ip, $request ) {

    $forwarded = $request->get_header( 'X-Forwarded-For' );

    if ( $forwarded ) {
        $ips = explode( ',', $forwarded );
        return trim( $ips[0] );
    }

    return $ip;

}, 10, 2 );

Security

Only trust proxy headers if you are certain your server is behind a trusted reverse proxy. Spoofed headers can bypass rate limiting.

form/fields

Filter the sanitized form fields before the email is built.

apply_filters( 'unblock/form/fields', array $fields, Context $context );

Parameter	Type	Description
$fields	array	Sanitized field key-value pairs
$context	\Unblock\Form\Context	Form context

Example: Add Referer Field

add_filter( 'unblock/form/fields', function( $fields, $context ) {

    $fields['submitted_from'] = $context->referer();

    return $fields;

}, 10, 2 );

form/allowed_extensions

Filter allowed file extensions for form attachments.

apply_filters( 'unblock/form/allowed_extensions', array $extensions, Context $context );

Parameter	Type	Description
$extensions	array	Default: ['jpg', 'jpeg', 'png', 'gif', 'webp', 'pdf', 'doc', 'docx']
$context	\Unblock\Form\Context	Form context

Example: Allow ZIP and CSV

add_filter( 'unblock/form/allowed_extensions', function( $extensions ) {

    $extensions[] = 'zip';
    $extensions[] = 'csv';

    return $extensions;

} );

Common mistake

Adding executable extensions like php, js, or exe here is a security risk. Only allow file types you actually need.

form/send_email

Filter whether to send the default email notification. Return false to skip email entirely — useful when forwarding submissions to an external service (HelpScout, Salesforce, etc.).

apply_filters( 'unblock/form/send_email', bool $send, Context $context );

Parameter	Type	Description
$send	bool	Whether to send the email. Default: true
$context	\Unblock\Form\Context	Form context

Example: Disable Email Globally

add_filter( 'unblock/form/send_email', '__return_false' );

Example: Disable Email for a Specific Form

add_filter( 'unblock/form/send_email', function( $send, $context ) {

    return 'contact' !== $context->form_id();

}, 10, 2 );

Form ID

The form ID comes from the data-unbk-form attribute value. If empty, it falls back to the block's uid. Access it via $context->form_id().

Error handling

When using send_email with an external service, call $context->add_error( $code, $message ) in your unblock/form/processed hook to report failures to the client. See the form/processed action for a full example.

form/email

Filter all email arguments before sending via wp_mail().

apply_filters( 'unblock/form/email', array $email_args, Context $context );

Parameter	Type	Description
$email_args	array	Keys: to, subject, body, headers, attachments
$context	\Unblock\Form\Context	Form context

Example: Route by Referer

add_filter( 'unblock/form/email', function( $args, $context ) {

    if ( str_contains( $context->referer(), '/careers' ) ) {
        $args['to'] = '[email protected]';
    }

    return $args;

}, 10, 2 );

Example: Add CC Header

add_filter( 'unblock/form/email', function( $args, $context ) {

    $args['headers'][] = 'Cc: [email protected]';

    return $args;

}, 10, 2 );

Next steps

• Actions — form lifecycle hooks (form/processed, form/spam_detected)
• Security filters — allowed form actions and HTML sanitization