WordPress Gravity Forms Email Verification with HubSpot Integration

User fills form → Form submits immediately (<1 second)
                        ↓
                  User sees confirmation page
                        ↓
            Background verification starts
                        ↓
    checkboxHQ API calls (3 endpoints):
    1. /verify_disposable/ (1 credit)
    2. /verify_dns/ (2 credits)
    3. /verify_public_provider/ (1 credit)
                        ↓
    Results stored in WordPress database
                        ↓
    HubSpot sync triggered with verification data
    → Contact created/updated with custom properties
    → Lead scoring applied
    → Workflows triggered

// checkboxHQ API Configuration
define('CHECKBOXHQ_API_KEY', 'cbx_your_actual_api_key_here');
define('CHECKBOXHQ_API_BASE_URL', 'https://api.checkboxhq.com');

<?php
/**
 * checkboxHQ Email Verification for Gravity Forms
 *
 * NON-BLOCKING email verification: User gets instant form confirmation,
 * email verification happens in background, results sync to HubSpot
 *
 * This maintains conversion rates while cleaning your email list
 */

// Prevent direct access
if (!defined('ABSPATH')) exit;

/**
 * Verify email using checkboxHQ API (comprehensive check)
 *
 * Combines disposable + DNS checks for complete validation
 * Uses 3 credits total per verification (1 + 2)
 *
 * @param string $email Email address to verify
 * @return array Verification result with all metadata
 */
function checkboxhq_verify_email_complete($email) {
    // Validate email format first (basic check)
    if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
        return [
            'success' => false,
            'is_valid' => false,
            'is_disposable' => false,
            'has_mx_record' => false,
            'has_a_record' => false,
            'is_public_provider' => false,
            'provider' => null,
            'reason' => 'invalid_format',
            'message' => 'Invalid email format'
        ];
    }

    // Get API credentials from wp-config.php
    $api_key = defined('CHECKBOXHQ_API_KEY') ? CHECKBOXHQ_API_KEY : '';
    $api_base = defined('CHECKBOXHQ_API_BASE_URL') ? CHECKBOXHQ_API_BASE_URL : 'https://api.checkboxhq.com';

    // Check if API key is configured
    if (empty($api_key)) {
        error_log('checkboxHQ Error: API key not configured in wp-config.php');
        return [
            'success' => false,
            'reason' => 'api_not_configured',
            'message' => 'Email verification not configured'
        ];
    }

    $results = [
        'success' => true,
        'email' => $email,
        'is_valid' => true, // Default assumption
        'is_disposable' => false,
        'has_mx_record' => false,
        'has_a_record' => false,
        'is_public_provider' => false,
        'provider' => null,
        'mx_records' => [],
        'a_records' => []
    ];

    // Step 1: Check if disposable email (1 credit)
    $disposable_check = checkboxhq_api_call($api_base . '/api/v1/verify_disposable/', $api_key, ['email' => $email]);

    if ($disposable_check && isset($disposable_check['is_disposable'])) {
        $results['is_disposable'] = $disposable_check['is_disposable'];
        $results['is_valid'] = $disposable_check['is_valid_format'];
        $results['provider'] = $disposable_check['provider'];
    }

    // Step 2: Check DNS records (2 credits)
    $dns_check = checkboxhq_api_call($api_base . '/api/v1/verify_dns/', $api_key, ['email' => $email]);

    if ($dns_check && isset($dns_check['has_mx_record'])) {
        $results['has_mx_record'] = $dns_check['has_mx_record'];
        $results['has_a_record'] = $dns_check['has_a_record'];
        $results['mx_records'] = $dns_check['mx_records'] ?? [];
        $results['a_records'] = $dns_check['a_records'] ?? [];

        // Override provider if DNS check provides more info
        if (!empty($dns_check['provider'])) {
            $results['provider'] = $dns_check['provider'];
        }
    }

    // Step 3: Check if public provider (1 credit) - Optional for lead scoring
    $public_check = checkboxhq_api_call($api_base . '/api/v1/verify_public_provider/', $api_key, ['email' => $email]);

    if ($public_check && isset($public_check['is_public_provider'])) {
        $results['is_public_provider'] = $public_check['is_public_provider'];
    }

    // Determine overall validity
    // Email is valid if: has valid format + has MX records + NOT disposable
    $results['is_deliverable'] = $results['is_valid'] && $results['has_mx_record'] && !$results['is_disposable'];

    // Determine reason for invalidity
    if (!$results['is_valid']) {
        $results['reason'] = 'invalid_format';
    } elseif ($results['is_disposable']) {
        $results['reason'] = 'disposable';
    } elseif (!$results['has_mx_record']) {
        $results['reason'] = 'no_mx_records';
    } else {
        $results['reason'] = 'valid';
    }

    return $results;
}

/**
 * Make API call to checkboxHQ endpoint
 *
 * @param string $endpoint Full API endpoint URL
 * @param string $api_key API key for authentication
 * @param array $data Request payload
 * @return array|null Response data or null on error
 */
function checkboxhq_api_call($endpoint, $api_key, $data) {
    $args = [
        'method'      => 'POST',
        'timeout'     => 10,
        'headers'     => [
            'x-api-key'    => $api_key, // Correct header format
            'Content-Type' => 'application/json',
            'User-Agent'   => 'WordPress-GravityForms/' . get_bloginfo('version')
        ],
        'body'        => json_encode($data)
    ];

    $response = wp_remote_post($endpoint, $args);

    // Handle network errors
    if (is_wp_error($response)) {
        error_log('checkboxHQ API Error (' . $endpoint . '): ' . $response->get_error_message());
        return null;
    }

    $status_code = wp_remote_retrieve_response_code($response);
    $response_body = wp_remote_retrieve_body($response);

    // Handle non-200 responses
    if ($status_code !== 200) {
        error_log('checkboxHQ API Error: HTTP ' . $status_code . ' - ' . $response_body);
        return null;
    }

    return json_decode($response_body, true);
}

/**
 * NON-BLOCKING: Verify email AFTER form submission
 *
 * User gets instant confirmation, verification happens in background
 * Results are stored and synced to HubSpot
 *
 * @param array $entry Form entry data
 * @param array $form Form configuration
 */
add_action('gform_after_submission', 'checkboxhq_verify_after_submission', 10, 2);
function checkboxhq_verify_after_submission($entry, $form) {
    // Find email field
    foreach ($form['fields'] as $field) {
        if ($field->type !== 'email') {
            continue;
        }

        $email = rgar($entry, $field->id);

        // Skip empty emails
        if (empty($email)) {
            continue;
        }

        // Perform verification (non-blocking - happens after user sees confirmation)
        $verification = checkboxhq_verify_email_complete($email);

        // Store verification result in entry meta
        gform_update_meta($entry['id'], 'checkboxhq_verification', $verification);
        gform_update_meta($entry['id'], 'checkboxhq_verification_date', current_time('mysql'));

        // Log result
        error_log(sprintf(
            'checkboxHQ Verification - Email: %s, Deliverable: %s, Disposable: %s, Has MX: %s, Reason: %s',
            $email,
            $verification['is_deliverable'] ? 'Yes' : 'No',
            $verification['is_disposable'] ? 'Yes' : 'No',
            $verification['has_mx_record'] ? 'Yes' : 'No',
            $verification['reason'] ?? 'unknown'
        ));

        // Only process first email field
        break;
    }
}

/**
 * Optional: Add email validation note to entry
 *
 * @param array $entry Form entry data
 * @param array $form Form configuration
 */
add_action('gform_after_submission', 'checkboxhq_add_entry_note', 11, 2);
function checkboxhq_add_entry_note($entry, $form) {
    $verification = gform_get_meta($entry['id'], 'checkboxhq_verification');

    if ($verification && isset($verification['reason'])) {
        $note = 'Email Verification: ' . ucfirst($verification['reason']);

        if ($verification['is_disposable']) {
            $note .= ' (Disposable Email - Review Required)';
        } elseif (!$verification['has_mx_record']) {
            $note .= ' (No MX Records - Likely Invalid)';
        } elseif ($verification['is_deliverable']) {
            $note .= ' ✓ (Verified & Deliverable)';
        }

        GFFormsModel::add_note($entry['id'], 0, 'checkboxHQ', $note, 'checkboxhq');
    }
}

/**
 * Add verification data to HubSpot contact properties
 *
 * @param array $entry Gravity Forms entry
 * @param array $form Form configuration
 */
add_filter('gform_hubspot_contact_properties', 'checkboxhq_add_hubspot_properties', 10, 3);
function checkboxhq_add_hubspot_properties($properties, $entry, $form) {
    // Get verification data from entry meta
    $verification = gform_get_meta($entry['id'], 'checkboxhq_verification');

    if ($verification && $verification['success']) {
        // Add custom properties to HubSpot contact
        $properties['email_verification_status'] = $verification['reason'];
        $properties['email_deliverable'] = $verification['is_deliverable'] ? 'true' : 'false';
        $properties['email_verified_date'] = date('Y-m-d');

        // Additional enrichment data
        if (!empty($verification['provider'])) {
            $properties['email_provider'] = $verification['provider'];
        }

        // Flag disposable emails
        if ($verification['is_disposable']) {
            $properties['disposable_email_flag'] = 'true';
        }

        // Flag public providers (Gmail, Yahoo, etc.) for lead scoring
        if (isset($verification['is_public_provider']) && $verification['is_public_provider']) {
            $properties['public_email_provider'] = 'true';
        }

        // MX record status (technical validation)
        $properties['email_has_mx_records'] = $verification['has_mx_record'] ? 'true' : 'false';

        // Optional: Boost lead score for verified emails
        if ($verification['is_deliverable']) {
            if (isset($properties['hs_lead_score'])) {
                $properties['hs_lead_score'] = intval($properties['hs_lead_score']) + 15;
            }

            // Extra points for business emails (non-public providers)
            if (isset($verification['is_public_provider']) && !$verification['is_public_provider']) {
                $properties['hs_lead_score'] = intval($properties['hs_lead_score']) + 5;
            }
        }
    }

    return $properties;
}

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

checkboxHQ Verification - Email: [email protected], Deliverable: Yes, Disposable: No, Has MX: Yes, Reason: valid
checkboxHQ API Error (/api/v1/verify_disposable/): HTTP 401 - Invalid API key

/**
 * Send admin alert if verification API is down
 */
add_action('checkboxhq_api_error', 'checkboxhq_send_admin_alert');
function checkboxhq_send_admin_alert($error_message) {
    $admin_email = get_option('admin_email');
    $subject = '[ALERT] checkboxHQ Email Verification Down';
    $message = "The checkboxHQ email verification API is experiencing issues:\n\n";
    $message .= "Error: " . $error_message . "\n\n";
    $message .= "Forms are currently accepting all submissions (fail-open mode).\n";
    $message .= "Please check your API key and account status at checkboxhq.com\n";

    wp_mail($admin_email, $subject, $message);
}

/**
 * Lightweight verification - DNS check only
 * Uses 2 credits per verification
 */
function checkboxhq_verify_email_lightweight($email) {
    if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
        return ['success' => false, 'reason' => 'invalid_format'];
    }

    $api_key = defined('CHECKBOXHQ_API_KEY') ? CHECKBOXHQ_API_KEY : '';
    $api_base = defined('CHECKBOXHQ_API_BASE_URL') ? CHECKBOXHQ_API_BASE_URL : 'https://api.checkboxhq.com';

    // Only call DNS verification endpoint
    $dns_check = checkboxhq_api_call($api_base . '/api/v1/verify_dns/', $api_key, ['email' => $email]);

    return [
        'success' => true,
        'email' => $email,
        'is_deliverable' => $dns_check['has_mx_record'] ?? false,
        'has_mx_record' => $dns_check['has_mx_record'] ?? false,
        'has_a_record' => $dns_check['has_a_record'] ?? false,
        'provider' => $dns_check['provider'] ?? null,
        'reason' => ($dns_check['has_mx_record'] ?? false) ? 'valid' : 'no_mx_records'
    ];
}

// Replace in checkboxhq_verify_after_submission function:
$verification = checkboxhq_verify_email_lightweight($email);

/**
 * Only verify high-priority forms (e.g., demo requests, enterprise inquiries)
 */
add_action('gform_after_submission', 'checkboxhq_selective_verification', 10, 2);
function checkboxhq_selective_verification($entry, $form) {
    // Only verify these form IDs
    $priority_form_ids = [1, 5, 12]; // Replace with your form IDs

    if (!in_array($form['id'], $priority_form_ids)) {
        return; // Skip verification for other forms
    }

    // Proceed with verification...
    foreach ($form['fields'] as $field) {
        if ($field->type === 'email') {
            $email = rgar($entry, $field->id);
            $verification = checkboxhq_verify_email_complete($email);
            gform_update_meta($entry['id'], 'checkboxhq_verification', $verification);
            break;
        }
    }
}

/**
 * Cache verification results for 24 hours
 */
function checkboxhq_verify_email_cached($email) {
    $cache_key = 'checkboxhq_' . md5(strtolower(trim($email)));
    $cached = get_transient($cache_key);

    if ($cached !== false) {
        error_log('checkboxHQ: Using cached result for ' . $email);
        return $cached;
    }

    $result = checkboxhq_verify_email_complete($email);

    // Cache for 24 hours (DAY_IN_SECONDS = 86400)
    set_transient($cache_key, $result, DAY_IN_SECONDS);

    return $result;
}

// Update checkboxhq_verify_after_submission to use cached version:
$verification = checkboxhq_verify_email_cached($email);

/**
 * Whitelist trusted email domains
 */
function checkboxhq_is_whitelisted_domain($email) {
    $whitelisted_domains = [
        'youragency.com',
        'trustedpartner.com',
        'enterpriseclient.com'
    ];

    $domain = substr(strrchr($email, "@"), 1);
    return in_array(strtolower($domain), $whitelisted_domains);
}

// Add to checkboxhq_verify_after_submission:
if (checkboxhq_is_whitelisted_domain($email)) {
    gform_update_meta($entry['id'], 'checkboxhq_verification', [
        'success' => true,
        'is_deliverable' => true,
        'reason' => 'whitelisted',
        'provider' => 'trusted_domain'
    ]);
    return; // Skip API call
}

/**
 * Queue entries for batch verification
 */
add_action('gform_after_submission', 'checkboxhq_queue_for_batch', 10, 2);
function checkboxhq_queue_for_batch($entry, $form) {
    foreach ($form['fields'] as $field) {
        if ($field->type === 'email') {
            $email = rgar($entry, $field->id);

            // Add to verification queue
            $queue = get_option('checkboxhq_verification_queue', []);
            $queue[] = [
                'entry_id' => $entry['id'],
                'email' => $email,
                'timestamp' => time()
            ];
            update_option('checkboxhq_verification_queue', $queue);

            break;
        }
    }
}

/**
 * Process verification queue every 5 minutes
 */
add_action('checkboxhq_process_batch', 'checkboxhq_batch_verify');
function checkboxhq_batch_verify() {
    $queue = get_option('checkboxhq_verification_queue', []);

    if (empty($queue)) {
        return;
    }

    // Process up to 50 at a time
    $batch = array_splice($queue, 0, 50);

    foreach ($batch as $item) {
        $verification = checkboxhq_verify_email_complete($item['email']);
        gform_update_meta($item['entry_id'], 'checkboxhq_verification', $verification);
    }

    // Update queue
    update_option('checkboxhq_verification_queue', $queue);
}

// Schedule cron job (add to theme activation)
if (!wp_next_scheduled('checkboxhq_process_batch')) {
    wp_schedule_event(time(), 'five_minutes', 'checkboxhq_process_batch');
}

// Add custom cron interval
add_filter('cron_schedules', 'checkboxhq_add_cron_interval');
function checkboxhq_add_cron_interval($schedules) {
    $schedules['five_minutes'] = [
        'interval' => 300,
        'display'  => 'Every 5 Minutes'
    ];
    return $schedules;
}

/**
 * Add colored flags to Gravity Forms entries list
 */
add_filter('gform_entries_field_value', 'checkboxhq_flag_suspicious_entries', 10, 4);
function checkboxhq_flag_suspicious_entries($value, $form_id, $field_id, $entry) {
    // Only modify email field display
    $form = GFAPI::get_form($form_id);
    $field = GFFormsModel::get_field($form, $field_id);

    if ($field->type !== 'email') {
        return $value;
    }

    $verification = gform_get_meta($entry['id'], 'checkboxhq_verification');

    if (!$verification) {
        return $value . ' <span style="color: orange;">⏳ Verifying...</span>';
    }

    if ($verification['is_disposable']) {
        return $value . ' <span style="color: red; font-weight: bold;">⚠️ DISPOSABLE</span>';
    }

    if (!$verification['has_mx_record']) {
        return $value . ' <span style="color: red;">❌ Invalid</span>';
    }

    if ($verification['is_deliverable']) {
        return $value . ' <span style="color: green;">✓ Verified</span>';
    }

    return $value;
}

define('CHECKBOXHQ_API_KEY', 'cbx_actual_key_here');

// Add to functions.php temporarily
add_action('init', function() {
    error_log('Next checkboxhq_process_batch: ' . wp_next_scheduled('checkboxhq_process_batch'));
});

// In WordPress admin, go to Tools → WP-Cron
// Or trigger manually in functions.php:
do_action('checkboxhq_process_batch');

// In wp-config.php:
set_time_limit(300); // 5 minutes

// See Advanced Configurations → Option 1

// See Advanced Configurations → Option 3

// Install Gravity Forms reCAPTCHA add-on

// Check your dashboard at checkboxhq.com/billing

/**
 * Rate limit verification requests (max 100/hour per IP)
 */
function checkboxhq_check_rate_limit() {
    $ip = $_SERVER['REMOTE_ADDR'];
    $cache_key = 'checkboxhq_rate_' . md5($ip);
    $requests = get_transient($cache_key) ?: 0;

    if ($requests >= 100) {
        return false; // Rate limit exceeded
    }

    set_transient($cache_key, $requests + 1, 3600); // 1 hour
    return true;
}

// Add to checkboxhq_verify_email function:
if (!checkboxhq_check_rate_limit()) {
    return [
        'valid' => false,
        'reason' => 'rate_limit',
        'message' => 'Too many verification attempts. Please try again later.'
    ];
}

$email = sanitize_email($email_value);
$email = strtolower(trim($email));

/**
 * Auto-delete verification data after 30 days
 */
add_action('gform_delete_entry', 'checkboxhq_cleanup_verification_data');
function checkboxhq_cleanup_verification_data($entry_id) {
    global $wpdb;
    $wpdb->delete(
        $wpdb->prefix . 'gf_entry_meta',
        ['entry_id' => $entry_id, 'meta_key' => 'checkboxhq_verification_%'],
        ['%d', '%s']
    );
}

/**
 * Cache verification results for 24 hours
 */
function checkboxhq_verify_email_cached($email) {
    $cache_key = 'checkboxhq_verify_' . md5(strtolower($email));
    $cached = get_transient($cache_key);

    if ($cached !== false) {
        return $cached;
    }

    $result = checkboxhq_verify_email($email);
    set_transient($cache_key, $result, DAY_IN_SECONDS);

    return $result;
}

/**
 * Queue verification for background processing
 */
add_action('gform_after_submission', 'checkboxhq_queue_verification', 10, 2);
function checkboxhq_queue_verification($entry, $form) {
    as_enqueue_async_action('checkboxhq_process_verification', [
        'entry_id' => $entry['id'],
        'form_id' => $form['id']
    ]);
}

add_action('checkboxhq_process_verification', 'checkboxhq_background_verify', 10, 2);
function checkboxhq_background_verify($entry_id, $form_id) {
    $entry = GFAPI::get_entry($entry_id);
    $form = GFAPI::get_form($form_id);

    // Verify email and update HubSpot
    // (code similar to synchronous version)
}

/**
 * Batch HubSpot contact updates (run hourly)
 */
add_action('checkboxhq_batch_hubspot_sync', 'checkboxhq_sync_verified_contacts');
function checkboxhq_sync_verified_contacts() {
    // Get all entries from last hour with verified emails
    // Update HubSpot in batches of 100
    // (implementation requires HubSpot PHP SDK)
}

/**
 * Add checkboxHQ stats to WordPress dashboard
 */
add_action('wp_dashboard_setup', 'checkboxhq_add_dashboard_widget');
function checkboxhq_add_dashboard_widget() {
    wp_add_dashboard_widget(
        'checkboxhq_stats',
        'checkboxHQ Email Verification Stats',
        'checkboxhq_dashboard_widget_display'
    );
}

function checkboxhq_dashboard_widget_display() {
    global $wpdb;

    // Query last 30 days of form submissions
    $stats = $wpdb->get_results("
        SELECT
            COUNT(*) as total,
            SUM(CASE WHEN meta_value LIKE '%valid\":true%' THEN 1 ELSE 0 END) as verified,
            SUM(CASE WHEN meta_value LIKE '%disposable\":true%' THEN 1 ELSE 0 END) as disposable
        FROM {$wpdb->prefix}gf_entry_meta
        WHERE meta_key LIKE 'checkboxhq_verification_%'
        AND entry_id IN (
            SELECT id FROM {$wpdb->prefix}gf_entry
            WHERE date_created >= DATE_SUB(NOW(), INTERVAL 30 DAY)
        )
    ");

    echo '<p><strong>Last 30 Days:</strong></p>';
    echo '<ul>';
    echo '<li>Total Verified: ' . $stats[0]->verified . '</li>';
    echo '<li>Blocked Disposable: ' . $stats[0]->disposable . '</li>';
    echo '<li>Success Rate: ' . round(($stats[0]->verified / $stats[0]->total) * 100, 1) . '%</li>';
    echo '</ul>';
}

// OLD: ZeroBounce
$response = wp_remote_get("https://api.zerobounce.net/v2/validate?api_key={$key}&email={$email}");

// NEW: checkboxHQ
$response = wp_remote_post('https://api.checkboxhq.com/v1/verify', [
    'headers' => ['Authorization' => 'Bearer ' . $api_key],
    'body' => json_encode(['email' => $email])
]);

// NeverBounce response format
$result = $data['result']; // 'valid', 'invalid', 'disposable', 'catchall', 'unknown'

// checkboxHQ equivalent
$is_valid = $data['deliverable'] === true;
$is_disposable = $data['disposable'] === true;