オートメーションのしくみ

definition は、trigger、entry ステップ、steps のリストで構成されます。各ステップには、オートメーション内で一意の key があります。英小文字 1 文字に、英小文字または数字が 2 文字から 23 文字続く形式です。ステップは次に続くステップを next で指定し、branch は yes と no の 2 つを指定します。null を指定すると、その経路はそこで終わります。ステップはツリーを構成するため、2 か所から到達するステップはなく、前に戻るループもありません。1 つのオートメーションが持てるステップは最大 50 個、分岐の深さは最大 5 段です。

• —audience_joined: 連絡先が audienceId に追加されます。includeImported が true でない限り、インポートで追加された連絡先は対象外です。
• —form_submitted: 人がフォーム formId から登録します。ダブルオプトインの場合は、確認した時点で入ります。
• —event: あなたのコードが eventName という名前のイベントを送信します。プロパティに対する最大 5 つの filters で、入る人を絞り込めます。
• —date: audienceId の各メンバーに、その日が訪れます。field は birthday か、そのオーディエンスに参加した日の記念日である joined です。offsetDays で最大 1 年までずらせます。負の値は何日前、正の値は何日後を表します。
• —manual: 自動で入る人はいません。アプリから、または追加用のエンドポイントで人を追加します。

props または update_field の値は、次の 3 つのいずれかから取得します。{ "source": "static", "value": "…" }、email、name、firstName、lastName、attributes.<key> を対象とする { "source": "contact", "field": "firstName" }、そして実行を開始したイベントのプロパティを対象とする { "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 は 1 回だけ）、トリガーのオーディエンスを離れた人を外す exitOnLeave、配信停止を記録するオーディエンスである listAudienceId があります。

problems は下書きの問題点の一覧で、それぞれに code、フィールドの path、stepKey、そして blocking かどうかが付きます。公開を妨げる問題のある下書きは公開できません。

入った人それぞれに参加状況が作られます。ステップを進んでいる間は active、経路の終わりまで進むと completed、途中で退出すると exited になり、exitReason が付きます。値は exit_step、unsubscribed、suppressed、left_audience、removed、archived、failed のいずれかです。

• —ステップは、実行時刻になってから約 15 秒以内に実行されます。1 回の処理で、同じオートメーションから 1 人に 2 通のメールが届くことはありません。
• —オートメーションのメールはマーケティングメールなので、どのメールにも配信停止リンクが付きます。配信停止した人は、そのリストにメールを送るオートメーションから退出し、アドレスがバウンスした人や苦情を申し立てた人は次のステップで退出します。
• —アドレスがメールを受信できない場合、そのメールはスキップされ、その人は次のステップへ進みます。
• —ドメインを失った送信者や非公開になったテンプレートのように、全員への送信が拒否される場合、オートメーションは一時停止し、pausedReason が理由を示します。

POST /events は、連絡先が何かをしたことを記録します。たとえば order.placed、trial.started、plan.upgraded です。イベントは、トリガーでそれを指定しているすべての公開中のオートメーションを開始し、それを待っている人を先へ進め、分岐の event の問いに答えます。イベントは 90 日間保持されます。

• —読み取りには automations:read、変更には automations:write が必要です。公開、再開、テスト送信は、オートメーションにメールを送信させるため、emails:send も必要です。
• —イベントの送信には contacts:write、連絡先のイベントの読み取りには contacts:read が必要です。
• —API キーとオーナーには、ワークスペースのすべてのオートメーションが見えます。メンバーが接続したアプリに見えるのは、そのメンバーが作成したものだけです。
• —オートメーションを削除するときは、OAuth アプリに確認コードが求められます。API キーには必要ありません。
• —公開できるオートメーションの数は、Free で 1 件、Starter で 10 件、Business で 50 件、Enterprise では無制限です。1 つのワークスペースが持てるオートメーションは、既定で 100 件です。

automation.entered、automation.exited、automation.paused の Webhook は、誰が入り、誰が出て、オートメーションがいつ止まったかをあなたのシステムに伝えます。オートメーションをアーカイブすると、1 人ずつの automation.exited イベントは送られずに、参加中の全員が終了します。

ここにあるものはすべて、SDK では openemail.automations と openemail.events、CLI では openemail automations と openemail events として使えます。MCP サーバーにはオートメーションのツールがあり、エージェントがオートメーションを組み立て、公開し、誰が参加中かを確認できます。