Hooks and Filters

WP Outreach provides extensive hooks and filters for developers to customize functionality and integrate with other plugins. This reference covers all available hooks.

Action Hooks

Action hooks allow you to execute custom code when specific events occur.

Subscriber Events

wp_outreach_subscriber_created

Fires when a new subscriber is created.

add_action('wp_outreach_subscriber_created', function($subscriber_id, $data) {
    // $subscriber_id - The new subscriber ID
    // $data - Array of subscriber data (email, first_name, etc.)
    
    // Example: Log new subscriber
    error_log("New subscriber: " . $data['email']);
    
    // Example: Sync with external CRM
    my_crm_sync($data['email'], $data);
}, 10, 2);

wp_outreach_subscriber_confirmed

Fires when a subscriber confirms their email (double opt-in).

add_action('wp_outreach_subscriber_confirmed', function($subscriber_id, $data) {
    // Subscriber has clicked the confirmation link
    // Status is now 'active'
}, 10, 2);

wp_outreach_subscriber_unsubscribed

Fires when a subscriber unsubscribes.

add_action('wp_outreach_subscriber_unsubscribed', function($subscriber_id, $data) {
    // Update external systems
    my_crm_remove_contact($data['email']);
}, 10, 2);

wp_outreach_subscriber_added_to_list

Fires when a subscriber is added to a list.

add_action('wp_outreach_subscriber_added_to_list', function($subscriber_id, $list_id, $data) {
    // Trigger specific actions based on list
    if ($list_id === 5) { // Premium list
        grant_premium_access($subscriber_id);
    }
}, 10, 3);

wp_outreach_subscriber_removed_from_list

Fires when a subscriber is removed from a list.

add_action('wp_outreach_subscriber_removed_from_list', function($subscriber_id, $list_id, $data) {
    // Handle list removal
}, 10, 3);

wp_outreach_tag_added_to_subscriber

Fires when a tag is added to a subscriber.

add_action('wp_outreach_tag_added_to_subscriber', function($subscriber_id, $tag_id, $data) {
    // React to tag changes
}, 10, 3);

wp_outreach_tag_removed_from_subscriber

Fires when a tag is removed from a subscriber.

add_action('wp_outreach_tag_removed_from_subscriber', function($subscriber_id, $tag_id, $data) {
    // Handle tag removal
}, 10, 3);

Email Events

wp_outreach_email_opened

Fires when an email is opened (first open only).

add_action('wp_outreach_email_opened', function($tracking_id, $log_data) {
    // $tracking_id - Unique email identifier
    // $log_data - Array with campaign_id, subscriber_id, etc.
    
    // Track engagement in analytics
    track_email_engagement('open', $log_data);
}, 10, 2);

wp_outreach_email_clicked

Fires when an email link is clicked.

add_action('wp_outreach_email_clicked', function($tracking_id, $link_hash, $data) {
    // $link_hash - MD5 hash of clicked URL
    // $data - Includes original URL
    
    // Track click events
    track_email_engagement('click', $data);
}, 10, 3);

Campaign Events

wp_outreach_campaign_started_sending

Fires when a campaign begins sending.

add_action('wp_outreach_campaign_started_sending', function($campaign_id) {
    // Log or notify that campaign has started
    notify_team("Campaign {$campaign_id} started sending");
});

wp_outreach_campaign_finished_sending

Fires when a campaign completes sending.

add_action('wp_outreach_campaign_finished_sending', function($campaign_id, $stats) {
    // $stats - Array with sent, failed, etc.
    
    // Send completion report
    send_campaign_report($campaign_id, $stats);
}, 10, 2);

Automation Events

wp_outreach_automation_started

Fires when a subscriber enters an automation.

add_action('wp_outreach_automation_started', function($automation_id, $subscriber_id) {
    // Track automation entry
}, 10, 2);

wp_outreach_automation_completed

Fires when a subscriber completes an automation.

add_action('wp_outreach_automation_completed', function($automation_id, $subscriber_id) {
    // Post-automation actions
}, 10, 2);

wp_outreach_automation_failed

Fires when an automation fails for a subscriber.

add_action('wp_outreach_automation_failed', function($automation_id, $subscriber_id, $error) {
    // Handle failures
    error_log("Automation {$automation_id} failed: {$error}");
}, 10, 3);

Filter Hooks

Filters allow you to modify data before it is used.

Email Filters

wp_outreach_email_subject

Modify the email subject before sending.

add_filter('wp_outreach_email_subject', function($subject, $campaign_id, $subscriber_id) {
    // Add prefix
    return "[Newsletter] " . $subject;
}, 10, 3);

wp_outreach_email_content

Modify email content before sending.

add_filter('wp_outreach_email_content', function($content, $campaign_id, $subscriber_id) {
    // Add custom footer
    $content .= '<p>Custom footer content</p>';
    return $content;
}, 10, 3);

wp_outreach_from_name

Modify the sender name.

add_filter('wp_outreach_from_name', function($from_name) {
    return "Support Team";
});

wp_outreach_from_email

Modify the sender email address.

add_filter('wp_outreach_from_email', function($from_email) {
    return "newsletter@yoursite.com";
});

Subscriber Filters

wp_outreach_campaign_recipients

Filter the list of recipients before a campaign sends.

add_filter('wp_outreach_campaign_recipients', function($subscriber_ids, $campaign_id) {
    // Exclude specific subscribers
    $exclude = [123, 456];
    return array_diff($subscriber_ids, $exclude);
}, 10, 2);

wp_outreach_should_send_to_subscriber

Control whether an email should be sent to a specific subscriber.

add_filter('wp_outreach_should_send_to_subscriber', function($should_send, $subscriber_id, $campaign_id) {
    // Custom logic to skip certain subscribers
    if (subscriber_is_inactive($subscriber_id)) {
        return false;
    }
    return $should_send;
}, 10, 3);

wp_outreach_subscriber_data

Filter subscriber data used for template personalization.

add_filter('wp_outreach_subscriber_data', function($data, $subscriber_id) {
    // Add custom fields for merge tags
    $data['membership_level'] = get_user_membership($subscriber_id);
    return $data;
}, 10, 2);

Custom Automation Triggers

Register custom triggers for the automation engine:

add_action('wp_outreach_register_triggers', function($registry) {
    $registry->register([
        'id'          => 'my_plugin_purchase',
        'name'        => __('Product Purchased', 'my-plugin'),
        'description' => __('Triggers when a product is purchased', 'my-plugin'),
        'group'       => 'My Plugin',
        'icon'        => 'shopping-cart',
        'config_fields' => [
            [
                'key'   => 'product_id',
                'label' => 'Product',
                'type'  => 'select',
                'options' => get_products_for_select(),
            ],
        ],
        'matcher' => function($config, $context) {
            // Return true if trigger should fire
            if (empty($config['product_id'])) return true;
            return $config['product_id'] == $context['product_id'];
        },
    ]);
});

// Fire the trigger when purchase occurs
add_action('my_plugin_purchase_complete', function($order_id, $user_id) {
    $subscriber_id = get_subscriber_by_user($user_id);
    if ($subscriber_id) {
        do_action('wp_outreach_trigger', 'my_plugin_purchase', $subscriber_id, [
            'product_id' => get_purchased_product($order_id),
            'order_id' => $order_id,
        ]);
    }
}, 10, 2);

Custom Automation Actions

Register custom actions for automations:

add_action('wp_outreach_register_actions', function($registry) {
    $registry->register([
        'id'          => 'my_plugin_grant_access',
        'name'        => __('Grant Access', 'my-plugin'),
        'description' => __('Grant access to a resource', 'my-plugin'),
        'group'       => 'My Plugin',
        'icon'        => 'unlock',
        'config_fields' => [
            [
                'key'   => 'resource_id',
                'label' => 'Resource',
                'type'  => 'select',
                'options' => get_resources_for_select(),
            ],
        ],
        'executor' => function($config, $subscriber_id, $automation_id, $context) {
            // Execute the action
            $result = grant_resource_access(
                $subscriber_id, 
                $config['resource_id']
            );
            
            // Return true on success, throw exception on failure
            if (!$result) {
                throw new Exception('Failed to grant access');
            }
            return true;
        },
    ]);
});

Generic Trigger Hook

Fire automation triggers from anywhere:

// Basic usage
do_action('wp_outreach_trigger', 'trigger_id', $subscriber_id, $context);

// Example: Fire when user completes profile
add_action('user_profile_complete', function($user_id) {
    $subscriber = get_subscriber_by_user_id($user_id);
    if ($subscriber) {
        do_action('wp_outreach_trigger', 'profile_completed', $subscriber->id, [
            'user_id' => $user_id,
            'profile_data' => get_profile_data($user_id),
        ]);
    }
});

Best Practices

Performance

• Keep hook callbacks lightweight
• Use transients for expensive operations
• Consider async processing for heavy tasks

Error Handling

• Wrap code in try-catch blocks
• Log errors for debugging
• Do not let errors break the email flow

Compatibility

• Check if WP Outreach is active before using hooks
• Use appropriate priorities (default 10)
• Document any hooks you add for other developers

// Check if WP Outreach is active
if (class_exists('WPOutreach\Plugin')) {
    // Safe to add hooks
    add_action('wp_outreach_subscriber_created', 'my_callback');
}