Skip to content
Cowliss is in beta: features and pricing may change.

Your first automation

View as markdown

This page starts where the Quickstart ends: an app, a client sending identify and track, and a verified sending domain. By the end, an automation in your repo emails people who started a checkout and did not finish within a day, and it is on.

Your app sends one more event for this, checkout_started, when someone starts a checkout:

await cow.track({
identifiers: { userId: "user_1" },
event: "checkout_started",
});

An automation is a JSON file in your repo that runs once per person: wait, check, send. (An API call can write the same definition, for a builder or an agent with no repo.)

Terminal window
npx cow init && cd .cowliss && npm install

cow init writes the project into .cowliss/ in your repo, and puts app_my-app in its cow.json, since it is your only app. Everything this repo pushes belongs to it, so no file below names it again. It also writes an example: automations/welcome.json, its email, a second example template and a scenario. This page builds its own automation, so delete those four files now (on Windows, delete them in the explorer); then every step below creates only what the final push sends:

Terminal window
rm automations/welcome.json emails/welcome.html emails/trial-ending.md scenarios/welcome.signed-up.json

An email says why it is sent. Your app declares its reasons in .cowliss/cow.json, each with the label a recipient reads. Add this beside the orgId and appId already there:

.cowliss/cow.json
"purposes": [{ "key": "marketing.cartReminders", "label": "Cart reminders" }]

The email names that purpose. {{firstName|there}} reads the person’s firstName trait:

emails/abandoned-checkout.md
---
subject: Still thinking it over?
purpose: marketing.cartReminders
---
Hi {{firstName|there}}, your cart is still here.

An email can also be Liquid HTML, emails/<key>.html, when it needs your own layout, loops or conditions. See Email templates.

It starts on checkout_started, gives them a day to come back on their own, and stops if purchase_completed arrives:

automations/abandoned-checkout.json
{
"trigger": { "event": "checkout_started" },
"purpose": "marketing",
"from": "Acme <[email protected]>",
"steps": [
{ "id": "wait", "type": "waitForEvent", "event": "purchase_completed", "timeout": "24h" },
{
"id": "purchased",
"type": "branch",
"if": { "var": "steps.wait.matched" },
"then": [{ "id": "done", "type": "exit" }]
},
{ "id": "remind", "type": "sendEmail", "template": "abandoned-checkout" }
]
}

The automation names the root, marketing, because its purpose only decides how it enrolls people; the template names marketing.cartReminders, because each email is gated on its own purpose, the one a recipient can turn off without leaving everything else. See Purposes.

The wait is durable: it survives deploys, and a purchase at hour 23 still cancels the email.

A scenario says what one run should do. Write one for each way the day can end. In the first, they buy within the hour, so nobody is emailed:

scenarios/abandoned-checkout.recovered.json
{
"user": { "id": "usr_1", "traits": { "email": "[email protected]", "plan": "free" } },
"events": [{ "at": "1h", "event": "purchase_completed" }],
"expect": []
}

In the second, they never buy, so after 24 hours they get the reminder:

scenarios/abandoned-checkout.reminded.json
{
"user": { "id": "usr_1", "traits": { "email": "[email protected]", "plan": "free" } },
"events": [],
"expect": [{ "activity": "sendEmail", "input": { "template": "abandoned-checkout" } }]
}
Terminal window
npx cow test abandoned-checkout

Expected: both pass, on a virtual clock and with nothing sent:

passed scenarios/abandoned-checkout.recovered.json
passed scenarios/abandoned-checkout.reminded.json
2 scenarios passed.

To see one run in full, npx cow test abandoned-checkout --scenario scenarios/abandoned-checkout.reminded.json prints its report: the one sendEmail call, and "simulatedMs": 86400000, the 24 hours it waited. Testing has the rest of the scenario format.

Terminal window
npx cow plan # check the files and show what a push would change
npx cow push # files a new version of whatever changed

Expected: cow plan lists the new automation, the new template and the marketing.cartReminders purpose, and cow push stores them. A pushed automation is off until you enable it.

A marketing email reaches only people who said yes to its purpose. Now that the push has declared it, record the yes on the identify call you already make (until then the API refuses a purpose it does not know):

await cow.identify({
identifiers: { userId: "user_1" },
traits: { email: "[email protected]", plan: "free" },
consent: { "marketing.cartReminders": true },
});

Without it the email is skipped, and the delivery says why. See Consent.

Terminal window
npx cow enable abandoned-checkout

Expected: the automation reads as on. From now on, a checkout_started with no purchase_completed within 24 hours sends the reminder from [email protected] to anyone who said yes.

Automations in the dashboard shows its steps, who is in flight and on which step, and every email it sent; npx cow automations stats abandoned-checkout --app-id app_my-app reads the same counts from the terminal.

  • Segments: group people by traits and events, and start an automation the moment somebody enters.
  • Your repo: the full loop, cow init to cow pull.
  • Automations: triggers, the seven steps, rules, and four full examples.
  • Testing: dry runs against a real user, and a second organization for the whole loop.
  • Connect your auth provider: users, signups and logins arrive with no integration code.
  • Blueprints: cow add blueprint <name>.