Skip to content

Powered by Grav CMS + Helios Theme

Newsletter automations (add-on)

Automations and their steps, the ready-made recipes, and the people walking through each one.

An automation is a trigger and a list of steps, and the routes call it a flow. See Automations.

List automations

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

Every automation this store has, with what starts it, how many steps it has, and where the people in it are: how many are moving, how many are waiting on a timer, how many have finished and how many left early. An automation is a series of waits and emails that runs on its own, one person at a time, from a trigger — a signup, a confirmation, a tag, an order, a subscription. Start here when somebody asks why a customer got an email nobody sent by hand. A flow's own messages never appear in the campaign list; they belong to their step.

Get one automation

GET /api/v1/kahunacart/newsletters/flows/{id} Permission kahunacart.newsletters.view

One automation with its steps in order, each email step's message summarized with what it has sent, opened and clicked, and a page of the people walking it — which step each of them is on, when they are due to move again, and why they left if they have. status narrows to moving, waiting, done or exited, and page walks the rest.

Parameters

Name Type Description
id required integer The automation
status optional string Show only the people in this state
One of: active, waiting, done, exited
page optional integer Which page of the people
sort optional string Sort the people by this column instead of newest first
One of: email, status, entered, left
dir optional string Which way sort runs. Without it, dates and counts run highest first and words A to Z
One of: asc, desc
q optional string Words to search for in the name and address of the people; every word has to be there, wherever it sits. Applied before the sort and the page, and the enrollments total counts what it found while the counts stay for the whole automation

Write an automation

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

Creates an automation in draft, with its steps. It is created switched off and sends nothing until it is activated, which is a separate call on purpose. steps is the whole ladder in order — every step needs a type and the settings that type takes, and an email step also takes a campaign with the subject and the body it should send. Positions are numbered from one and are what a branch step's yes and no name.

Parameters

Name Type Description
name required string What this automation is called, for you rather than for anybody who receives it
trigger required string What starts it
One of: subscribed, confirmed, tag_added, order_completed, first_order, product_bought, cart_recovered, subscription_started, subscription_renewed, subscription_cancelled
trigger_json optional object What the trigger is about: {"tag": "vip"} for tag_added, {"product_id": 12} for product_bought
list_id optional integer or null Only people on this list are put into it
segment_id optional integer or null Only people who match this segment are put into it
allow_reentry optional boolean Whether somebody may walk this automation more than once. Off means once ever, however it ended.
Default: false
exit_on_purchase optional boolean Take somebody out of it the moment they buy something
Default: false
steps optional array of object The whole ladder, in order. Keys: `type`, `config`, `campaign`

Change an automation

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

Changes an automation's settings, its steps, or both. The steps are saved whole: send the ladder you want, and a step that comes back with the id it was given keeps its row and everybody standing on it. A step you leave out is deleted, which is refused while anybody is standing on it. Changing an automation that is running is allowed and takes effect for everybody still in it.

Parameters

Name Type Description
id required integer
name optional string
trigger optional string
One of: subscribed, confirmed, tag_added, order_completed, first_order, product_bought, cart_recovered, subscription_started, subscription_renewed, subscription_cancelled
trigger_json optional object
list_id optional integer or null
segment_id optional integer or null
allow_reentry optional boolean
exit_on_purchase optional boolean
steps optional array of object The whole ladder, in order. A step with an id keeps its row and its people.

Delete an automation

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

Deletes an automation, its steps and the messages its email steps own, sends and all. Refused while anybody is still walking it unless force is set, which takes them all out first with "the automation was deleted" against their name. There is no undo.

Parameters

Name Type Description
id required integer
force optional string Delete it even though people are still in it
One of: 1

Switch an automation on

POST /api/v1/kahunacart/newsletters/flows/{id}/activate Permission kahunacart.newsletters.manage

Starts an automation running. From this moment its trigger puts people into it and the worker moves them along a step at a time. Refused for an automation with no steps, and for one whose email step has no message written — both would enroll people and do nothing to them. Nobody who qualified while it was in draft is enrolled retrospectively.

Parameters

Name Type Description
id required integer

Pause an automation

POST /api/v1/kahunacart/newsletters/flows/{id}/pause Permission kahunacart.newsletters.manage

Holds everybody in an automation exactly where they are: no step runs, no mail goes out, nobody new is put in, and nobody is taken out. Resuming carries each of them on from the same step they were standing on.

Parameters

Name Type Description
id required integer

Resume a paused automation

POST /api/v1/kahunacart/newsletters/flows/{id}/resume Permission kahunacart.newsletters.manage

Sets a paused automation running again. Everybody in it carries on from the step they were held at; a wait that ran out while it was paused is over, so those people move on the worker's next run.

Parameters

Name Type Description
id required integer

Put one person into an automation

POST /api/v1/kahunacart/newsletters/flows/{id}/enrol Permission kahunacart.newsletters.manage

Starts one subscriber on an automation by hand, under exactly the same rules a trigger applies: they have to be subscribed, on the automation's list if it names one, matching its segment if it names one, and new to it unless it allows re-entry. The refusal says which of those was the problem. Useful for testing an automation on yourself before switching it on.

Parameters

Name Type Description
id required integer The automation
subscriber_id required integer Who to put into it

Take one person out of an automation

POST /api/v1/kahunacart/newsletters/flows/{id}/enrolments/{eid}/exit Permission kahunacart.newsletters.manage

Ends one person's walk through one automation, with "taken out by hand" against it. They keep the step they had reached, so the record still says how far they got, and they receive nothing more from it. It does not stop the same trigger putting them back in later if the automation allows re-entry.

Parameters

Name Type Description
id required integer The automation
eid required integer The enrollment, from get_automation

List the ready-made automations

GET /api/v1/kahunacart/newsletters/flows/recipes Permission kahunacart.newsletters.view

The automations that come with the add-on ready to use — a welcome series, a thank you after somebody buys, a win-back — each with a key, a sentence saying what it does, its ladder written out a step a line, and what to change before switching it on. available says whether this store can use it and reason says what is missing when it cannot: the win-back mints a discount code apiece and needs a coupon group that exists. Each one writes a draft you read through and change before switching it on.

Write an automation from a recipe

POST /api/v1/kahunacart/newsletters/flows/recipes/{key} Permission kahunacart.newsletters.manage

Builds a draft automation from one of the ready-made ones, with its steps and its messages already written. It is a draft: nothing is sent, nobody is enrolled and no discount code is minted until it is activated, so this is safe to call and read through. Answers a 404 for a key that does not exist, and a 422 naming what to make first for a recipe this store is not set up for — see available on list_automation_recipes.

Parameters

Name Type Description
key required string Which recipe, from list_automation_recipes