---
title: "Developer guide: where to start"
description: "A map of everything a developer can use in Hive Mail: the REST API, webhooks, hooks, database tables, extension points, shortcodes and WP-CLI."
url: "https://hiveplugins.com/docs/hive-mail-developer-guide/"
updated: "2026-10-28"
category: Hive Mail
---

# 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](/docs/hive-mail-rest-api-authentication/) |
| See every resource and the three basic requests | Overview, errors, paging | [REST API: the main endpoints](/docs/hive-mail-rest-api-reference/) |
| Work with contacts, lists, tags, custom fields, import and export | Route tables and examples | [Contacts, lists, tags and custom fields](/docs/hive-mail-rest-api-contacts-lists-tags-fields/) |
| Work with campaigns, segments, templates, reports, the sending log | Route tables and examples | [Campaigns, segments, templates and reports](/docs/hive-mail-rest-api-campaigns-segments-reports/) |
| Work with flows, recipes, forms, shops and visitor reports | Route tables and examples | [Flows, recipes, forms and shops](/docs/hive-mail-rest-api-automation-and-commerce/) |
| Start a flow from another service, or report bounces | Incoming and bounce webhooks, API keys | [Webhooks and API keys](/docs/hive-mail-webhooks-and-api-keys/) |
| Run PHP when something happens | Action hooks | [Hooks: actions](/docs/hive-mail-hooks-actions/) |
| Change a value Hive Mail is about to use | Filter hooks | [Hooks: filters](/docs/hive-mail-hooks-filters/) |
| Read the data directly (read only) | The `hm_` tables | [Database tables](/docs/hive-mail-database-tables/) |
| Add a delivery method, a trigger, a settings group or a menu entry | Registries and seams | [Extending Hive Mail](/docs/hive-mail-extending-hive-mail/) |
| Put a form on a page | Shortcode and block | [Shortcodes and the signup form block](/docs/hive-mail-shortcodes-and-block/) |
| Run the scheduler from a real cron | `wp hivemail` | [WP-CLI commands](/docs/hive-mail-wp-cli-commands/) |
| See what Hive Mail connects to | Shops, form plugins, importers, sending services | [Integrations overview](/docs/hive-mail-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](/docs/hive-mail-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](/docs/hive-mail-settings-roles-and-permissions/) or with `$role->add_cap()`.

## First request

Create an application password ([authentication](/docs/hive-mail-rest-api-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](/docs/hive-mail-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](/docs/hive-mail-consent-banner-and-privacy-choices/).

Next: [REST API: introduction and authentication](/docs/hive-mail-rest-api-authentication/), [Hooks: actions](/docs/hive-mail-hooks-actions/), [Extending Hive Mail](/docs/hive-mail-extending-hive-mail/).