Heads Up Mailer

In-house WordPress newsletter plugin built to replace MailerLite for a single site. Drafts are authored by an AI agent over REST, reviewed and edited in WP admin, then sent to segmented customer groups via an asynchronous WP-Cron queue. Privacy-positive: no open tracking, no click tracking, no link rewriting.

Unsubscribes work via RFC 8058 one-click POST and via a mailto: form that the plugin harvests by polling an IMAP mailbox.

Who this is for

• Site administrators running a low-to-medium volume newsletter on a single WordPress site, who want full control over the send pipeline.
• Newsletter editors who need to review and approve drafts before they go out.
• Hosting providers who want a plugin that uses standard WordPress patterns (wp_mail(), WP-Cron, custom tables) and integrates cleanly with an existing SMTP and IMAP setup.

This plugin is not a hosted service, a multi-site mailer, or a marketing-automation suite.

Features

• Dashboard — a privacy-first overview of the last 30 days: send health with a failure-rate alert banner, active-audience size, a per-group breakdown (active members plus sign-ups and departures), and recent send failures. Every figure comes from data the plugin already holds — no pixels, no link rewriting.
• Drafts pipeline — REST endpoint, sandboxed admin preview, configurable footer + sender identity.
• Optional autonomous send — a trusted agent can trigger a send over REST, gated behind a site-wide master switch and a per-group opt-in flag (both off by default). Fail-safe: a send only proceeds when every target group is opted in, so the general list can never be auto-mailed. Drafting is unaffected; the Sent log flags Auto vs Manual sends.
• Groups REST API — an agent can list, read, create, update and delete groups instead of being handed slugs out of band. Read (hum_read_groups) and write (hum_manage_groups) are separate capabilities; write is Administrator-only by default. Deleting a group that still has members is refused, so memberships are never discarded as a side effect, and the per-group autonomous-send flag is read-only over REST — it stays a human decision.
• Send queue + worker — async drain on a configurable WP-Cron interval, per-recipient optimistic claim against UNIQUE(send_id, subscriber_id), wall-clock budget per tick.
• RFC 8058 unsubscribe — List-Unsubscribe (mailto + https), List-Unsubscribe-Post: One-Click, List-ID, Precedence: bulk. Plain-text alternative auto-generated.
• Public /manage-comms/ page — per-group preferences with resubscribe-via-tick, plus a distinct "Unsubscribe me from everything" button that flips the subscriber to a sticky never_contact status.
• IMAP poller — harvests mailto: unsubscribe replies on a separate cron tick. Failed messages move to an Errors folder; processed messages move to Processed. Master enable switch on the settings tab.
• Sent log — list view of every send with live status counters, per-send recipient drill-down with status filter.
• Subscribers + groups admin — full CRUD, MailerLite-export CSV import (idempotent, refuses to overwrite never-contact rows), row + bulk actions. The subscribers list is paginated and flags which subscribers have a linked WordPress user account.
• Integrations framework — pluggable Integration base class + hum_integrations filter. Built-ins:
  • Contact Form 7 — new [hum_signup group:slug "Label"] form tag, droppable into any CF7 form.
  • WooCommerce — auto-enrol customers into a configurable group once their order is paid (not when the order is created, so declined and abandoned orders enrol nobody); per-group opt-in checkboxes with admin-defined labels (classic checkout).
• In-plugin GitHub auto-updater — releases land via the standard WordPress plugin update flow.
• Encryption — IMAP password encrypted at rest with libsodium (AUTH_KEY-derived key).

Documentation

End-user docs live under the docs/ directory in the GitHub repo (not shipped in the installable zip — clone the repo or browse on GitHub):

• REST API for AI agents — how to POST drafts, read them back, and trigger an autonomous send.
• Autonomous send — admin setup — the two safety gates and how to enable / revoke agent-triggered sending.

Additional admin / editor / host guides are tracked as a follow-up; the in-admin tab descriptions cover day-to-day use.

REST API

AI agents work through the heads-up-mailer/v1 namespace with WordPress application-password auth:

Each capability is granted and revoked independently, so an agent can be given exactly the rights it needs. See the REST API reference for request / response shapes, error codes, and curl examples.

Updates

includes/class-github-updater.php checks the GitHub releases page and surfaces new versions through the standard WordPress "Plugins → Updates" UI. Site owners can pin / disable updates via the hum_updater_enabled filter.

License

GPL v2 or later, matching WordPress core. See the plugin header in heads-up-mailer.php.