Hooks: filters

A filter lets your code change a value before Hive Mail uses it. Add one with add_filter( $hook, $callback, $priority, $accepted_args ) and always return a value of the same type. Every hook name below exists in the plugin code.

<?php
// Treat a click within 8 seconds of sending as a mail scanner, not a person.
add_filter( 'hivemail_min_seconds_to_click', function ( $seconds ) {
    return 8;
} );

// Add a header to every email just before it is handed to the delivery method.
add_filter(
    'hivemail_rendered_email',
    function ( array $email, array $payload, array $contact, array $ctx ) {
        $email['headers']['X-Campaign-Source'] = 'hive-mail';
        return $email;
    },
    10,
    4
);

The $email array for hivemail_rendered_email has the keys to, subject, html, text, from_name, from_email, reply_to and headers (header name => value).

Email content and sending #

Hook	Arguments	Return	Purpose
hivemail_message_content	null, $message, $contact	array or null	Supply the content of a queued message that has none stored. Array keys: subject, html, text, preheader, from_name, from_email, reply_to
hivemail_merge_values	[], $message, $contact, $payload	array	Add values for merge tags, tag => value
hivemail_merge_tags	$tags	array	Add entries (key => label) to the editors' merge-tag menu
hivemail_rendered_email	$email, $payload, $contact, $ctx	array	Last chance to change a finished email. $ctx has message_id, campaign_id, category, preview
hivemail_confirmation_email	$payload, $contact, $list_id, $url	array	Change the double opt-in confirmation email (subject, preheader, html, text). $url is the confirm address
hivemail_track_transactional	false, $payload, $contact	bool	Return true to track opens and clicks of a transactional email (off by default)
hivemail_channel_per_minute	$default, $channel	int	Messages a minute for a delivery channel (0 = no limit). The default for email is the sending speed
hivemail_smtp_plugin	$found	array or null	Name the SMTP plugin Hive Mail reports (detected, name, slug)
hivemail_free_mail_domains	$domains	array	Domains treated as free mail in the From address check
hivemail_dns_lookup	null, $host, $type	array, false or null	Answer a DNS lookup yourself (hosts without DNS functions). Return a list of records or false
hivemail_soft_bounce_limit	$limit	int	Temporary failures allowed before an address counts as bounced
hivemail_min_seconds_to_click	$seconds	int	Clicks sooner than this after sending are ignored as scanners. Default 3
hivemail_public_page_id	$id, $action	int	The WordPress page used for unsubscribe, preferences or confirm (0 = Hive Mail's own page)
hivemail_cleanup_kept_events	$types	array	Timeline event types that Data cleanup never deletes

Campaigns, templates and flows #

Hook	Arguments	Return	Purpose
hivemail_campaign_utm	$params, $campaign	array	The UTM parameters added to a campaign's links (name => value)
hivemail_campaign_send_chunk	$size	int	How many recipients are queued per step. Default 1000
hivemail_campaign_eligible_where	[ $sql, $values ]	array	Narrow who a campaign may be sent to: append AND ... conditions over the contacts table (alias c) with their prepared values
hivemail_segment_condition_groups	$groups	array	The groups of rule types shown in the segment builder
hivemail_template_starters	$starters	array	Add or change starter designs (id => id, name, description, design)
hivemail_recipes	$recipes	array	Add or change automation recipes (id => recipe)
hivemail_integration_detected	$detected, $key	bool	Force or deny the detection of a plugin by its integration key
hivemail_form_rate_limits	[ per minute, per hour ]	int[]	Signup form sends allowed per visitor. Default 3 and 10
hivemail_form_email_limits	[ per address a day, per network an hour ]	int[]	Confirmation emails the signup forms may send. Default 3 and 20

Shops #

Hook	Arguments	Return	Purpose
hivemail_commerce_shops	$shops	array	The shops the customer index is filled from (key => shop object)
hivemail_commerce_order	$order, $raw_order, $source	array	The normalised order, before Hive Mail uses it. $source: woo or edd
hivemail_commerce_context	$context, $order, $source	array	The data an order trigger puts on a flow run
hivemail_commerce_index_row	$row, $source, $email, $orders	array	A customer's summary row just before it is saved
hivemail_commerce_lookups	$kinds	array	What the rule editor can search (kind => callable)
hivemail_cart_snapshot	$snapshot, $cart	array	What is kept of a WooCommerce cart
hivemail_cart_restore_url	$url, $cart, $contact_id	string	The restore link used by the cart merge tag
hivemail_edd_paid_statuses	$statuses	string[]	The Easy Digital Downloads order statuses that count as a purchase

Visitor tracking (marketing intelligence) #

Hook	Arguments	Return	Purpose
hivemail_tracking_enqueue	$wanted, $settings	bool	Whether the tracker script loads on this page
hivemail_tracking_consent	$ok, $claim	bool	Last word on whether Full mode may record a request. $claim: 0 none, 1 HiveMail.consent(true), 2 WP Consent API
hivemail_tracking_order_page	$is	bool	Whether this page shows a customer's order (the tracker stays off it)
hivemail_tracking_account_paths	$rules	string[]	Addresses kept off the tracker by "Do not track account, password and sign-up pages"
hivemail_tracking_order_staff_caps	$caps	string[]	Capabilities of people who handle other customers' orders
hivemail_tracking_hosts	$hosts	string[]	Hosts the tracker accepts requests from. Default: the home host
hivemail_tracking_cookie_name	$name	string	The visitor cookie's name. Default hm_vid
hivemail_tracking_download_extensions	$extensions	string[]	File types counted as downloads
hivemail_tracking_referrer_rules	$rules	array	Rules that name a referring site (medium => source => host pattern)
hivemail_tracking_banner	$banner, $settings	array	The consent banner's configuration
hivemail_tracking_rate_limit	$limit	int	Requests a minute from one browser. Default 120
hivemail_tracking_network_rate_limit	$limit, $client_limit	int	Requests a minute from one network. Default 5 times the client limit
hivemail_visitor_ip	$ip, $remote	string	The visitor's IP as the tracker sees it, never stored (for example from a CDN header)
hivemail_visitor_kind	$kind, $agent	string	How a request is classified: bot, apple or human
hivemail_consent_tools	$found	array	Add a cookie-consent tool Hive Mail cannot detect (key, label, api, direct)
hivemail_engagement_points	$points, $what, $contact_id	int	Engagement points for open, click, visit, intent or purchase

Report limits #

Hook	Arguments	Return	Purpose
hivemail_intel_currency	$currency	string	The currency used for goal values
hivemail_intel_max_raw_days	$days	int	Most days a report counts from raw hits while totals catch up. Default 10
hivemail_intel_max_keys	$keys	int	Most pages, sources or campaigns kept per day. Default 20,000
hivemail_intel_live_budget_ms	$ms	int	Milliseconds counting today may take before the report reads stored rows. Default 3000

Admin, settings and extension lists #

Hook	Arguments	Return	Purpose
hivemail_capabilities	$capabilities	string[]	The list of Hive Mail capabilities. Administrators always get every one
hivemail_rest_controllers	$classes	string[]	REST controller class names. Add your own class (it must extend HiveMail\Api\BaseController)
hivemail_admin_nav	[]	array	Menu items for the admin app. Each: group, path, label, icon, and optionally cap
hivemail_settings_schema	$schema	array	Add or change Settings groups and fields
hivemail_job_handlers	$handlers	array	Background job type => handler class
hivemail_migration_sources	$sources	array	Register or replace "import from another plugin" sources
hivemail_setup_steps	$steps	array	The steps of the Dashboard's first-steps card (key, label, done, to)
hivemail_cron_guides	$guides	array	The host guides on Settings > Scheduler (host, title, intro, steps)
hivemail_notification_events	$events	array	The alerts on Settings > Notifications
hivemail_notification_content	$content, $event, $data	array	The subject and content of an alert email
hivemail_notifications_active	$active	bool	Whether alerts may be sent from this kind of run
hivemail_scheduler_overdue	$problem, $info	array or null	Change the "scheduled sending is running late" finding
hivemail_role_matrix_capabilities	$catalogue	array	The permissions on the Roles & Permissions screen (label, group, description, requires)
hivemail_pro_auto_update	$allowed	bool	Allow or stop automatic updates of Hive Mail

Registries #

Each extension list is a registry. Hive Mail fires the action hivemail_register_{name} the first time the registry is read (see Hooks: actions), and applies the filter hivemail_{name} to the full list whenever it is read.

{name}	Holds
triggers	What starts a flow
nodes	The steps of a flow
segment_conditions	Segment rule types
integrations	Plugin integrations
channels	Delivery channels
transports	Email transports
blocks	Visual builder blocks
bounce_providers	Bounce webhook adapters

Warning: hivemail_campaign_eligible_where takes SQL. Use %s and %d placeholders and pass values in the second array item; never put request data into the string. Always return the value you were given when you do not change it.

Next: Hooks: actions, Extending Hive Mail.