Newsletters

This page introduces the newsletter add-on and the screens it adds to your store. It is for the store owner who wants the audience, the consent record and the numbers kept with the orders instead of in a separate email tool.

The newsletter is an add-on, not part of KahunaCart itself. Install the kahunacart-newsletters plugin alongside the base plugin and your store can collect subscribers and mail them. Leave it out and the rest of your store behaves exactly as before.

Two facts sit underneath everything else in this chapter.

Your store is the audience of record. A subscriber is a row in your own database with a consent record on it: when this person agreed, from what address, and a hash of the exact sentence they were shown. It is not a flag on a customer row. Somebody can subscribe from your homepage without ever buying, and somebody can buy for years without ever being asked, and the store tells those two apart.

The numbers are yours. Opens are a one-pixel image and clicks are a redirect, both served by this plugin from your own domain. A campaign from three years ago still says how it did, whatever mail provider you were using at the time.

Before you begin

KahunaCart 1.2.0 or later, on a store that can already take an order. See Getting started.
The Grav Email plugin 5.1.0 or later, already sending mail, with a transport configured. Delivery reports need 5.1.0, where the provider contract lives. See Delivery reports and providers.
The scheduler running. A campaign is one job on the store's own queue, and nothing goes out unless a worker is draining it. See CLI.
The kahunacart-newsletters plugin installed and enabled, and kahunacart.newsletters.view, .manage or .send on whoever is going to run it.

The ten screens

The newsletter appears in the KahunaCart admin under Newsletters, with ten screens along the top.

Screen	What it is for
Overview	Four figures (subscribed, waiting to confirm, left, never mail again), thirty days of new signups, the last campaign, and the recent campaigns table.
Campaigns	Writing, previewing, testing, scheduling and sending one message to one audience, and the numbers afterwards.
Subscribers	The searchable list of people, and one person's whole history: consent, lists, tags, and every campaign they were part of.
Audience	Lists, tags and segments. A list is a topic somebody chose, a tag is something the store noticed, a segment is a saved question about both.
Automations	Series of waits and emails that run on their own, one person at a time, from the moment the store notices something about them.
Templates	Starting points a campaign can be created from. A template is copied, never referenced.
Suppressions	The addresses this store will never mail again, keyed by a hash of the address.
Reports	Seven reports over any range of dates: campaign performance, list growth, engagement, links, bounces and complaints, automations and send times, each with a CSV export.
Health	Nine deliverability checks over your domain, your transport and the last thirty days of sending.
Settings	The plugin's own configuration form, drawn inside the KahunaCart admin, plus the Providers cards.

Note

Two screens were renamed after the first release. Lists, tags and segments are now under Audience, and the deliverability checks are under Health.

The three permissions

Permission	What it allows
`kahunacart.newsletters.view`	Reading. Subscribers, campaigns, counters, lists, templates, suppressions, settings.
`kahunacart.newsletters.manage`	Everything that writes: campaigns, lists, tags, templates, imports, suppressions, unsubscribing somebody by hand.
`kahunacart.newsletters.send`	Starting a campaign, resuming one, and the test send. Checked in addition to `.manage`, never instead of it.

Sending is a separate permission because pausing a campaign does not get back the mail that already went. You can give a copywriter everything they need to write, preview and schedule a campaign without letting them send it.

A reader without .manage sees every screen with the buttons absent and a line saying why.

The words this chapter uses

Term	Means
Subscriber	One person, one address, one consent record.
List	A topic somebody can join and leave on its own, with its own membership status per person.
Tag	Something the store noticed rather than something anybody chose. Removing a tag unsubscribes nobody.
Segment	A saved question about your audience, answered against the live database every time it is asked.
Campaign	One message, one audience, one set of numbers.
Automation	A series of waits and emails that runs on its own, one person at a time.
Suppression	An instruction never to mail an address, which outranks every list and every import.
Provider	The mail service you send through, and the transport plugin that talks to it.

What is on the alert strip

Anything that needs fixing before the next campaign goes out appears on the admin's Needs attention strip at the top of every KahunaCart screen, not on the Overview. Each alert folds away, can be hidden for a while, and opens the screen that fixes it.

The Email plugin is missing or switched off.
A campaign stopped itself after too many refusals in a row.
No From address of the newsletter's own is set.
The transport drops the one-click unsubscribe headers.
A segment's last count failed.
The bounce rate over the last thirty days is above alerts.bounce_rate_percent.
A campaign has gone out, a provider secret is configured, and no delivery event has arrived in thirty days.
Something is posting to a provider webhook address that has no secret configured.

A store with nothing wrong has an empty strip. See Dashboard alerts.

Five of those alerts can also reach you away from the admin, on the channels you tick under Notifications → Store owner, in KahunaCart 1.5.3 or later. A campaign that stopped itself and a bounce rate over your limit arrive as urgent messages. A provider that has gone quiet, a webhook with no secret behind it and a failing deliverability check arrive as normal ones. Each sends one message when it starts and a "Cleared" one when it stops. You can switch them off or choose their channels on that screen. The Email plugin missing, no From address, stripped unsubscribe headers and a segment that would not count stay on the strip, since you are in the admin when you go to fix them. New messages go to the channels chosen under New messages go to on the Channels page until you tick channels on a row yourself.