자동화의 작동 방식
자동화는 어떤 일이 생길 때마다 한 사람씩 메일을 보냅니다. 누군가 목록에 가입하거나, 양식을 작성하거나, 제품에서 무언가를 하거나, 생일을 맞을 때입니다. 경로를 한 번 정해 두면 각자 자기 속도로 그 길을 갑니다.
트리거와 단계 트리
definition에는 trigger, entry 단계, steps 목록이 있습니다. 각 단계에는 자동화 안에서 고유한 key가 있으며, 소문자 하나 뒤에 소문자나 숫자가 2자에서 23자 이어지는 형식입니다. 단계는 뒤따르는 단계를 next로 지정하고, branch는 yes와 no 둘을 지정합니다. null은 그 경로를 끝냅니다. 단계는 트리를 이루므로 두 곳에서 도달하는 단계는 없고 되돌아가는 것도 없습니다. 자동화는 단계를 최대 50개까지 가지며, 분기는 최대 5겹까지 중첩할 수 있습니다.
audience_joined: 연락처가audienceId에 추가됩니다. 가져오기로 추가된 연락처는includeImported가 true가 아니면 제외됩니다.form_submitted: 사람이formId양식으로 가입합니다. 더블 옵트인이면 확인하는 시점에 들어옵니다.event: 코드가eventName이라는 이름의 이벤트를 보냅니다. 속성에 거는filters를 최대 5개까지 써서 들어올 사람을 좁힐 수 있습니다.date:audienceId의 각 멤버에게 그날이 찾아옵니다.field는birthday또는 그 오디언스에 가입한 날의 기념일인joined입니다.offsetDays로 최대 1년까지 옮길 수 있습니다. 음수는 며칠 전, 양수는 며칠 후입니다.manual: 아무도 저절로 들어오지 않습니다. 앱에서, 또는 추가 엔드포인트로 사람을 추가합니다.
| 단계 | 하는 일 |
|---|---|
| send_email | templateId의 게시된 버전을 이 워크스페이스의 주소인 from에서 보냅니다. props는 템플릿 값을 채우고, subject는 템플릿 제목을 대체하며 {{firstName|there}} 같은 병합 필드를 쓸 수 있습니다 |
| wait | 사람을 붙잡아 둡니다. duration 동안, until로 지정한 다음 요일과 시각까지, 또는 그 사람이 해야 하는 event가 일어날 때까지 기다리며, timeout이 지나면 그대로 다음으로 넘어갑니다 |
| branch | 질문 하나를 던져 그 사람을 yes 또는 no로 보냅니다. 질문은 앞선 이메일 단계에 대한 email_opened 또는 email_clicked, in_audience, 연락처의 field, 또는 withinDays일 안에 한 event입니다 |
| add_to_audience, remove_from_audience | 연락처가 속한 오디언스를 바꿉니다 |
| update_field | 연락처에 값을 기록합니다 |
| webhook | automation.webhook 이벤트로 웹훅 엔드포인트 중 하나를 호출합니다 |
| exit | 경로를 일찍 끝냅니다. 완료가 아니라 나간 것으로 집계됩니다 |
props나 update_field의 값은 세 곳 중 하나에서 옵니다. { "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은 한 번만), 트리거 오디언스를 떠난 사람을 내보내는 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 키에는 인증 코드가 필요 없습니다.
- 요금제별로 게시 중 자동화는 Free에서 1개, Starter에서 10개, Business에서 50개, Enterprise에서는 제한 없이 둘 수 있습니다. 워크스페이스는 기본적으로 자동화를 100개까지 가질 수 있습니다.
automation.entered, automation.exited, automation.paused 웹훅은 누가 들어오고 누가 나갔는지, 자동화가 언제 멈췄는지를 시스템에 알려 줍니다. 자동화를 보관하면 사람마다 automation.exited 이벤트를 보내지 않고 그 안의 모든 사람을 끝냅니다.
코드, 터미널, 에이전트에서
여기 있는 모든 것은 SDK에서는 openemail.automations와 openemail.events로, CLI에서는 openemail automations와 openemail events로도 쓸 수 있습니다. MCP 서버에는 자동화 도구가 있어, 에이전트가 자동화를 만들고 게시하고 누가 참여 중인지 지켜볼 수 있습니다.