Actions & Filters

PrimoCRM exposes WordPress actions (events you can react to) and filters (values and registries you can modify). All hooks use the primocrm_ prefix.

Action hooks (events)

React to these with add_action.

Contact lifecycle

Hook	Arguments	Fires when
`primocrm_contact_created`	`$contact_id`	A contact is created
`primocrm_contact_updated`	`$contact_id, $changed_keys`	A contact is updated (`$changed_keys` are the changed field names)
`primocrm_contact_status_changed`	`$contact_id, $new_status, $old_status`	A contact’s status changes
`primocrm_contact_unsubscribed`	`$contact_id`	A contact unsubscribes
`primocrm_contact_tag_added`	`$contact_id, $tag_id`	A tag is applied
`primocrm_contact_tag_removed`	`$contact_id, $tag_id`	A tag is removed
`primocrm_contact_list_added`	`$contact_id, $list_id`	Added to a list
`primocrm_contact_list_removed`	`$contact_id, $list_id`	Removed from a list

Engagement and forms

Hook	Arguments	Fires when
`primocrm_form_submitted`	`$form_id, $entry_id, $contact_id, $data`	A PrimoCRM form is processed
`primocrm_email_opened`	`$contact_id, $campaign_id`	An email open is tracked
`primocrm_email_link_clicked`	`$contact_id, $campaign_id, $url`	A tracked link is clicked

System

Hook	Arguments	Fires when
`primocrm_loaded`	none	Inside REST route registration. A catalog handshake, not a reliable boot hook
`primocrm_pro_downgraded`		A Pro license is lost or lapses
`primocrm_pro_resumed`		A Pro license is restored
`primocrm_ab_evaluate_winners`		The cron tick that evaluates A/B winners

Example:

add_action( 'primocrm_contact_created', function ( $contact_id ) {
    error_log( "New PrimoCRM contact: {$contact_id}" );
} );

add_action( 'primocrm_email_link_clicked', function ( $contact_id, $campaign_id, $url ) {
    // Score the contact, notify a channel, etc.
}, 10, 3 );

Filter hooks (registries)

These collect extendable things. Full recipes are in Extending PrimoCRM.

Filter	Value	Purpose
`primocrm_automation_triggers`	array	Register or modify automation triggers
`primocrm_automation_actions`	array	Register or modify automation actions
`primocrm_condition_options`	array (`fields`, `operators`)	Add condition-builder fields and operators
`primocrm_form_field_types`	array (type to class)	Register custom form field types
`primocrm_migration_sources`	array (key to source)	Register migration source providers
`primocrm_smtp_send`	`$result, $provider, $atts, $settings`	Provide an email sender (how ESP providers hook in)
`primocrm_ab_manager`	object	Provide the A/B test manager implementation

Filter hooks (gating)

Filter	Value	Purpose
`primocrm_free_triggers`	array of keys	Which triggers are free (fail-closed for the rest)
`primocrm_free_actions`	array of keys	Which actions are free
`primocrm_free_limits`	array	Free plan count caps per resource
`primocrm_upgrade_url`	string	The URL the upgrade prompts link to

Filter hooks (behavior and tuning)

Filter	Value	Purpose
`primocrm_send_batch_size`	int	Emails per campaign worker batch
`primocrm_send_rate_per_hour`	int	Campaign send throttle
`primocrm_automation_batch_limit`	int	Rows per automation worker batch
`primocrm_email_body_retention_days`	int	How long rendered email bodies are retained
`primocrm_async_automation_delivery`	bool	Toggle async delivery of automation emails
`primocrm_auto_create_contact_status`	`$status, $source`	Status for contacts auto-created by triggers or user sync
`primocrm_trust_proxy_headers`	bool	Whether to trust proxy headers for the submitter IP on forms

White-label brand seams

Filter	Value	Purpose
`primocrm_brand_name`	string	The brand name shown in admin
`primocrm_brand_menu_icon`	string	The admin menu icon
`primocrm_brand`	array	The brand descriptor localized to the app

JavaScript hooks (wp.hooks)

The admin app exposes two JavaScript filters via wp.hooks so add-ons can inject UI. These return descriptors with mount callbacks, not React elements, because the app and add-ons may run different React versions.

Filter	Purpose
`primocrm.settings.tabs`	Add a tab to the Settings screen
`primocrm.campaigns.rowActions`	Add an action to a campaign row