---
title: "Hooks: filters"
description: Every Hive Mail filter hook grouped by area, with its arguments and return value, for changing emails, limits, tracking and extension lists.
url: "https://hiveplugins.com/docs/hive-mail-hooks-filters/"
updated: "2026-10-28"
category: Hive Mail
---

# 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 `HiveMailApiBaseController`) |
| `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](/docs/hive-mail-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](/docs/hive-mail-hooks-actions/), [Extending Hive Mail](/docs/hive-mail-extending-hive-mail/).