Wie Automatisierungen funktionieren

Eine definition hat einen trigger, den Schritt entry und eine Liste von steps. Jeder Schritt hat einen key, der in der Automatisierung eindeutig ist: ein Kleinbuchstabe, gefolgt von 2 bis 23 Kleinbuchstaben oder Ziffern. Ein Schritt nennt seinen Nachfolger in next, und ein branch nennt zwei, yes und no. null beendet diesen Pfad. Die Schritte bilden einen Baum, kein Schritt wird also von zwei Stellen aus erreicht, und nichts führt zurück. Eine Automatisierung fasst bis zu 50 Schritte, mit Verzweigungen in höchstens 5 Ebenen.

• —audience_joined: Ein Kontakt wird zu audienceId hinzugefügt. Per Import hinzugefügte Kontakte bleiben außen vor, sofern includeImported nicht true ist.
• —form_submitted: Eine Person meldet sich über das Formular formId an. Bei Double-Opt-in tritt sie ein, sobald sie bestätigt.
• —event: Ihr Code sendet ein Ereignis namens eventName. Bis zu 5 filters auf seine Eigenschaften grenzen ein, wer eintritt.
• —date: Für jedes Mitglied von audienceId kommt ein Tag. field ist birthday oder joined, der Jahrestag des Beitritts zu dieser Zielgruppe. offsetDays verschiebt ihn um bis zu ein Jahr: negativ für Tage davor, positiv für Tage danach.
• —manual: Niemand tritt von selbst ein. Sie nehmen Personen in der App oder über den Endpunkt zum Aufnehmen auf.

Ein Wert in props oder update_field kommt aus einer von drei Quellen: { "source": "static", "value": "…" }, { "source": "contact", "field": "firstName" } für email, name, firstName, lastName oder attributes.<key> und { "source": "event", "path": "orderId" } für eine Eigenschaft des Ereignisses, das den Durchlauf gestartet hat.

Speichern ändert die definition des Entwurfs. Nichts läuft, bis POST /automations/{id}/publish den Entwurf als nummerierte Version einfriert, die published dann zeigt. Personen, die bereits darin sind, schließen mit der Version ab, mit der sie eingetreten sind, und wer danach eintritt, erhält die neue. hasUnpublishedChanges zeigt an, dass sich der Entwurf weiterentwickelt hat.

• —draft: nie veröffentlicht. Niemand tritt ein.
• —live: veröffentlicht und in Betrieb.
• —paused: Niemand tritt ein, und alle darin bleiben, wo sie sind. pausedReason nennt den Grund: manual oder ein Problem, auf das die Engine gestoßen ist, etwa sender_refused oder template_unavailable.
• —archived: endgültig stillgelegt. Alle darin verlassen sie, und der Verlauf bleibt.

settings sind getrennt und gelten, sobald sie gespeichert sind: die timezone, ein sendWindow, außerhalb dessen E-Mails warten, reentryDays, bevor dieselbe Person erneut eintreten darf (null bedeutet einmal), exitOnLeave, um Personen herauszunehmen, die die Zielgruppe des Auslösers verlassen, und listAudienceId, die Zielgruppe, in der eine Abmeldung erfasst wird.

problems listet auf, was am Entwurf nicht stimmt, jeweils mit einem code, dem path des Feldes, dem stepKey und der Angabe, ob es blocking ist. Ein Entwurf mit einem blockierenden Problem kann nicht veröffentlicht werden.

Jede Person, die eintritt, erhält eine Teilnahme. Sie ist active, solange die Person die Schritte durchläuft, completed, wenn sie das Ende eines Pfads erreicht, und exited, wenn sie vorzeitig austritt, mit einem exitReason: exit_step, unsubscribed, suppressed, left_audience, removed, archived oder failed.

• —Schritte laufen innerhalb von etwa 15 Sekunden, nachdem sie fällig werden. Eine Person erhält im selben Durchgang nie zwei E-Mails aus einer Automatisierung.
• —E-Mails aus Automatisierungen sind Marketing-Mail, daher trägt jede einen Abmeldelink. Wer sich abmeldet, verlässt die Automatisierungen, die an diese Liste senden, und wessen Adresse unzustellbar war oder sich beschwert hat, tritt beim nächsten Schritt aus.
• —Eine E-Mail, deren Adresse keine Mail empfangen kann, wird übersprungen, und die Person geht zum nächsten Schritt weiter.
• —Wenn ein Versand für alle abgelehnt wird, etwa bei einem Absender, der seine Domain verloren hat, oder einer Vorlage, deren Veröffentlichung zurückgenommen wurde, pausiert die Automatisierung, und pausedReason nennt den Grund.

POST /events erfasst, dass ein Kontakt etwas getan hat: order.placed, trial.started, plan.upgraded. Ein Ereignis startet jede aktive Automatisierung, deren Auslöser es nennt, lässt alle weitergehen, die darauf warten, und beantwortet die event-Frage einer Verzweigung. Ereignisse werden 90 Tage aufbewahrt.

• —Lesen erfordert automations:read und Ändern erfordert automations:write. Veröffentlichen, Fortsetzen und das Senden eines Tests erfordern außerdem emails:send, weil die Automatisierung dadurch Mail sendet.
• —Ein Ereignis zu senden erfordert contacts:write, und die Ereignisse eines Kontakts zu lesen erfordert contacts:read.
• —Ein API-Schlüssel und der Inhaber sehen jede Automatisierung im Workspace. Eine App, die ein Mitglied verbunden hat, sieht die, die dieses Mitglied erstellt hat.
• —Das Löschen einer Automatisierung verlangt von einer OAuth-App einen Bestätigungscode. Ein API-Schlüssel braucht nie einen.
• —Ein Tarif erlaubt 1 aktive Automatisierung bei Free, 10 bei Starter, 50 bei Business und beliebig viele bei Enterprise. Ein Workspace fasst standardmäßig 100 Automatisierungen.

Die Webhooks automation.entered, automation.exited und automation.paused melden Ihren Systemen, wer eingetreten ist, wer ausgetreten ist und wann eine Automatisierung angehalten hat. Das Archivieren einer Automatisierung beendet alle darin, ohne ein automation.exited-Ereignis für jede Person.

Alles hier gibt es auch im SDK als openemail.automations und openemail.events und in der CLI als openemail automations und openemail events. Der MCP-Server hat Automatisierungs-Tools, sodass ein Agent eine Automatisierung erstellen, veröffentlichen und im Blick behalten kann, wer darin ist.