---
title: "Automations and events"
description: "Every command for automations, the people inside them and the events that move them, with worked examples."
url: "https://openemail.uk/docs/cli/automations"
area: "CLI"
category: "Commands by area"
---

# Automations and events

Every command for automations, the people inside them and the events that move them, with worked examples.

## How it fits together

An automation is a trigger and a tree of steps. It keeps a draft and a live version: `update` changes the draft and the settings, and `publish` freezes the draft and turns the automation on. Reading needs `automations:read` and changing needs `automations:write`. `publish`, `resume` and `send-test` also need `emails:send`, because they make the automation send mail.

**Terminal**

```
openemail automations create --name "Welcome series" --starter welcome-series
openemail automations update aut_5c1e9a7b3d2f48e6a0b4c7d1 --data @welcome.json
openemail automations publish aut_5c1e9a7b3d2f48e6a0b4c7d1
openemail automations stats aut_5c1e9a7b3d2f48e6a0b4c7d1
```

The definition is JSON, so write it to a file and pass it with `--data @file`. `openemail automations get <id> --json` prints the current one, and its `problems` lists what still stops it from being published.

## Automations

| Command | What it does |
| --- | --- |
| openemail automations list | One page of the automations, most recently changed first. `--status` narrows it to `draft`, `live`, `paused` or `archived` |
| openemail automations create --name <value> | Make a draft from `--starter`, from a definition in `--data`, or an empty one |
| openemail automations get <id> | One automation with its draft, its live version, its settings and what is wrong with the draft |
| openemail automations update <id> | Change the name, the settings or the draft definition. `--expected-updated-at` refuses to overwrite a change made since you read it |
| openemail automations publish <id> | Freeze the draft as the next version and turn the automation on |
| openemail automations pause <id> | Stop a live automation. Everybody inside holds where they are |
| openemail automations resume <id> | Turn a paused automation back on with the version it was running |
| openemail automations archive <id> | Retire an automation for good and keep its history. Everybody inside leaves |
| openemail automations duplicate <id> | Copy an automation into a new draft, without its people or numbers |
| openemail automations delete <id> | Delete an automation and its history after you confirm. A browser sign-in also asks for a verification code |
| openemail automations list-starters | The starting points a new automation can begin from |

## Testing, versions and numbers

| Command | What it does |
| --- | --- |
| openemail automations send-test <id> --step-key <value> | Send one email step of the draft to yourself, or to `--to`, with sample values. It enrolls nobody |
| openemail automations list-versions <id> | Every version that was published, newest first |
| openemail automations restore-version <id> <version> | Copy an earlier version back into the draft. Publish to make it run |
| openemail automations stats <id> | Totals, a row for each step and a point for each day. `--since` sets where the window starts, and it defaults to the last 30 days |

## People inside an automation

| Command | What it does |
| --- | --- |
| openemail automations list-enrollments <id> | The people who entered, newest first, with the step each one is on. `--status` and `--step-key` narrow it, and `--all` reads every page |
| openemail automations get-enrollment <id> <enrollment-id> | One person’s run, with every step it ran and the email each send produced |
| openemail automations enroll <id> --email <value> | Put a contact into a live automation at its first step. `--contact-id` names the contact by id instead |
| openemail automations exit-enrollment <id> <enrollment-id> | Take somebody out before they finish |

**Terminal**

```
openemail automations list-enrollments aut_5c1e9a7b3d2f48e6a0b4c7d1 --status active --all --json | jq -r '.items[] | .contact.email + " " + (.stepKey // "")'
```

## Events

An event says a contact did something in your product. It starts every live automation whose trigger names it and moves on anybody who was waiting for it. Sending one needs `contacts:write`.

| Command | What it does |
| --- | --- |
| openemail events send --name <value> --email <value> | Record one event for a contact. `--create-contact` adds the contact when nobody has the address yet, and `--idempotency-key` makes a retry safe |
| openemail events send-batch <events> | Record up to 100 events from a JSON file, and print which were accepted and which were refused |
| openemail events list-names | The event names the workspace has sent, for choosing one in a trigger |
| openemail contacts list-events <email> | The events one contact did, newest first. `--name` narrows it to one event |

**Terminal**

```
openemail events send --data '{"name":"order.placed","email":"ada@example.com","properties":{"orderId":"AC-4192"}}' --idempotency-key order:AC-4192:placed
openemail events send-batch @events.json
openemail contacts list-events ada@example.com --name order.placed
```

Properties go in the JSON body, so send an event that has them with `--data`. Events are kept for 90 days.