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
/api/v1/kahunacart/newsletters/flows
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
/api/v1/kahunacart/newsletters/flows/{id}
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
/api/v1/kahunacart/newsletters/flows
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
/api/v1/kahunacart/newsletters/flows/{id}
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
/api/v1/kahunacart/newsletters/flows/{id}
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
/api/v1/kahunacart/newsletters/flows/{id}/activate
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
/api/v1/kahunacart/newsletters/flows/{id}/pause
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
/api/v1/kahunacart/newsletters/flows/{id}/resume
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
/api/v1/kahunacart/newsletters/flows/{id}/enrol
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
/api/v1/kahunacart/newsletters/flows/{id}/enrolments/{eid}/exit
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
/api/v1/kahunacart/newsletters/flows/recipes
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
/api/v1/kahunacart/newsletters/flows/recipes/{key}
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 |