CLI
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.
nextmail automations create --name "Welcome series" --starter welcome-seriesnextmail automations update aut_5c1e9a7b3d2f48e6a0b4c7d1 --data @welcome.jsonnextmail automations publish aut_5c1e9a7b3d2f48e6a0b4c7d1nextmail automations stats aut_5c1e9a7b3d2f48e6a0b4c7d1The definition is JSON, so write it to a file and pass it with --data @file. nextmail automations get <id> --json prints the current one, and its problems lists what still stops it from being published.
Automations
| Command | What it does |
|---|---|
| nextmail automations list | One page of the automations, most recently changed first. --status narrows it to draft, live, paused or archived |
| nextmail automations create --name <value> | Make a draft from --starter, from a definition in --data, or an empty one |
| nextmail automations get <id> | One automation with its draft, its live version, its settings and what is wrong with the draft |
| nextmail 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 |
| nextmail automations publish <id> | Freeze the draft as the next version and turn the automation on |
| nextmail automations pause <id> | Stop a live automation. Everybody inside holds where they are |
| nextmail automations resume <id> | Turn a paused automation back on with the version it was running |
| nextmail automations archive <id> | Retire an automation for good and keep its history. Everybody inside leaves |
| nextmail automations duplicate <id> | Copy an automation into a new draft, without its people or numbers |
| nextmail automations delete <id> | Delete an automation and its history after you confirm. A browser sign-in also asks for a verification code |
| nextmail automations list-starters | The starting points a new automation can begin from |
Testing, versions and numbers
| Command | What it does |
|---|---|
| nextmail 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 |
| nextmail automations list-versions <id> | Every version that was published, newest first |
| nextmail automations restore-version <id> <version> | Copy an earlier version back into the draft. Publish to make it run |
| nextmail 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 |
| nextmail automations analytics | Every automation of the workspace side by side over a window. --automation-ids counts some of them, and --since sets where the window starts |
| nextmail automations list-runs <id> | The run log, newest first: who entered, what each step did and who finished. --event, --step-key and --outcome narrow it, and --all reads every page |
People inside an automation
| Command | What it does |
|---|---|
| nextmail 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 |
| nextmail automations get-enrollment <id> <enrollment-id> | One person’s run, with every step it ran and the email each send produced |
| nextmail automations enroll <id> --email <value> | Put a contact into a live automation at its first step. --contact-id names the contact by id instead |
| nextmail automations exit-enrollment <id> <enrollment-id> | Take somebody out before they finish |
nextmail 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 |
|---|---|
| nextmail 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 |
| nextmail events send-batch <events> | Record up to 100 events from a JSON file, and print which were accepted and which were refused |
| nextmail events list-names | The event names the workspace has sent, for choosing one in a trigger |
| nextmail contacts list-events <email> | The events one contact did, newest first. --name narrows it to one event |
nextmail events send --data '{"name":"order.placed","email":"[email protected]","properties":{"orderId":"AC-4192"}}' --idempotency-key order:AC-4192:placednextmail events send-batch @events.jsonnextmail 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.