Subscriber Notifications Plugin

Subscriber Notifications lets visitors subscribe by post type, taxonomy, or individual posts. Configure Content Types from any public post type and taxonomy, collect preferences via a theme-native form or on-page subscribe widgets, and send one-time or recurring notifications on daily, weekly, or monthly schedules. Emails are personalized with shortcodes and content feeds, fully brandable, and delivered through WordPress mail—with logs, analytics, and CSV tools for managing your list.

GitHub repository description

Paste this into GitHub Settings → General → Description:

WordPress subscriptions by topic or individual page: global form + on-page widget, scheduled topic notifications, immediate on-page update emails, branded templates, and delivery analytics.

Features

Core Functionality

• Subscriber Registration Form - Frontend form with CAPTCHA protection; guests enter name and email, logged-in users use readonly account fields
• WordPress account linking - Logged-in signups store the subscriber's WordPress user_id for admin visibility and reliable identity on resubscribe
• Immediate Subscription - Subscribers are activated immediately upon form submission
• On-page subscribe widget - Per-post subscriptions via [subscriber_notifications_post_subscribe] on singular templates, with visibility rules in Content Types
• Notification Management - WYSIWYG editor for creating notifications
• Email Delivery - Sends through WordPress wp_mail() (use your SMTP or mail plugin); open/click logging preserved
• Smart Scheduling System - Daily, weekly and monthly email scheduling
• Recurring Notifications - Send notifications repeatedly based on frequency schedule
• Analytics Tracking - Email open/click tracking
• CSV Import/Export - Bulk subscriber management; exports include user_id when linked to a WordPress account
• Rate Limiting - Prevents email flooding for frequent notifications

Admin Features

• Dashboard - Setup & health checklist (Content Types, frontend pages, subscribers, cron; optional reCAPTCHA and pending notifications), subscriber and notification summaries, time-windowed delivery stats, upcoming sends, send queue, recent activity, schedule and Content Types summaries, inline test email, and quick links
• Notification Management - View, edit, cancel, resend, and delete notifications
• Recurring Notification Support - Create and manage notifications that send repeatedly
• Subscriber Management - View subscribers (including WP User link and ID), search, activate/deactivate, delete, and CSV import/export
• Notification Creation - Rich text editor with shortcodes and send preview email
• Email Logs - Track all email activity with open/click counts and log type (topic notification, welcome, on-page subscription, on-page update, preferences update, test, etc.)
• Content Types - Enable public post types and taxonomies, term display rules (all / children of / include / exclude), form labels, and on-page subscriptions to individual posts per type
• Settings - Scheduling, CAPTCHA, email templates, Email Design branding, and general options (test email, hide empty terms on form, delete on uninstall)
• Test email - Send a test message to verify mail delivery (wp_mail())

Installation

1. Upload the plugin files to /wp-content/plugins/subscriber-notifications/
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Configure settings in the 'Notifications' admin menu
4. Add the subscription form to your pages using [subscriber_notifications_form]
5. Add [subscriber_notifications_post_subscribe] to singular block templates for post types where Allow on-page subscriptions is enabled, then configure On-page subscribe widget — where to show it under Notifications → Content Types

Requirements

• WordPress 5.0+
• PHP 7.4+
• MySQL 5.6+ (or MariaDB equivalent)
• Google reCAPTCHA v2 account (optional)
• Tested up to WordPress 6.8

Subscriber Notifications is now content-type agnostic. Configure which public post types and taxonomies subscribers can choose from under Notifications > Content Types before publishing the subscription form. Any post type plugin (including The Events Calendar) is supported out of the box — there is no longer a hard dependency on a specific plugin.

Terminology

The plugin uses two subscription paths with distinct user-facing labels:

Concept	User-facing label	How it works
Subscribe form + scheduled sends	Topic notifications	Subscribers choose post types and taxonomy terms on the global form. Scheduled notification emails include personalized content via [content_feed]. Posts are marked Include in topic notifications in the editor.
On-page widget + immediate sends	On-page subscriptions / On-page updates	Subscribers follow a specific post via [subscriber_notifications_post_subscribe]. Confirmation and update emails use dedicated templates under Settings → Email Templates → On-page subscriptions. Admins can check Send on-page update email now when saving a post.

Internal slugs (notification, item_subscribe, item_update) and option keys are unchanged for compatibility.

How it works

1. Content Types — You enable post types and taxonomies; that drives the subscribe form, notification target checklists, CSV import/export columns, matching rules, and on-page subscribe widget visibility.
2. Two subscription paths — Visitors subscribe globally via [subscriber_notifications_form] (topics by post type and taxonomy) or to a specific post via [subscriber_notifications_post_subscribe] when that post type allows on-page subscriptions.
3. Subscriber choices — Each person’s selected terms, on-page subscriptions, and delivery frequency are saved when they subscribe or update preferences. Each notification stores which terms that send is about.
4. Who gets an email — Active subscribers are matched by frequency (daily, weekly, or monthly), then filtered to those who share at least one targeted term with the notification. On-page update emails go only to subscribers of that specific post.
5. What they see — Email content uses shortcodes. [content_feed] builds a personalized list of posts per recipient. Global header, footer, and styling come from Email Design settings.
6. Delivery — Scheduled topic notifications and immediate on-page update sends go through WordPress (use SMTP or a mail plugin on your host if needed). Opens and clicks are logged automatically for every send.

Posts can be marked Include in topic notifications in the editor (sets feed meta for scheduled sends). Send on-page update email now sends an immediate on-page update to on-page subscribers when saved.

On-page subscriptions

Visitors can subscribe to a specific post via [subscriber_notifications_post_subscribe] on singular block templates — independent of the global taxonomy subscribe form. Under Notifications → Content Types, enable Allow on-page subscriptions for the post type, set Taxonomies & term rules, then choose On-page subscribe widget — where to show it: By content rules (taxonomy OR logic with optional Except on these posts) or Only specific posts I choose. On-page confirmation and update emails use dedicated templates under Settings → Email Templates → On-page subscriptions. Subscribers manage on-page subscriptions on the preferences page under On-page subscriptions.

Shortcodes

In-admin reference: Notifications → Settings → Shortcodes has the same reference plus an auto-generated panel listing the post type and taxonomy slugs configured on this site. Administrators should use that tab; this section is a developer-focused summary.

Use in notification subject and body, welcome/preference emails, and global header/footer (Email Design).

Shortcode	Use
[subscriber_name]	Subscriber name
[subscriber_email]	Subscriber email
[delivery_frequency]	Daily / weekly / monthly label
[selected_subscriptions]	Formatted subscription summary (HTML in body; format="plain" for subjects). Default shows Topic notifications and On-page subscriptions. Use sections="topics" or sections="items" to limit
[selected_terms taxonomy="…"]	Names of the subscriber's selected terms in one taxonomy. Optional post_type="…" (omit to aggregate across post types) and separator="…" (default ,)
[site_title]	Site name
[manage_preferences_link]	Clickable HTML link to the subscriber's preferences page. Default link text Manage Preferences; override with text="…"
[subscriber_notifications_form]	Public subscribe form (title="…" optional)
[subscriber_notifications_preferences]	Public manage-preferences form (title="…" optional). Requires Preferences page in Settings → General
[subscriber_notifications_post_subscribe]	On-page widget to subscribe to the current post (singular templates). Requires Allow on-page subscriptions for that post type. Visibility is configured under Notifications → Content Types; optional plain-text copy overrides — see Settings → Shortcodes

[subscriber_notifications_post_subscribe] (single-post widget)

Place on block templates for a post type (e.g. all Pages). The widget uses the current post; it is never shown on the configured subscribe or preferences pages.

Content eligibility is configured per post type under Notifications → Content Types. Set Taxonomies & term rules first, then On-page subscribe widget — where to show it. Choose By content rules to match taxonomy term rules with optional Except on these posts, or Only specific posts I choose for an explicit pick list that ignores taxonomy rules.

Attribute	Notes
heading, description, button	Plain-text overrides for the subscribe form
heading_subscribed, description_subscribed, button_manage	Plain-text overrides for the subscribed state

Leave copy attributes empty for plugin defaults (post title and singular content type label, e.g. "Post").

[content_feed] (personalized post lists)

Only includes published posts flagged for the feed, notified within the duration window (1day, 1week, 1month).

Attribute	Notes
post_type	Required. Must be enabled in Content Types.
taxonomy	Optional. One taxonomy — filter on that dimension only. Omit — match the subscriber in any form taxonomy for that post type (OR).
duration	Default 1month.
limit	Default 10.
format	list (default) = bulleted title links; summary = linked title + short excerpt. Modified posts append (updated on …) to link text — using the on-page update stamp when set, otherwise the post’s last modified date.
terms	Optional comma-separated term slugs; requires taxonomy. Alias: term (same value). Scopes the feed block; each subscriber sees only slugs they subscribed to (intersection). Unknown slugs skipped.

Slugs: Use the exact slug from WordPress for each taxonomy and term (Posts → Categories / your taxonomy; edit a term to see its slug). Taxonomy slugs and term slugs may use different punctuation (e.g. tribe_events_cat vs family-events) — always copy from WordPress, do not guess.

Personalization: Without terms, the feed uses the subscriber’s selections and the notification’s targets together. With terms, the feed uses only the listed slugs that the subscriber also selected (notification targets still control who receives the email). Create one notification with broad targets; each subscriber sees only matching posts.

Examples:

[content_feed post_type="post" taxonomy="category" duration="1week" format="list"]
[content_feed post_type="tribe_events" taxonomy="tribe_events_cat" terms="family-events,concerts,kids-events" duration="1week" format="list"]
[content_feed post_type="project" duration="1day" limit="10" format="summary"]

Community events example: Notification targets Family Events, Concerts, and Kids Events (who receives the email). Shortcode terms="family-events,concerts,kids-events" scopes the feed. A subscriber who chose Family Events and Concerts only sees those two — not Kids Events.

Multi-taxonomy example: A subscriber excludes status “On Hold” but includes type “Commerce”. [content_feed post_type="project" duration="1day"] can still show a project tagged On Hold + Commerce, because Commerce matches.

Configuration

Email Delivery Setup

1. WordPress mail - All plugin emails go through wp_mail(). Configure SMTP or a mail plugin if your host does not send mail reliably.
2. Test - In Notifications > Settings > General, enter a test address and use Send Test Email to verify delivery.

Email Scheduling

1. Daily Emails - Set time for daily email delivery (e.g., "9:00 AM")
2. Weekly Emails - Set day of week and time (e.g., "Tuesday at 2:00 PM")
3. Monthly Emails - Set day of month and time (e.g., "15th at 2:00 PM")
4. Edge Case Handling - Monthly day 31st automatically adjusts for shorter months
5. Cron Scheduling - Uses WordPress cron with "every_minute" schedule for precise timing

CAPTCHA Setup

1. Create a Google reCAPTCHA v2 site (the "I'm not a robot" checkbox version)
2. Enter your site key and secret key in Notifications > Settings > Security
3. The CAPTCHA checkbox will appear on the subscription form

Content Types

1. Go to Notifications > Content Types
2. Enable one or more public post types and set a display label for each
3. For each post type, enable taxonomies that should appear on the subscription form and choose how terms are listed:
   • All — every term in the taxonomy
   • Children of — terms under a parent (hierarchical taxonomies only)
   • Include — only selected term IDs
   • Exclude — all terms except selected IDs
4. Save via options.php (Settings API). The public form will not render until at least one post type and one taxonomy are enabled.

General Settings

Under Notifications > Settings > General:

• Test Email Address — address used by Send Test Email (wp_mail())
• Frontend pages — select the WordPress pages that contain the subscribe and preferences shortcodes; both are required for a complete setup (see Frontend pages setup)
• Hide Empty Terms on Subscription Form (default on) — on the public subscribe and preferences forms, hide terms that have zero published posts for the configured post type (e.g. empty Uncategorized). Admin notification targets, Content Types configuration, and CSV import reference lists always show every configured term. Uncheck to show all configured terms on the public form regardless of post count.

Data Settings

Under Notifications > Settings > Data:

• Email logs — purge log entries older than 30 / 90 / 180 / 365 days (with match counts and confirmation)
• Delete Data on Uninstall — when checked, uninstall removes subscribers, logs, queues, all plugin options, post meta (feed/item flags), and admin screen preferences; shortcodes in page content are intentionally left as plain text

Email Templates

• Customize welcome email subject and content
• Welcome emails are sent immediately after subscription
• Customize welcome back email for reactivated subscribers
• Customize preferences update confirmation email

Usage

Frontend pages setup

1. Create a Subscribe page and add [subscriber_notifications_form].
2. Create a Notification Preferences page and add [subscriber_notifications_preferences].
3. Go to Notifications > Settings > General > Frontend pages and select both pages. Both are required for a complete setup (subscribe links, email manage links, and on-site preference management).

Email manage URLs use {preferences_page_permalink}/?token={management_token} only.

Frontend Form

Add the subscription form to your subscribe page:

[subscriber_notifications_form]

Add the preferences form to your preferences page:

[subscriber_notifications_preferences]

Optional parameters:

• title="Custom Title" - Custom form title

Form layout and behavior:

• Collapsible sections — one block per enabled post type; checklists per enabled taxonomy
• Select all — per-taxonomy control with indeterminate state when partially selected
• Theme-native markup — minimal plugin CSS; the active theme styles most of the form
• Empty terms — by default, terms with no published posts for that post type are hidden on the public form (see Hide Empty Terms on Subscription Form under General settings)
• Validation — at least one term must be selected across all sections; frequency is required

Guest vs logged-in behavior

Both forms share the same term/frequency UI (including hide-empty behavior). Contact fields, page access, and what visitors see depend on whether they are logged in and whether a subscriber row already exists.

Subscribe form ([subscriber_notifications_form])

Visitor	What they see
Guest	Full form — editable name and email, plus term/frequency selections
Logged in, no subscription	Form with name and email read-only from the WordPress profile (first_name, last_name, user_email); submitting creates a new subscriber row and links user_id
Logged in, active subscriber	Already Subscribed message with a link to the preferences page (no form)
Logged in, inactive subscriber	Form prefilled with saved preferences and a reactivation notice; submit reactivates the subscription

Preferences form ([subscriber_notifications_preferences])

Visitor	What they see
Guest with valid email token (?token=…)	Full preferences form; name editable, email read-only from the subscriber record
Guest without token	Prompt to use the link from their email, plus a log-in link
Guest with invalid/expired token	Invalid Link message
Logged in, linked or email-matched subscription	Full form without a token; name and email read-only from the WordPress profile when user_id is set on the row
Logged in, no subscription	Not Subscribed empty state with a link to the subscribe page
Active subscriber	Update Preferences button and Unsubscribe section
Inactive subscriber	Red You are currently unsubscribed notice, Reactivate Subscription button, Unsubscribe section hidden

Account linking

• The subscriber row stores user_id when someone subscribes while logged in.
• Existing rows are matched by user_id first, then by email for legacy guest signups.
• Email match auto-links user_id on subscribe or preferences page visit.
• On save, linked accounts always use the WordPress profile for name and email; POSTed contact fields are ignored.

Inactive and unsubscribe flows (guests and logged-in users)

• Unsubscribe — AJAX on the preferences page; stays on the page with a green confirmation (?unsubscribed=1).
• Reactivate — saving preferences while inactive sets status back to active, sends the welcome-back email, and redirects with a green Welcome back! confirmation (?reactivated=1).
• Stale ?unsubscribed=1 in the URL is ignored once the subscriber is active again.

Other

• CAPTCHA — required for both guests and logged-in users when enabled.

Managing Notifications

1. View All Notifications - Go to Notifications > Notifications
2. Search & Filter - Find specific notifications by title, content, or status
3. Notification Actions:
   • View - Complete email preview with subject, content, footer, and styling
   • Edit - Edit any notification (title, content, target terms, frequency)
   • Cancel - Cancel pending notifications
   • Resend - Resend sent notifications
   • Delete - Permanently delete notifications
4. Status Tracking - See pending, sent, and cancelled notifications
5. Content Reuse - Edit sent notifications to reuse content for new notifications

Creating Notifications

1. Go to Notifications > Create Notification
2. Enter title, email subject, and content using the WYSIWYG editor
3. Select target terms and frequency (same Content Types as the public form; admin lists include empty terms)
4. Choose notification type:
   • One-time Notification: Sent once based on subscriber frequency preferences
   • Recurring Notification: Sent repeatedly based on frequency schedule
5. Notifications are sent based on subscriber frequency preferences:
   • Daily - Sent on configured daily schedule
   • Weekly - Sent on configured weekly schedule
   • Monthly - Sent on configured monthly schedule
6. Use shortcodes for dynamic content in both subject and body
7. Global footer automatically added to all notifications
8. Use Send Preview Email (below the form) to send a test message to your inbox — uses current unsaved subject, content, and target terms, full branding, and shortcode processing
9. Preview emails include subject, content, global header/footer, and custom CSS styling (logged in Email Logs as Test)

Recurring Notifications

What are Recurring Notifications?

Recurring notifications are sent repeatedly based on your frequency schedule settings. Unlike one-time notifications that are sent once, recurring notifications continue to send at regular intervals.

How Recurring Notifications Work:

1. Create Recurring Notification: Check "Recurring Notification" when creating a notification
2. Automatic Scheduling: The system calculates the next send date based on your settings
3. Repeated Sending: After each send, the system calculates the next occurrence
4. Settings Integration: Changes to send day/time automatically update all recurring notifications
5. Status Tracking: View send count and next send date in the notifications list

Recurring vs One-time Notifications:

• One-time: Sent once when the scheduled time arrives
• Recurring: Sent repeatedly at the scheduled intervals
• Status: One-time notifications become "sent" after delivery; recurring notifications stay "pending"
• Management: Recurring notifications show send count and next send date

Settings Integration:

• Dynamic Updates: When you change send day/time in Settings, all recurring notifications update automatically
• Consistent Schedule: All recurring notifications follow the same schedule
• Flexible Timing: Change when notifications are sent without recreating them

Use Cases:

• Weekly Newsletters: Send weekly updates that continue indefinitely
• Monthly Reports: Send monthly reports that repeat each month
• Daily topic notifications: Send daily summaries that continue daily
• Regular Updates: Any notification that should repeat at regular intervals

Managing Large Subscriber Bases (Thousands of Subscribers)

Universal Notification Strategy:

For thousands of subscribers, create notifications that target broad term sets but use personalized shortcodes:

Title: Weekly City Updates
Subject: Weekly Updates for [subscriber_name]
Content:
Hello [subscriber_name],

Here are this week's updates based on your interests:

[content_feed post_type="post" taxonomy="category" duration="1week"]
[content_feed post_type="project" duration="1week"]
[content_feed post_type="tribe_events" taxonomy="tribe_events_cat" duration="1week"]

Your topic subscriptions: [selected_subscriptions sections="topics"]
Delivery frequency: [delivery_frequency]

[manage_preferences_link]

How It Works:

• Target All Terms: Select all relevant terms when creating the notification
• Personalized Content: Each subscriber automatically receives only content from their selected terms
• Efficient Management: One notification reaches everyone with personalized content
• No Irrelevant Content: Subscribers never see content they didn't subscribe to

Benefits:

• Scalable: Works perfectly for thousands of subscribers
• Personalized: Each email is customized to subscriber interests
• Efficient: No need to create individual notifications for each subscriber
• Better Engagement: Relevant content reduces unsubscribe rates

Email Design (Settings tab)

1. Go to Notifications > Settings and open the Email Design tab
2. Header & Footer — global header logo (JPG, PNG, GIF; max 700×200px, 200KB), header content (WYSIWYG), and footer content (WYSIWYG). Header/footer are added to every notification email. Default footer: [site_title] | [manage_preferences_link] if empty
3. Brand Colors — body text, link, link hover (a:hover in clients that support it), outer background, content card background, footer background, footer text. CTAs use text links (e.g. [manage_preferences_link]), not button styles
4. Typography — body font and heading font chosen from email-safe presets (with optional custom stack); live preview on the settings screen
5. Advanced — custom CSS appended after generated branding CSS for fine-tuning
6. Shortcodes work in header/footer content: [site_title], [manage_preferences_link], [subscriber_name], etc.

Preview Functionality

Two preview paths are available in the admin:

1. Send Preview Email (Create / Edit notification) — Enter an address and click Send Preview Email below the form. Sends a real email via wp_mail() using the current subject, content, and Target Content selections (saved or unsaved), global header/footer, brand styling, and server-side shortcode processing. Logged in Email Logs as type Test. Uses a sample subscriber (Preview User, weekly frequency, empty preferences), so personalized shortcodes such as [manage_preferences_link] show placeholders; [content_feed] resolves from the form’s target terms (same as the modal preview).
2. Modal preview (Notifications list) — Click View on a saved notification to open an in-browser preview. Loads stored notification data, processes shortcodes with sample data (John Doe), applies the same email wrapper/CSS as production sends, and can resolve [content_feed] from the notification’s target terms (even though the sample subscriber has no preferences).
3. Email Design typography preview (Settings → Email Design) — Font preset dropdowns show a live browser preview of body/heading stacks; this is settings-only and does not preview notification content.

Preview emails are not sent to subscribers. They approximate production output but do not fully simulate a real subscriber’s term selections or working manage-preferences links.

Managing Subscribers

1. View all subscribers in Notifications > Subscribers
2. Filter by status; search by name, email, or a numeric WordPress user ID
3. WP User column — login linked to the user profile when user_id is set; em dash (—) for guests. Deleting a WordPress user automatically removes their linked subscriber row
4. Activate, deactivate, or delete subscribers from the list (admin actions do not set or change user_id; linking happens on logged-in frontend subscribe/reactivate only)
5. Import/export — see CSV import and export below

CSV import and export

Export (Notifications > Import/Export):

• Includes columns: id, name, email, user_id, frequency, status, date_added, last_notified, followed by one column per configured post_type:taxonomy pair (e.g. post:category, tribe_events:tribe_events_cat).
• Term values are comma-separated term names. user_id is the WordPress user ID when the subscriber signed up while logged in; empty for guests.

Import:

• Required columns: name, email
• Optional: frequency, plus any post_type:taxonomy columns matching configured content types. Each subscriber row must select at least one term across the configured taxonomies.
• Imports ignore user_id even if present in the file (prevents incorrect account links from spreadsheets). Link accounts only via the public subscription form when the user is logged in.

Subscriber Preference Management

See Guest vs logged-in behavior for how the preferences form differs by visitor type, subscription status, and token access.

1. Subscribers manage preferences on the configured Notification Preferences page ([subscriber_notifications_preferences])
2. Email links — {preferences_page}/?token={management_token} (from [manage_preferences_link] and notification emails)
3. Logged-in access — subscribers with a linked account (user_id) or matching account email can open the preferences page without a token
4. Subscribers can update:
   • Name (guest subscribers only; linked accounts use the WordPress profile)
   • Their selected terms for each configured post type / taxonomy
   • Delivery frequency
5. Unsubscribe option available on the preferences page (hidden while inactive)
6. Inactive subscribers who save the preferences form are reactivated (same as resubscribing via the public form); they receive the welcome-back email
7. Active subscribers receive a preferences-update confirmation email after saving

Flagging Posts for Notifications

1. Edit any post in an enabled content type
2. In the Subscriber Notifications meta box, check Include in topic notifications to add the post to scheduled topic notification emails (does not send immediately; stays checked until you uncheck it)
3. Optionally check Send on-page update email now to email on-page subscribers immediately when you save. This also stamps the post for (updated on …) in [content_feed] and [post_link] output in future topic notifications. That checkbox clears after save
4. Save — flagged posts are eligible for the next scheduled notification that matches subscriber preferences

Data storage

The plugin stores subscribers, scheduled notifications, and email logs in four custom tables (schema version 4). Data is created when the plugin is activated. All datetimes are stored in the WordPress site timezone via current_time( 'mysql' ) — not MySQL CURRENT_TIMESTAMP.

• Cascade delete — deleting a subscriber removes their email logs and send-queue rows.
• Send-queue retention — after a notification finishes sending, completed queue rows (sent, skipped) are purged; failed rows are kept for the dashboard.
• Uninstall — optionally delete all plugin data under Settings → General.

Security and performance

Nonces, capability checks (manage_options), sanitized input, optional reCAPTCHA, rate limiting, and prepared SQL. Topic notifications run on WordPress cron with batched sends for large lists; term lists are cached where appropriate.

Analytics

Every email the plugin sends is tracked automatically (there is no on/off setting).

• Open tracking — A 1×1 pixel in each message requests /track/open/ when the email client loads images. This is standard pixel tracking: it measures pixel loads, not a guaranteed human “open.”
• Click tracking — Links in the email body (including [content_feed] post links and [manage_preferences_link]) are wrapped with /track/click/ redirects so clicks are counted before the subscriber reaches the destination. mailto: and tel: links are not tracked.
• Where to view logs — Notifications → Logs (full list and CSV export) and the dashboard Recent activity panel.
• Email log types — Each row is labeled by purpose: Topic notification, Welcome, Welcome back, Preferences update, Test (admin test/preview sends), On-page subscription, and On-page update.
• Engagement metrics — The dashboard Email delivery panel shows open and click rates for the selected period (7 / 30 / 90 days or all time), using unique opens and clicks divided by delivered emails.

Interpreting open and click counts

Pixel tracking is approximate. Counts can differ from what a recipient remembers doing.

• Logs → Opens column — Total times the tracking pixel was loaded for that send (open_count). A single person opening once can still show 2+ if the mail client loads images more than once.
• Dashboard rates — Treat an email as opened or clicked once when open_count or click_count is greater than zero for that log row (unique engagement per send).
• Duplicate opens — Rapid repeat requests for the same pixel (preload, retries) are deduplicated within a 10-second window. Loads farther apart—preview pane then full open, mobile and desktop, or a second session—can each increment the count.
• Opens without clicking — Many clients and providers (Gmail image proxy, Apple Mail Privacy Protection, inbox preview, security scanners) fetch images in the background. You may see 1 open / 0 clicks even when the recipient did not consciously open the message.
• Clicks without extra opens — Clicking a tracked link updates click count only; it does not add an open unless the client also loads the pixel separately.

For manual QA, treat log opens as directional signal, not exact user actions. One click on Manage Preferences should always show 1 click on that email if the link was wrapped correctly.

Troubleshooting

Common Issues

1. Emails not sending

   • Confirm wp_mail() works on this site (SMTP plugin or host mail logs)
   • Use Send Test Email under Settings > General
   • Check server mail configuration or outbound SMTP blocking

2. Scheduled emails not working

   • Verify WordPress cron is functioning
   • Check scheduling settings in Settings
   • Ensure cron jobs are properly scheduled

3. CAPTCHA not working

   • Verify site key and secret key
   • Check domain configuration in reCAPTCHA v2 settings
   • Ensure you're using reCAPTCHA v2 (not v3) keys

4. No terms (or too few) on the subscription form

   • Visit Notifications > Content Types and confirm at least one post type is enabled
   • For each enabled post type, enable the taxonomies you want subscribers to choose from and set a valid term display mode (all, children of, include, or exclude)
   • Ensure the parent term (for "children of" mode) or each listed term still exists
   • If terms exist but have no published posts, they are hidden when Hide Empty Terms on Subscription Form is enabled (default). Uncheck that option under Settings > General, or publish content in those terms, or adjust Content Types include/exclude rules

5. Unwanted terms still visible on the public form

   • A term with at least one published post of that post type will always appear when configured. To hide it anyway, use Content Types exclude (or include-only) rules
   • Terms with zero published posts for that post type are hidden automatically when Hide Empty Terms on Subscription Form is on

6. Shortcodes not working

   • Ensure content is processed through the shortcode system
   • Check for proper subscriber context

7. WordPress mail test failing

   • Check server mail configuration
   • Verify SMTP settings if using SMTP plugin
   • Check server logs for mail errors

Debug Mode

Enable WordPress debug mode to see detailed error messages:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

Production cron

The scheduler registers five cron hooks (subscriber_notifications_process_queue, subscriber_notifications_send_daily, subscriber_notifications_send_weekly, subscriber_notifications_send_monthly, subscriber_notifications_drain_queue), all running every minute. WP-Cron only fires on incoming WordPress requests, so on low-traffic sites a notification can sit idle until someone visits the site. In production, disable WP-Cron and trigger it from a real system cron:

// wp-config.php
define('DISABLE_WP_CRON', true);

# /etc/crontab or `crontab -e` for the web user
* * * * * curl -s https://example.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1

This guarantees the send queue drains on a strict one-minute cadence regardless of site traffic.

Changelog

Version 4.0.0

• Release packaging — Integration tests, seed scripts, and Pantheon test runner moved out of the plugin (Internal Resources in repo; not shipped to sites). No database or runtime behavior change from 3.9.x

Version 3.9.10

• [selected_subscriptions] sections attribute — Optional comma-separated filter: topics, items (alias on-page). Default shows both. Use sections="topics" in topic digest emails so on-page subscription links are not listed alongside feed updates

Version 3.9.9

• [selected_subscriptions] email layout — When both exist, Topic notifications and On-page subscriptions appear as separate sections; taxonomy rows are indented under post types; on-page titles use bulleted lists with permalinks when published; plain format="plain" uses matching section labels
• Preferences updated email default — Simpler template: shortcode on its own block, Delivery frequency: label, manage link only (no redundant “Subscriptions:” wrapper)
• Email wrapper — Skips wpautop when the body already contains paragraph or subscription-summary block HTML

Version 3.9.8

• Subscribers list — Subscriptions column — Split Topic notifications and On-page subscriptions when both exist; taxonomy rows show label + count with +N truncation for long term lists; on-page items grouped by post type with count, A–Z titles (truncated), and frontend permalinks (new tab); notification targets column uses compact taxonomy rows without subscriber-only section headings; topic rows read from stored subscriber preferences (not current Content Types form enablement)

Version 3.9.7

• Meta box layout — Checkbox labels use Settings-style markup (no wrapping <p>); help text indented under the label with tighter spacing
• Preferences — On-page subscriptions — Same accordion layout as Choose your subscriptions (collapsible post-type sections, Select all, shared checklist styling); removed redundant Subscribed content legend
• Preferences — guest email field — Read-only email uses the same locked field styling as logged-in users

Version 3.9.6

• Meta box UX — Removed section headings; checkbox help only, with divider between topic and on-page controls
• On-page update help — Documents immediate email plus (updated on …) stamp in topic notification feeds
• Documentation — README Flagging Posts and [content_feed] note for updated-on link text

Version 3.9.5

• Meta box UX — Title Subscriber Notifications (Title Case); split into Topic notifications and On-page updates sections with scoped help text; removed combined intro that mixed both paths

Version 3.9.4

• Terminology — Aligned user-facing copy: Topic notifications (subscribe form + scheduled path) vs On-page subscriptions / On-page updates (widget + immediate path). Meta box, preferences, email templates, logs, and admin shortcode reference updated; internal slugs unchanged
• Meta box — Renamed to Subscriber notifications with intro explaining both paths; Include in topic notifications and Send on-page update email now
• **Preferenc