Your first automation
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",});1. Set up the project in your repo
Section titled “1. Set up the project in your repo”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.)
npx cow init && cd .cowliss && npm installcow 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:
rm automations/welcome.json emails/welcome.html emails/trial-ending.md scenarios/welcome.signed-up.json2. Declare why you send
Section titled “2. Declare why you send”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:
"purposes": [{ "key": "marketing.cartReminders", "label": "Cart reminders" }]3. Write the email
Section titled “3. Write the email”The email names that purpose. {{firstName|there}} reads the person’s firstName trait:
---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.
4. Write the automation
Section titled “4. Write the automation”It starts on checkout_started, gives them a day to come back on their own, and stops if purchase_completed arrives:
{ "trigger": { "event": "checkout_started" }, "purpose": "marketing", "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.
5. Test both paths
Section titled “5. Test both paths”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:
{ "events": [{ "at": "1h", "event": "purchase_completed" }], "expect": []}In the second, they never buy, so after 24 hours they get the reminder:
{ "events": [], "expect": [{ "activity": "sendEmail", "input": { "template": "abandoned-checkout" } }]}npx cow test abandoned-checkoutExpected: both pass, on a virtual clock and with nothing sent:
passed scenarios/abandoned-checkout.recovered.jsonpassed scenarios/abandoned-checkout.reminded.json2 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.
6. Push
Section titled “6. Push”npx cow plan # check the files and show what a push would changenpx cow push # files a new version of whatever changedExpected: 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.
7. Record consent
Section titled “7. Record consent”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" }, consent: { "marketing.cartReminders": true },});Without it the email is skipped, and the delivery says why. See Consent.
8. Turn it on
Section titled “8. Turn it on”npx cow enable abandoned-checkoutExpected: 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.
Where next
Section titled “Where next”- Segments: group people by traits and events, and start an automation the moment somebody enters.
- Your repo: the full loop,
cow inittocow 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>.