Developer guide: where to start

Hive Mail can be read and extended from outside: HTTP calls, incoming webhooks, PHP actions and filters, registries, shortcodes and WP-CLI. Every route, hook, table and command named in these pages exists in the plugin code.

The map #

You want to	Use	Page
Call Hive Mail from another program	REST API at /wp-json/hivemail/v1: how to sign in	REST API: introduction and authentication
See every resource and the three basic requests	Overview, errors, paging	REST API: the main endpoints
Work with contacts, lists, tags, custom fields, import and export	Route tables and examples	Contacts, lists, tags and custom fields
Work with campaigns, segments, templates, reports, the sending log	Route tables and examples	Campaigns, segments, templates and reports
Work with flows, recipes, forms, shops and visitor reports	Route tables and examples	Flows, recipes, forms and shops
Start a flow from another service, or report bounces	Incoming and bounce webhooks, API keys	Webhooks and API keys
Run PHP when something happens	Action hooks	Hooks: actions
Change a value Hive Mail is about to use	Filter hooks	Hooks: filters
Read the data directly (read only)	The hm_ tables	Database tables
Add a delivery method, a trigger, a settings group or a menu entry	Registries and seams	Extending Hive Mail
Put a form on a page	Shortcode and block	Shortcodes and the signup form block
Run the scheduler from a real cron	wp hivemail	WP-CLI commands
See what Hive Mail connects to	Shops, form plugins, importers, sending services	Integrations overview

Hive Mail has no outgoing webhook per event (a new contact, a sent campaign). To pass an event on, use a PHP hook such as hivemail_contact_created, or the Call a webhook step in a flow (Steps).

How a request is authenticated #

Hive Mail adds no key, token or header of its own. A request acts as a WordPress user, and each route checks one WordPress capability for that user. Two ways to sign in:

• Application password over HTTP Basic (what the API keys card creates). Use this from outside WordPress.
• Login cookie plus the X-WP-Nonce header (nonce action wp_rest). Use this from code running in wp-admin.

Public routes with their own protection: POST /forms/{id}/submit, the bounce webhooks and the incoming flow webhook.

Capability	Area
manage_hivemail	Open the app, /ping, /bootstrap
hivemail_view_audience	Read contacts, lists, tags, fields, segments
hivemail_manage_audience	Change and delete them, import, export, signup forms, suppressions
hivemail_manage_campaigns	Campaigns, templates, the sending log, reports
hivemail_manage_automations	Flows, runs, recipes, connected forms
hivemail_view_intelligence	Visitor reports and journeys
hivemail_manage_settings	Settings, sending checks, tools, API keys, roles
hivemail_use_ai	The assistant

Administrators hold all of them. Give one to a role or a person on Roles & Permissions or with $role->add_cap().

First request #

Create an application password (authentication), then:

curl -u "admin:abcd efgh ijkl mnop qrst uvwx" \
  "https://example.com/wp-json/hivemail/v1/ping"

A JSON answer with "plugin": "hivemail" means you are signed in and allowed to open the app.

First hook #

<?php
add_action( 'hivemail_contact_created', function ( array $contact, array $ctx ) {
    error_log( sprintf( 'New contact %d (%s), status %s', $contact['id'], $contact['email'], $contact['status'] ) );
}, 10, 2 );

It runs for every new contact, whatever the source: the admin, an import, a form or the API.

Constants #

Define these in wp-config.php.

Constant	Effect
DISABLE_WP_CRON	WordPress stops starting its cron on page visits. Hive Mail then needs a real cron (WP-CLI commands).
HMAIL_FORCE_WP_CRON	The minute tick runs as a WP-Cron event instead of through Action Scheduler.
HIVEMAIL_ALLOW_RESET	true switches on Delete all data in Settings > Tools.
HIVEMAIL_MAILGUN_API_KEY, HIVEMAIL_MAILGUN_DOMAIN, HIVEMAIL_MAILGUN_REGION, HIVEMAIL_MAILGUN_SIGNING_KEY, HIVEMAIL_SENDGRID_API_KEY, HIVEMAIL_SENDGRID_WEBHOOK_KEY	Keep a sending key out of the database. The constant always wins over the saved value.

Browser functions #

On the front end, when visitor tracking is on, the tracker defines HiveMail.track( name, props ), HiveMail.consent( true | false ), HiveMail.forget() and HiveMail.banner(). See The consent banner.

Next: REST API: introduction and authentication, Hooks: actions, Extending Hive Mail.