How automations work

A definition has a trigger, the entry step and a list of steps. Each step has a key that is unique in the automation: a lower-case letter followed by 2 to 23 lower-case letters or digits. A step names the one that follows it in next, and a branch names two, yes and no. null ends that path. The steps form a tree, so no step is reached from two places and nothing loops back. An automation holds up to 50 steps, with branches at most 5 deep.

• —audience_joined: a contact is added to audienceId. Contacts added by an import are left out unless includeImported is true.
• —form_submitted: a person signs up through the form formId. With double opt-in, they enter when they confirm.
• —event: your code sends an event named eventName. Up to 5 filters on its properties narrow who enters.
• —date: a day arrives for each member of audienceId. field is birthday or joined, the anniversary of the day they joined that audience. offsetDays moves it by up to a year: negative for days before, positive for days after.
• —manual: nobody enters by themselves. You add people from the app or with the enroll endpoint.

A value in props or update_field comes from one of three places: { "source": "static", "value": "…" }, { "source": "contact", "field": "firstName" } for email, name, firstName, lastName or attributes.<key>, and { "source": "event", "path": "orderId" } for a property of the event that started the run.

Saving changes the draft definition. Nothing runs until POST /automations/{id}/publish freezes the draft as a numbered version, which published then shows. People who are already inside finish on the version they entered with, and people who enter afterwards get the new one. hasUnpublishedChanges says the draft has moved on.

• —draft: never published. Nobody enters.
• —live: published and running.
• —paused: nobody enters and everybody inside holds where they are. pausedReason says why: manual, or a problem the engine met, such as sender_refused or template_unavailable.
• —archived: retired for good. Everybody inside leaves, and the history stays.

settings are separate and apply as soon as they are saved: the timezone, a sendWindow outside which emails wait, reentryDays before the same person may enter again (null means once), exitOnLeave to drop people who leave the trigger audience, and listAudienceId, the audience an unsubscribe is recorded on.

problems lists what is wrong with the draft, each with a code, the path of the field, the stepKey and whether it is blocking. A draft with a blocking problem cannot be published.

Each person who enters gets an enrollment. It is active while they move through the steps, completed when they run off the end of a path, and exited when they leave early, with an exitReason: exit_step, unsubscribed, suppressed, left_audience, removed, archived or failed.

• —Steps run within about 15 seconds of becoming due. A person never gets two emails from one automation in the same pass.
• —Automation emails are marketing mail, so every one carries an unsubscribe link. A person who unsubscribes leaves the automations that mail that list, and one whose address bounced or complained leaves at their next step.
• —An email whose address cannot receive mail is skipped, and the person carries on to the next step.
• —When a send is refused for everybody, such as a sender that lost its domain or a template that was unpublished, the automation pauses and pausedReason says why.

POST /events records that a contact did something: order.placed, trial.started, plan.upgraded. An event starts every live automation whose trigger names it, moves on anybody waiting for it, and answers the event question of a branch. Events are kept for 90 days.

• —Reading needs automations:read and changing needs automations:write. Publishing, resuming and sending a test also need emails:send, because they make the automation send mail.
• —Sending an event needs contacts:write, and reading a contact’s events needs contacts:read.
• —An API key and the owner see every automation in the workspace. An app a member connected sees the ones that member made.
• —Deleting an automation asks an OAuth app for a verification code. An API key never needs one.
• —A plan allows 1 live automation on Free, 10 on Starter, 50 on Business and any number on Enterprise. A workspace holds 100 automations by default.

automation.entered, automation.exited and automation.paused webhooks tell your systems who went in, who came out and when an automation stopped. Archiving an automation ends everybody in it without an automation.exited event for each person.

Everything here is also in the SDK as openemail.automations and openemail.events, and in the CLI as openemail automations and openemail events. The MCP server has automation tools, so an agent can build one, publish it and watch who is inside.