Skip to content
KahunaCart

Powered by Grav CMS + Helios Theme

Newsletter lists and tags (add-on)

The topics people subscribe to and leave separately, and the tags that mark them.

Lists are what a person joins and leaves; tags are the store's own labels on a person. See Subscribers, lists and tags.

List mailing lists

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

Every list in the store with the number of people a campaign to it would reach — the subscribed ones, not the pending or the departed. A list is a topic somebody can leave on its own, with a code a signup form names it by and a per-person membership that is what makes a preference center possible at all.

Create a mailing list

POST /api/v1/kahunacart/newsletters/lists Permission kahunacart.newsletters.manage

Add a topic people can subscribe to and leave separately. The code is what a signup form posts and what an import writes into, and it can never be changed afterwards; the name is what people read on the preference center. Double opt-in defaults to the store setting and should stay on for anything a form on a public page points at.

Parameters

Name Type Description
code required string Lowercase, no spaces. Fixed once the list exists.
name required string What people read on the preference center
description optional string or null
double_opt_in optional boolean Ask people to confirm by email. Defaults to the store setting.
is_default optional boolean Where a signup with no list named goes. Only one list is the default.
public optional boolean Offer it on the preference center and in the customer account, so somebody can join it themselves. Off by default, and then it is joined only through a signup form, an import or the admin.
position optional integer
from_name optional string or null Overrides the store default for this list
from_email optional string or null

Edit a mailing list

PATCH /api/v1/kahunacart/newsletters/lists/{id} Permission kahunacart.newsletters.manage

Change a list's name, description, confirmation setting, default flag, whether it is offered on the preference center, or sender overrides. The code cannot be changed and the attempt is refused — every signup form, import and campaign audience is resolved through it, and renaming it would break every form on the site while every screen went on looking correct. Making one list the default clears the flag on any other.

Parameters

Name Type Description
id required integer List id
name optional string
description optional string or null
double_opt_in optional boolean
is_default optional boolean
public optional boolean Offer it on the preference center and in the customer account, so somebody can join it themselves
position optional integer
from_name optional string or null
from_email optional string or null

List tags

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

Every tag in the store with how many people carry it. A tag is something the store noticed rather than something anybody chose — a label an import or a signup form put on somebody — so it has no consent and no state, and removing one unsubscribes nobody. A tag nobody carries is the one worth finding and deleting.

Create a tag

POST /api/v1/kahunacart/newsletters/tags Permission kahunacart.newsletters.manage

Add a tag. Codes are normalized — lower case, spaces and underscores to hyphens — so "Early Access", "early access" and "early-access" are one tag, and adding one that already exists answers the existing row rather than failing.

Parameters

Name Type Description
code required string The tag, as typed. It is normalized on the way in.
label optional string or null What a person reads. Defaults to the text as typed.

Delete a tag

DELETE /api/v1/kahunacart/newsletters/tags/{id} Permission kahunacart.newsletters.manage

Remove a tag from the store and from everybody carrying it. Nobody is unsubscribed and no membership changes: a tag is a note the store made about people, so deleting one has no consequences for them.

Parameters

Name Type Description
id required integer Tag id