Skip to main content

Read the Analytics Dashboard email engagement

Premium Intermediate Analytics Dashboard

How the Email Editor’s episode notifications and broadcasts were opened and clicked over the dates, each kind apart, beside the previous period of the same length, as the Email engagement box, its Export CSV and the PDF snapshot draw it. It takes show_id, date_from, date_to (inclusive UTC Y-m-d) and scope, with the same permission and 403 as the other Analytics Dashboard routes; a tier_slug is ignored. The add-on reads each show and each kind through the Email Editor’s benecaster_email_editor_get_engagement(), never its tables.

  • Two kinds, never blended. types.episode_notification and types.broadcast are read separately; no figure adds one to the other.
  • available is false when the Email Editor is not on for any show read, or not installed: draw a placeholder, not an empty state. shows gives each show’s own available. With available: true and no sends, every count is 0 and every rate null.
  • Rates are percentages to one decimal of recipients, null with no recipients. change.open_rate is in points against prior; direction is up, down or same, and both are null when either period had no recipients.
  • tiers sums each send’s per-tier counts over the range, most recipients first; tier_slug '' is followers. Aggregates only: no recipient is ever named.
  • Open rates are directional (Apple Mail fetches every tracking pixel when the mail arrives), and nothing is recorded while the Email Editor is off for a show or its license has lapsed. Say both wherever you show these figures.
  • The filter’s $args are show_ids, date_from, date_to and tier_slug (always null); a non-array return is ignored.
  • The answer also carries placeholder_dismissed, added after the filter because it is about the viewer: whether the person asking dismissed the placeholder. POST benecaster-analytics/v1/analytics/email-engagement/dismiss-placeholder with { show_id } dismisses it for that person on every show and answers { dismissed: true }.

Code

const url = window.benecasterAnalyticsDashboard.apiUrl + 'analytics/email-engagement?show_id=12&date_from=2026-10-01&date_to=2026-10-31';
const email = await ( await fetch( url, { headers: { 'X-WP-Nonce': window.benecasterAdmin.nonce } } ) ).json();
if ( ! email.available ) {
    // The Email Editor is not on for any show read (or not installed): draw a placeholder, not an empty state.
}
// email.types.episode_notification → { sends: [ { show_id, show_name, type, send_id, title, sent_at, recipients, opened, opens, clicked, clicks, open_rate, click_rate }, … ],
//   totals: { sends: 2, recipients: 20, opened: 10, opens: 14, clicked: 3, clicks: 4, open_rate: 50, click_rate: 15 },
//   prior: { recipients: 10, opened: 4, …, open_rate: 40, click_rate: 0 }, change: { open_rate: 10, direction: 'up' },
//   tiers: [ { tier_slug: 'gold', recipients: 12, opened: 8, …, open_rate: 66.7, click_rate: 25 }, { tier_slug: '', … } ] }
// email.types.broadcast → the same shape, never added to the other.

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →