Developer Guide: Customizing CF7 AntiSpam Filters

The CF7 AntiSpam plugin now uses a modular “Pipeline” architecture. This means every spam check (DNSBL, HoneyPot, Bad Words, etc.) is an individual WordPress filter hooked into cf7a_spam_check_chain.

This allows developers to:

1. Inspect or modify the data being checked.
2. Add custom spam checks easily.
3. Remove or re-order default checks.

1. The $spam_data Array

All filters in the chain receive and must return a single array called $spam_data. This array contains the context of the submission and the current spam status.

Structure of $spam_data:

PHP

$spam_data = array(
    // Context (Read Only recommended)
    'submission'    => (object) WPCF7_Submission instance,
    'posted_data'   => (array)  The raw form data,
    'remote_ip'     => (string) The user IP address,
    'user_agent'    => (string) The user browser agent,
    'message'       => (string) The message body,
    'emails'        => (array)  List of emails found in the form,
    
    // State (Read/Write)
    'spam_score'    => (float)  Current spam score (default 0),
    'is_spam'       => (bool)   True if spam detected,
    'reasons'       => (array)  List of reasons why it was flagged,
    'is_whitelisted'=> (bool)   If true, subsequent filters usually skip processing,
);

2. How to Create a Custom Filter

To add your own anti-spam logic, hook into cf7a_spam_check_chain. You can check any data in the array and update the spam_score and reasons.

Example: Block specific email domains

Add this code to your theme’s functions.php or a custom plugin.

PHP

add_filter( 'cf7a_spam_check_chain', 'my_custom_cf7_domain_blocker', 15 );

function my_custom_cf7_domain_blocker( $data ) {
    // 1. If explicitly whitelisted by previous filters, skip.
    if ( $data['is_whitelisted'] ) {
        return $data;
    }

    // 2. Define domains to block
    $blocked_domains = array( 'spammy-domain.com', 'fake-mail.net' );

    // 3. Check submitted emails
    if ( ! empty( $data['emails'] ) ) {
        foreach ( $data['emails'] as $email ) {
            $domain = substr( strrchr( $email, "@" ), 1 );
            
            if ( in_array( $domain, $blocked_domains ) ) {
                // 4. Mark as spam
                $data['spam_score'] += 5; // Add points
                $data['is_spam'] = true;  // Flag as spam
                $data['reasons']['custom_domain'] = "Blocked domain: $domain"; // Log reason
            }
        }
    }

    // 5. Always return the data array!
    return $data;
}

Example: Advanced Regex on Message Body

PHP

add_filter( 'cf7a_spam_check_chain', 'my_custom_crypto_blocker', 15 );

function my_custom_crypto_blocker( $data ) {
    if ( $data['is_whitelisted'] ) return $data;

    // Check if message contains typical crypto scam keywords
    $pattern = '/(bitcoin|investment|forex|cryptocurrency)/i';
    
    if ( preg_match( $pattern, $data['message'] ) ) {
        $data['spam_score'] += 10;
        $data['is_spam'] = true;
        $data['reasons']['crypto_scam'] = 'Crypto keywords detected';
    }

    return $data;
}

3. How to Remove a Specific Filter

If you need to disable a specific built-in check programmatically (instead of using the plugin settings), you can use remove_filter.

Note: Because the filters are added inside the plugin class instance, you need access to that instance object to remove them.

Assuming the plugin instance is accessible via a global variable or helper function (e.g., $cf7_antispam_plugin->filters), you would do:

PHP

// Example: Removing the DNSBL check programmatically
add_action( 'wp_loaded', 'remove_cf7_dnsbl_check' );

function remove_cf7_dnsbl_check() {
    // Retrieve the class instance (pseudo-code, depends on how you instantiate your plugin)
    global $cf7_antispam_filters_instance; 
    
    if ( $cf7_antispam_filters_instance ) {
        remove_filter( 
            'cf7a_spam_check_chain', 
            array( $cf7_antispam_filters_instance, 'filter_dnsbl' ), 
            10 
        );
    }
}

List of Available Methods (Callbacks)

These are the method names you can target for removal:

• filter_ip_whitelist (Priority 5)
• filter_empty_ip (Priority 10)
• filter_bad_ip
• filter_ip_blacklist_history
• filter_honeyform
• filter_referrer_protocol
• filter_bot_fingerprint
• filter_geoip
• filter_time_submission
• filter_bad_email_strings
• filter_dnsbl
• filter_b8_bayesian (Note: This is hooked to cf7a_check_b8, not the main chain).

4. Modifying the Bayesian (B8) Filter

The Bayesian B8 filter runs separately at the very end of the process. To modify or remove it, target the cf7a_check_b8 hook.

To Disable B8 programmatically:

PHP

remove_filter( 'cf7a_check_b8', array( $instance, 'filter_b8_bayesian' ), 10 );

To Replace B8 with your own logic:

PHP

add_filter( 'cf7a_check_b8', 'my_custom_ai_check', 20 );

function my_custom_ai_check( $data ) {
    // Your custom AI analysis logic here
    return $data;
}