Comment fonctionnent les automatisations

Une definition a un trigger, l'étape entry et une liste de steps. Chaque étape a une key unique dans l'automatisation : une lettre minuscule suivie de 2 à 23 lettres minuscules ou chiffres. Une étape nomme celle qui la suit dans next, et une branch en nomme deux, yes et no. null termine ce parcours. Les étapes forment un arbre : aucune étape n'est atteinte depuis deux endroits et rien ne revient en arrière. Une automatisation contient jusqu'à 50 étapes, avec des branches imbriquées sur 5 niveaux au plus.

• —audience_joined : un contact est ajouté à audienceId. Les contacts ajoutés par un import sont exclus, sauf si includeImported vaut true.
• —form_submitted : une personne s'inscrit via le formulaire formId. En double opt-in, elle entre quand elle confirme.
• —event : votre code envoie un événement nommé eventName. Jusqu'à 5 filters sur ses propriétés restreignent qui entre.
• —date : un jour arrive pour chaque membre de audienceId. field vaut birthday ou joined, l'anniversaire du jour où il a rejoint cette audience. offsetDays le décale d'un an au plus : négatif pour des jours avant, positif pour des jours après.
• —manual : personne n'entre de soi-même. Vous ajoutez des personnes depuis l'application ou avec le point de terminaison d'inscription.

Une valeur dans props ou update_field vient de l'un de trois endroits : { "source": "static", "value": "…" }, { "source": "contact", "field": "firstName" } pour email, name, firstName, lastName ou attributes.<key>, et { "source": "event", "path": "orderId" } pour une propriété de l'événement qui a démarré le parcours.

Enregistrer modifie la definition du brouillon. Rien ne s'exécute tant que POST /automations/{id}/publish n'a pas figé le brouillon en une version numérotée, que published affiche alors. Les personnes déjà en cours terminent sur la version avec laquelle elles sont entrées, et celles qui entrent ensuite reçoivent la nouvelle. hasUnpublishedChanges indique que le brouillon a évolué depuis.

• —draft : jamais publiée. Personne n'entre.
• —live : publiée et en cours d'exécution.
• —paused : personne n'entre et toutes les personnes en cours restent où elles sont. pausedReason dit pourquoi : manual, ou un problème rencontré par le moteur, comme sender_refused ou template_unavailable.
• —archived : retirée définitivement. Toutes les personnes en cours en sortent, et l'historique reste.

Les settings sont à part et s'appliquent dès leur enregistrement : la timezone, un sendWindow hors duquel les e-mails attendent, reentryDays avant que la même personne puisse entrer de nouveau (null signifie une seule fois), exitOnLeave pour faire sortir les personnes qui quittent l'audience du déclencheur, et listAudienceId, l'audience sur laquelle un désabonnement est enregistré.

problems liste ce qui ne va pas dans le brouillon, chaque problème avec un code, le path du champ, le stepKey et s'il est blocking. Un brouillon avec un problème bloquant ne peut pas être publié.

Chaque personne qui entre reçoit une inscription. Elle est active tant que la personne parcourt les étapes, completed quand elle arrive au bout d'un parcours, et exited quand elle sort avant la fin, avec un exitReason : exit_step, unsubscribed, suppressed, left_audience, removed, archived ou failed.

• —Les étapes s'exécutent environ 15 secondes après leur échéance. Une personne ne reçoit jamais deux e-mails d'une même automatisation dans le même passage.
• —Les e-mails d'automatisation sont du courrier marketing, chacun porte donc un lien de désabonnement. Une personne qui se désabonne quitte les automatisations qui écrivent à cette liste, et une personne dont l'adresse a été rejetée ou qui s'est plainte sort à sa prochaine étape.
• —Un e-mail dont l'adresse ne peut pas recevoir de courrier est ignoré, et la personne passe à l'étape suivante.
• —Quand un envoi est refusé pour tout le monde, par exemple un expéditeur qui a perdu son domaine ou un modèle dépublié, l'automatisation se met en pause et pausedReason dit pourquoi.

POST /events enregistre qu'un contact a fait quelque chose : order.placed, trial.started, plan.upgraded. Un événement démarre chaque automatisation en ligne dont le déclencheur le nomme, fait avancer toute personne qui l'attend, et répond à la question event d'une branche. Les événements sont conservés 90 jours.

• —La lecture nécessite automations:read et la modification automations:write. Publier, reprendre et envoyer un test nécessitent aussi emails:send, parce qu'ils font envoyer du courrier par l'automatisation.
• —Envoyer un événement nécessite contacts:write, et lire les événements d'un contact nécessite contacts:read.
• —Une clé API et le propriétaire voient toutes les automatisations de l'espace de travail. Une application connectée par un membre voit celles que ce membre a créées.
• —Supprimer une automatisation demande un code de vérification à une application OAuth. Une clé API n'en a jamais besoin.
• —Une offre permet 1 automatisation en ligne en Free, 10 en Starter, 50 en Business et un nombre illimité en Enterprise. Un espace de travail peut contenir 100 automatisations par défaut.

Les webhooks automation.entered, automation.exited et automation.paused indiquent à vos systèmes qui est entré, qui est sorti et quand une automatisation s'est arrêtée. Archiver une automatisation met fin au parcours de toutes les personnes en cours, sans événement automation.exited pour chacune.

Tout ce qui figure ici existe aussi dans le SDK avec openemail.automations et openemail.events, et dans la CLI avec openemail automations et openemail events. Le serveur MCP a des outils d'automatisation, un agent peut donc en construire une, la publier et suivre qui est en cours.