Skip to content

Powered by Grav CMS + Helios Theme

Newsletter overview and reports (add-on)

The front screen in one call, the settings as the store sees them, and the Reports tab.

The read-only calls behind the section's front screen and its Reports tab. See Reports.

Newsletter overview

GET /api/v1/kahunacart/newsletters/overview Permission kahunacart.newsletters.view

The front screen of the newsletter in one call: how many people are in each subscriber status and how many of them a campaign could actually reach, how many addresses are suppressed, thirty daily buckets of new signups, the last five campaigns with their open and click rates, the last twenty that actually went out with their open, click, unsubscribe, bounce and complaint rates side by side, how many campaigns are in each status, and every alert the store should act on before it sends anything else. Start here when somebody asks how the mailing list is doing, or how the last few sends compare with one another.

Get newsletter settings

GET /api/v1/kahunacart/newsletters/settings Permission kahunacart.newsletters.view

What this store is configured to send and whether it can. The sending throttle, the batch size and the circuit breaker; whether opens and clicks are counted by default and how long the rows are kept; the from name and address campaigns go out as; and the transport check — whether the Grav Email plugin is installed and sending, which engine it uses, and whether the one-click unsubscribe headers survive that transport, which is what decides whether Gmail shows an unsubscribe button. Read only; the values are edited in the plugin's own configuration.

One of the seven newsletter reports

GET /api/v1/kahunacart/newsletters/reports/{type} Permission kahunacart.newsletters.view

The Reports tab, as a call. Pick a report with type and a window with from and to (dates, YYYY-MM-DD) or a preset, and the answer carries a row of headline figures, a table with its columns, and — the part worth reading before quoting any of it — the sentence that defines every figure and every column, so nothing has to be guessed at from a column name. Every rate is a fraction between 0 and 1 and is null rather than zero where there was nothing to divide by, with the two counts it was made of in their own columns beside it. Times are UTC epoch seconds; the send-time report is the one exception and reads the store's own timezone, which it names. Nothing here writes and nothing here is money — what a campaign earned is a question for the base plugin's analytics. The seven: campaigns is one row per campaign sent in the window with its five rates and a totals row, for "did that subject line work"; list-growth is joined, confirmed, left and suppressed per day, week or month with the way each person arrived, for "are we growing"; engagement is how many subscribers have opened anything in thirty, sixty and ninety days, how many never have and how many are dormant, broken down by list and by tag, for "who should we win back and who should we stop mailing"; links is the most pressed links with the share of that campaign's opens that pressed them, for "what did people actually want"; bounces is bounces and complaints by receiving domain and by transport, for "our reputation slipped and we do not know where"; automations is per flow enrolled, walking it now, finished, why people left early, and the open and click rates of its emails; send-times is opens by hour and weekday, for "when do our readers read". Answers are cached for five minutes; refresh set to 1 reads the store again.

Parameters

Name Type Description
type required string Which report
One of: campaigns, list-growth, engagement, links, bounces, automations, send-times
from optional string First day of the window, YYYY-MM-DD. With `to`, this wins over `preset`.
to optional string Last day of the window, YYYY-MM-DD, counted whole.
preset optional string A window by name instead of by dates. Defaults to the last 30 days.
One of: 7d, 30d, 90d, year, all, custom
bucket optional string How wide one row of list-growth is. Left off, it is chosen from the length of the window.
One of: day, week, month
list optional integer Narrow list-growth to one list.
campaign optional integer Narrow links to one campaign.
flow optional integer Cut automations by the steps of one automation instead of by flow.
refresh optional integer Set to 1 to ignore the five-minute cache and read the store again.

Read the section's strings

GET /api/v1/kahunacart/newsletters/labels Permission kahunacart.newsletters.view

Every caption, empty state and confirmation the admin section prints, translated into the store's language. No tool: it is the screen's own wording rather than anything about the store.

Export a report as CSV

GET /api/v1/kahunacart/newsletters/reports/{type}.csv Permission kahunacart.newsletters.view

The same table as GET /kahunacart/newsletters/reports/{type}, as a file to open in a spreadsheet.