Skip to content
KahunaCart

Powered by Grav CMS + Helios Theme

Getting started with the newsletter

This page guides you through installing the add-on and sending your first campaign. It assumes KahunaCart is already selling; if it is not, start with Getting started and come back.

Before you begin

  • KahunaCart 1.2.0 or later, and the Grav Email plugin already sending mail.
  • The scheduler running bin/plugin kahunacart work every minute.
  • kahunacart.newsletters.manage and kahunacart.newsletters.send on your account.

Install the add-on

  1. 1

    Install the plugin.

    BASH
    bin/gpm install kahunacart-newsletters
  2. 2

    Look at what the migrations will do, then run them.

    BASH
    bin/plugin kahunacart migrate --status
bin/plugin kahunacart migrate

    newsletter_0001_core and newsletter_0002_campaigns create thirteen tables and seed one list, newsletter, with double opt-in on. Running migrate a second time applies nothing.

  3. 3

    Check the worker is draining the queue.

    BASH
    bin/plugin kahunacart work --once

    On a live store this is a cron entry running every minute. Without it a campaign sits in sending with counters that never move.

Newsletters now appears in the KahunaCart admin sidebar.

Set the From address

  1. In the admin sidebar, click KahunaCart, then Newsletters → Settings.
  2. Open the Sending tab.
  3. Set From name and From address under Who Campaigns Come From.
  4. Click Save in the admin header.
YAML
from_name: 'Your Store'
from_email: h[email protected]

Leave them empty and campaigns go out as whatever the Grav Email plugin is configured with. The alert strip says so until one is set.

Important

from_email has to be an address your mail transport is allowed to send as, or the mail will not land.

Check the store can actually send

At the top of the Sending tab, Can this store send mail? answers two questions: whether the Grav Email plugin is installed and sending, and whether the one-click unsubscribe headers survive your transport.

Read the second one carefully. List-Unsubscribe and List-Unsubscribe-Post are what put an unsubscribe button at the top of a Gmail message, and an API transport can drop them on the way to a JSON body. Where no transport plugin answers, the check says the transport has not been asked rather than guessing.

YAML
consent_text: 'Yes, email me about new products and offers. I can unsubscribe at any time.'

This is the sentence a signup form prints. A SHA-256 of it is stored against every consent recorded through that form, so you can later show the wording and the hash together as proof of what somebody agreed to.

Clear the field and the consent checkbox stops being required. See Signup forms.

Make a list

  1. Go to Newsletters → Audience.
  2. Click Add a list.
  3. Enter a name. This is what people read on the preference centre.
  4. Enter a code. This is what a signup form posts and what an import writes into.
  5. Leave Ask people to confirm on for anything a public page points at.
  6. Click Save.

Warning

A list's code can never be changed once the list exists. Every form, import and campaign audience is resolved through it.

Exactly one list is the default. Making one the default clears the flag on every other.

Get some subscribers in

There are three ways.

A signup form. Point the Form plugin's newsletter process action at the list, or drop {{ kahunacart_newsletter_form() }} into a theme template. See Subscribers, lists and tags.

An import. Newsletters → Subscribers → Import a CSV. Leave Ask everybody to confirm off for a list from another tool, since those people already confirmed there. See Import a contact list.

By hand. Add somebody, for one person who asked you directly. They land confirmed and are sent nothing.

Send your first campaign

  1. 1

    Go to Newsletters → Campaigns → Write a campaign. Give it a name only the store sees, a subject, and a body in Markdown.

  2. 2

    Write merge tags as {{ subscriber.first_name }}. The full list is under the body. Anything not on it is refused when you save, with the variable named.

  3. 3

    Read the preview beside the editor. It renders through the store's real email layout with a sample subscriber, with tracking off.

  4. 4

    Save the campaign. Send a test and Send it appear under the form once it is saved. Click Send a test, give it your own address, and open the result in a real inbox. Check that it reads well on a phone, that the unsubscribe link works, and that Gmail draws its own unsubscribe button beside your name.

  5. 5

    In the Send it panel, below Send a test, click Send it now — or put a date and time in Send at first, which turns the button into Schedule it. The confirmation names the number of people it is about to reach.

The audience is worked out before anything is queued. Everybody on the list who is subscribed and not suppressed gets a row, and everybody excluded gets a row saying why. A campaign that would reach nobody is refused rather than started.

The morning after

The campaign screen carries the counters, the first forty-eight hours as a chart, which links were clicked and how often, and the recipient table filtered by what happened to each person.

The chart is cumulative and by the hour from the moment the first message left.

What the alert strip is telling you

The strip says Do this
The Email plugin is missing or switched off Install and enable the Grav Email plugin, and configure a transport.
No From address Set from_name and from_email on Settings → Sending.
The transport drops the unsubscribe headers Update the transport plugin, or switch to a transport that carries headers. See Health.
A campaign stopped itself Fix the mail settings, then press Resume on the campaign.
A segment's last count failed Open the segment; a condition names a field the store no longer has.
The bounce rate is above the threshold See Health.
A webhook has said nothing in thirty days See Delivery reports and providers.

If something goes wrong

Nothing is sending. Check the worker. Newsletters → Settings says at the top of its Sending tab whether the store can send at all, and the campaign's own screen says whether the job was queued.

A campaign stopped itself. Too many messages in a row were refused, so sending.abort_after_failures stopped it. Fix the mail settings and press Resume. It carries on from what is still pending, and nobody is mailed twice.

Somebody says they never signed up. Open them in Subscribers. The screen says when they agreed, from what address, whether the store still holds the sentence they were shown, which import they came in with, and every campaign they have been part of.