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.
openemail automations create --name "Welcome series" --starter welcome-seriesopenemail automations update aut_5c1e9a7b3d2f48e6a0b4c7d1 --data @welcome.jsonopenemail automations publish aut_5c1e9a7b3d2f48e6a0b4c7d1openemail automations stats aut_5c1e9a7b3d2f48e6a0b4c7d1The 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 |
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 |
openemail events send --data '{"name":"order.placed","email":"[email protected]","properties":{"orderId":"AC-4192"}}' --idempotency-key order:AC-4192:placedopenemail events send-batch @events.jsonopenemail contacts list-events [email protected] --name order.placedProperties go in the JSON body, so send an event that has them with --data. Events are kept for 90 days.