# Your first automation

> Part of the Cowliss docs. Markdown for every page: append `index.md` to its URL. Site map: /llms.txt

This page starts where the [Quickstart](/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:

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

## 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.)

```sh
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:

```sh
rm automations/welcome.json emails/welcome.html emails/trial-ending.md scenarios/welcome.signed-up.json
```

## 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:

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

## 3. Write the email

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

```md title="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](/emails/).

## 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:

```json title="automations/abandoned-checkout.json"
{
  "trigger": { "event": "checkout_started" },
  "purpose": "marketing",
  "from": "Acme <hello@acme.com>",
  "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](/emails/#purposes).

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

## 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:

```json title="scenarios/abandoned-checkout.recovered.json"
{
  "user": { "id": "usr_1", "traits": { "email": "ada@acme-demo.io", "plan": "free" } },
  "events": [{ "at": "1h", "event": "purchase_completed" }],
  "expect": []
}
```

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

```json title="scenarios/abandoned-checkout.reminded.json"
{
  "user": { "id": "usr_1", "traits": { "email": "ada@acme-demo.io", "plan": "free" } },
  "events": [],
  "expect": [{ "activity": "sendEmail", "input": { "template": "abandoned-checkout" } }]
}
```

```sh
npx cow test abandoned-checkout
```

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

```text
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](/automations/testing/) has the rest of the scenario format.

## 6. Push

```sh
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.

## 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):

```ts
await cow.identify({
  identifiers: { userId: "user_1" },
  traits: { email: "ada@acme-demo.io", plan: "free" },
  consent: { "marketing.cartReminders": true },
});
```

Without it the email is skipped, and the delivery says why. See [Consent](/sdk/identify/#consent).

## 8. Turn it on

```sh
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 `hello@acme.com` 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

- [Segments](/segments/): group people by traits and events, and start an automation the moment somebody enters.
- [Your repo](/guides/repo/): the full loop, `cow init` to `cow pull`.
- [Automations](/automations/): triggers, the seven steps, rules, and four full examples.
- [Testing](/automations/testing/): dry runs against a real user, and a second organization for the whole loop.
- [Connect your auth provider](/tracking/apps/#connecting-clerk): users, signups and logins arrive with no integration code.
- [Blueprints](/blueprints/): `cow add blueprint <name>`.
