Как работают автоматизации

У definition есть trigger, шаг entry и список steps. У каждого шага есть key, уникальный в пределах автоматизации: строчная буква, за которой идут от 2 до 23 строчных букв или цифр. Шаг называет следующий за ним в next, а branch называет два, yes и no. null завершает этот путь. Шаги образуют дерево, поэтому ни в один шаг нельзя попасть из двух мест и ничто не возвращается назад. Автоматизация вмещает до 50 шагов, а глубина ветвлений не превышает 5.

• —audience_joined: контакт добавляется в audienceId. Контакты, добавленные импортом, не учитываются, если includeImported не равен true.
• —form_submitted: человек подписывается через форму formId. При двойном подтверждении он входит, когда подтверждает подписку.
• —event: ваш код отправляет событие с именем eventName. До 5 filters по его свойствам сужают круг тех, кто входит.
• —date: для каждого участника audienceId наступает определённый день. field принимает birthday или joined, годовщину дня, когда он вступил в эту аудиторию. offsetDays сдвигает дату не более чем на год: отрицательное значение для дней до, положительное для дней после.
• —manual: сам никто не входит. Вы добавляете людей из приложения или через эндпоинт добавления.

Значение в props или update_field берётся из одного из трёх мест: { "source": "static", "value": "…" }, { "source": "contact", "field": "firstName" } для email, name, firstName, lastName или attributes.<key> и { "source": "event", "path": "orderId" } для свойства события, которое запустило прохождение.

Сохранение меняет definition черновика. Ничего не выполняется, пока POST /automations/{id}/publish не зафиксирует черновик как пронумерованную версию, которую затем показывает published. Те, кто уже внутри, заканчивают на версии, с которой вошли, а те, кто входит позже, получают новую. hasUnpublishedChanges говорит, что черновик ушёл вперёд.

• —draft: ни разу не публиковалась. Никто не входит.
• —live: опубликована и работает.
• —paused: никто не входит, а все, кто внутри, остаются на своих местах. pausedReason объясняет почему: manual или проблема, с которой столкнулся движок, например sender_refused или template_unavailable.
• —archived: навсегда выведена из работы. Все, кто внутри, выходят, а история остаётся.

settings существуют отдельно и применяются сразу после сохранения: timezone, sendWindow, вне которого письма ждут, reentryDays до того, как тот же человек сможет войти снова (null означает один раз), exitOnLeave, чтобы убирать тех, кто покинул аудиторию триггера, и listAudienceId, аудитория, в которую записывается отписка.

problems перечисляет, что не так с черновиком: у каждой проблемы есть code, path поля, stepKey и признак blocking. Черновик с блокирующей проблемой нельзя опубликовать.

Каждый, кто входит, получает участие. Оно active, пока человек идёт по шагам, completed, когда он доходит до конца пути, и exited, когда он выходит раньше, с exitReason: exit_step, unsubscribed, suppressed, left_audience, removed, archived или failed.

• —Шаги выполняются примерно в течение 15 секунд после наступления срока. За один проход человек никогда не получает два письма из одной автоматизации.
• —Письма автоматизаций относятся к маркетинговым, поэтому в каждом есть ссылка для отписки. Тот, кто отписался, выходит из автоматизаций, которые пишут в этот список, а тот, чей адрес вернул письмо или пожаловался, выходит на следующем шаге.
• —Письмо, адрес которого не может принимать почту, пропускается, и человек переходит к следующему шагу.
• —Когда отправка отклоняется для всех, например отправитель потерял домен или шаблон сняли с публикации, автоматизация приостанавливается, а pausedReason объясняет почему.

POST /events записывает, что контакт что-то сделал: order.placed, trial.started, plan.upgraded. Событие запускает каждую активную автоматизацию, триггер которой его называет, продвигает дальше всех, кто его ждёт, и отвечает на вопрос event в ветвлении. События хранятся 90 дней.

• —Для чтения нужен automations:read, а для изменения automations:write. Публикация, возобновление и отправка теста требуют ещё и emails:send, потому что заставляют автоматизацию отправлять почту.
• —Для отправки события нужен contacts:write, а для чтения событий контакта contacts:read.
• —API-ключ и владелец видят все автоматизации рабочего пространства. Приложение, подключённое участником, видит те, что создал этот участник.
• —Удаление автоматизации требует от приложения OAuth код подтверждения. API-ключу он никогда не нужен.
• —Тариф допускает 1 активную автоматизацию на Free, 10 на Starter, 50 на Business и сколько угодно на Enterprise. По умолчанию рабочее пространство вмещает 100 автоматизаций.

Вебхуки automation.entered, automation.exited и automation.paused сообщают вашим системам, кто вошёл, кто вышел и когда автоматизация остановилась. Архивирование автоматизации завершает путь всех, кто в ней, без события automation.exited для каждого человека.

Всё, что здесь описано, есть и в SDK как openemail.automations и openemail.events, и в CLI как openemail automations и openemail events. У MCP-сервера есть инструменты автоматизаций, поэтому агент может собрать автоматизацию, опубликовать её и следить, кто внутри.