템플릿, 규칙, 웹훅

이 세 네임스페이스가 있으면 아무도 지켜보지 않아도 메일함이 돌아갑니다. templates는 여러 번 보내는 본문을 저장하고, rules는 도착하는 메일을 정리하며, webhooks는 무슨 일이 있었는지 자체 서버에 알립니다. 각 명령은 케밥 케이스 이름을 가진 SDK 메서드이므로 webhooks.rotateSecret은 openemail webhooks rotate-secret이며, 다른 모든 리소스 명령처럼 인수와 플래그를 읽습니다.

이 페이지는 모든 명령과 스크립트로 만들기 전에 알아 둘 점을 나열합니다. 모든 인수와 플래그를 타입, 필요한 범위, 엔드포인트, 반환값과 함께 보려면 openemail <namespace> <verb> --help를 실행하세요. --json을 붙이면 같은 페이지를 JSON으로 받습니다.

openemail templates --helpopenemail rules create --helpopenemail webhooks replay-delivery --help --json

한 번 저장해서 여러 번 보내는 본문으로, 버전, 미리 보기, 타입이 있는 props를 갖습니다. <id-or-slug>를 받는 모든 명령은 tpl_ ID나 슬러그를 받습니다. 템플릿 이름을 바꿔도 슬러그는 바뀌지 않으므로 스크립트에서는 슬러그를 고정하세요.

• —보관된 템플릿은 template_archived로 보내기를 거부합니다. publish하면 다시 활성이 됩니다.
• —워크스페이스에는 보관된 것을 포함해 템플릿을 최대 200개까지 둘 수 있으므로, 자리를 만들려면 삭제하는 수밖에 없습니다.
• —예약되었거나 대기 중인 브로드캐스트가 템플릿을 가리키는 동안 delete는 template_in_use로 거부됩니다.

도착하는 메일에 대해 rules list가 보여 주는 순서대로 평가되는 조건과 동작입니다. 규칙은 켜져 있는 동안 도착한 메일에만 작동합니다. 이미 메일함에 있는 메일에 규칙을 적용하는 명령은 없으며, 무엇을 잡을지 보려면 rules test를 씁니다. 규칙 ID는 rul_로 시작합니다.

--conditions는 { field, op, value } 객체의 목록으로, --match all이나 --match any로 묶이며, value는 항상 문자열이고 negate: true는 조건 하나를 뒤집습니다. --actions는 { type, value } 객체의 목록으로, 순서대로 적용됩니다. 규칙에는 조건 1개에서 20개, 동작 1개에서 10개가 들어가며, 메일함에는 규칙을 최대 100개까지 둘 수 있습니다.

• —조건 필드: from, from_domain, envelope_from, to, cc, bcc, recipient, reply_to, delivered_to, subject, body, header, list_id, attachment_name, attachment_type, has_attachment, attachment_size, message_size, spam, hour, weekday.
• —연산자: matches, contains, equals, starts_with, ends_with, gt, lt. gt와 lt는 숫자 필드에서만 동작하며, has_attachment와 spam은 true나 false와 함께 equals만 받습니다.
• —동작 종류: label, remove_label, archive, mark_read, star, spam, trash, forward, reply, block_sender, reject. label과 remove_label은 USER_RECEIPTS 같은 라벨 ID를, forward는 주소를, reply는 템플릿 ID나 슬러그를 받습니다.
• —from_domain은 하위 도메인도 맞추며, hour와 weekday는 UTC 기준으로 읽고 일요일은 0입니다.
• —reject 동작이 있는 규칙은 envelope_from도 검사해야 하며, 그렇지 않으면 reject_needs_envelope로 거부됩니다.

서명된 메일함 이벤트를 받는 자체 서버의 엔드포인트로, 서명 시크릿, 전달 로그, 모든 변경의 감사 로그가 함께 있습니다. 엔드포인트 ID는 whe_, 전달 ID는 whd_로 시작합니다.

--event-types를 빼면 엔드포인트는 기본 집합, 즉 email.replied를 제외한 email.* 이벤트를 받습니다. email.replied, domain.* 이벤트, suppression.* 이벤트는 지정할 때만 전달됩니다. --address-allowlist와 --domain-allowlist는 API 키를 좁히는 것과 같은 방식으로 엔드포인트를 일부 주소나 도메인으로 좁힙니다.

• —지원팀이 한도를 올리지 않았다면 워크스페이스에는 엔드포인트를 10개까지 둘 수 있습니다.
• —전달에 100번 연속 실패한 엔드포인트는 서버가 끄며, webhooks update <id> --enabled로 되살립니다.
• —브라우저 로그인에서는 워크스페이스 소유자만 get-delivery로 전달을 읽을 수 있습니다. 그 밖의 사람은 owner_only와 종료 코드 4를 받습니다.

templates preview는 같은 값으로 보냈을 때 나올 결과를 초안까지 포함해 정확히 렌더링하며, templates:read만 필요하므로 읽기 전용 키로도 실행할 수 있습니다. send라면 거부했을 필수 prop 누락을 경고로 보고하므로, 경고가 하나라도 있으면 빌드를 실패시키세요. 이미 게시된 head를 게시해도 아무것도 바뀌지 않으므로 publish는 배포할 때마다 해도 안전합니다.

draft=$(openemail templates get order-shipped --json | jq .latestVersion)openemail templates preview order-shipped --template-version "$draft" \  --props '{"orderId":"AC-4192","customer":"Ada"}' --json | jq -e '.warnings == []'openemail templates publish order-shipped

버전을 고정해서 내일 게시되는 수정본이 이 코드가 보내는 내용을 바꾸지 않게 하고, 보내기를 일으킨 원인에서 멱등 키를 가져와 넘겨서 응답을 잃은 뒤의 재시도가 두 번째 메시지를 보내는 대신 첫 메시지를 재생하게 하세요. --dry-run은 메서드, URL, 자격 증명을 가린 헤더, 본문을 출력하고, 아무것도 보내지 않고 코드 0으로 종료합니다. 보내려면 --dry-run 없이 다시 실행하세요.

openemail templates send order-shipped \  --from 'Acme <[email protected]>' \  --to [email protected] \  --template-version 5 \  --props '{"orderId":"AC-4192","customer":"Ada"}' \  --idempotency-key order-shipped:AC-4192 \  --dry-run

규칙을 꺼진 상태로 만들고, 최근 메일로 시험 실행한 뒤, 의도한 것을 잡으면 켜세요. 브라우저 로그인에서는 rules create와 rules update가 스크립트는 입력할 수 없는 인증 코드를 요구하므로, 먼저 openemail verify를 실행하세요. 이후 60분 동안 그 프로필은 묻지 않고 실행합니다.

[  { "field": "from_domain", "op": "equals", "value": "stripe.com" },  { "field": "has_attachment", "op": "equals", "value": "true" }]

[  { "type": "label", "value": "USER_RECEIPTS" },  { "type": "archive" }]

openemail verifyrule=$(openemail rules create --name 'Stripe receipts' \  --conditions @conditions.json --actions @actions.json --no-enabled --json | jq -r .id)openemail rules test "$rule" --days 30 --limit 100openemail rules update "$rule" --enabled

rules test의 일치 결과보다 경고를 먼저 읽으세요. field_unevaluable은 조건이 저장된 메일에 더 이상 없는 무언가를 읽어서 테스트가 판단하지 못했다는 뜻이고, forward_unverified는 전달 대상이 여기서 호스팅되지 않는다는 뜻입니다. wouldApply는 규칙이 선언한 것을 나열합니다. 확인하지 않은 주소로의 전달은 실제 메일이 도착하면 여전히 실패합니다.

rules reorder는 메일함의 모든 규칙을 정확히 한 번씩 받습니다. 빠지거나 두 번 적힌 규칙이 있으면 거부되고 아무것도 움직이지 않습니다. rules list는 실행 순서대로 ID를 반환하므로, 맨 앞에 둘 규칙을 나머지 앞에 놓으세요.

first=rul_4f1c9a2b7d3e8f6a0b5c1d2eopenemail rules reorder "$first" $(openemail rules list --all --ndjson \  | jq -r --arg first "$first" 'select(.id != $first) | .id')openemail rules list-runs --thread-id CAHk7pQ2x9LmZ4 --json | jq '.items[] | {ruleName, actions, failures}'

list-runs는 실제로 일어난 일의 기록입니다. 각 행은 규칙 하나가 메시지 하나에 일치한 것으로, 효과가 있었던 동작과 failures에는 메일함이 거절한 동작이 있습니다. 예를 들어 그날 이미 답장한 보낸 사람에게 하는 답장입니다. 각 행은 그 시점의 규칙 이름을 보관하므로, 이후 삭제한 규칙에도 --rule-id가 동작합니다.

webhooks create는 서명 시크릿을 한 번 보여 주며, 이후 어떤 명령도 다시 보여 주지 않습니다. --json을 주면 시크릿은 stdout의 JSON에 들어 있고, 저장하라는 안내는 stderr로 가므로 출력은 여전히 파싱됩니다. webhooks test는 엔드포인트가 무엇을 구독하든 서명된 합성 email.sent 이벤트를 보내며, 메일은 보내지 않습니다.

openemail verifyopenemail webhooks create --url https://hooks.acme.com/openemail \  --event-types email.received,email.bounced,email.complained \  --description 'Support desk sync' --json > endpoint.jsonjq -r .secret endpoint.jsonopenemail webhooks test "$(jq -r .id endpoint.json)" --json | jq .deliveryrm endpoint.json

파일을 지우기 전에 시크릿을 시크릿 저장소에 넣으세요. test는 서버가 실패해도 코드 0으로 종료하므로 delivery.status를 읽으세요. 2xx 응답이면 delivered, 그 밖에는 리디렉션을 포함해 모두 failed입니다. 리디렉션은 절대 따라가지 않기 때문입니다. responseCode가 null이면 응답이 아예 오지 않은 것입니다.

자체 서버에 장애가 있었다면, 모든 엔드포인트에서 실패한 것을 나열하고, 재전송이 받아들여질지 확인한 뒤 이벤트를 다시 보내세요. 재전송은 같은 이벤트 ID를 담으므로, 이미 처리한 ID를 버리는 수신기는 이를 이미 아는 이벤트로 취급합니다.

openemail webhooks list-workspace-deliveries --status failed --since 2026-09-26T00:00:00Z --all --ndjson \  | jq -r '[.endpointId, .id, .eventType, (.responseCode // "no answer")] | @tsv'openemail webhooks get-delivery whe_3f9c2a7b1e4d8f60a5c7b92d whd_8c1e4a7f2b9d3e6a0c5f1b28 --json | jq .replayRefusalopenemail webhooks replay-delivery whe_3f9c2a7b1e4d8f60a5c7b92d whd_8c1e4a7f2b9d3e6a0c5f1b28

• —--since와 --until은 ISO 8601 시각을 받습니다.
• —nextAttemptAt에 시각이 있는 실패 행에는 아직 자동 재시도가 남아 있습니다.
• —재전송이 나갈 수 있으면 replayRefusal은 null이고, 그렇지 않으면 엔드포인트가 꺼져 있을 때의 webhook_disabled처럼 거부될 이유를 알려 줍니다.
• —재전송은 이벤트 하나씩 합니다. 실패한 전달을 모두 다시 보내는 명령은 없습니다.

브라우저 로그인에서는 이 명령 중 네 개가 웹 앱처럼 무엇이든 바꾸기 전에 인증 코드를 요구합니다. rules create, rules update, webhooks create, webhooks update입니다. API 키는 요구받지 않습니다. 이 페이지의 다른 모든 명령은 삭제와 webhooks rotate-secret을 포함해 코드 없이 실행됩니다.

• —터미널에서는 CLI가 여섯 자리 코드를 이메일로 보내거나, 2단계 로그인이 켜져 있으면 인증 앱의 코드를 요구한 뒤 명령을 한 번 실행합니다.
• —--json이나 --no-input을 주었거나, CI이거나, 터미널이 없는 무인 실행에서는 아무도 코드를 입력할 수 없으므로 명령이 종료 코드 4로 멈추고 아무것도 바꾸지 않습니다. 먼저 openemail verify를 실행하면 그 프로필은 60분 동안 코드가 필요 없습니다.
• —--yes는 삭제를 확인하지만 코드를 건너뛰지는 않습니다.

여기의 일곱 명령은 무언가를 제거하거나 덮어쓰므로 먼저 확인을 요청합니다. templates delete, templates delete-version, templates replace-content, templates restore-version, rules delete, webhooks delete, webhooks rotate-secret입니다. 무인 실행에서는 --yes를 주지 않으면 각각 종료 코드 2로 멈춥니다.

$ openemail webhooks delete whe_3f9c2a7b1e4d8f60a5c7b92d --no-input✗ Refusing to run unattended. Pass --yes to confirm.$ openemail webhooks delete whe_3f9c2a7b1e4d8f60a5c7b92d --yes

--dry-run은 무언가를 바꿀 첫 요청을 출력하고, 보내거나 확인을 묻지 않고 코드 0으로 종료합니다. --json을 주면 { dryRun, request } 문서 하나를 출력합니다. rules test, templates render, templates preview는 아무것도 바꾸지 않지만 POST 요청이므로, 드라이 런은 이를 실행하는 대신 출력합니다.

• —templates list, templates list-versions, rules list, rules list-runs, 그리고 모든 webhooks list… 명령은 한 번에 한 페이지를 읽으며, --limit로 최대 100개를 요청하지 않으면 25행입니다. 터미널은 다음 페이지를 위해 넘길 --cursor를 보여 줍니다.
• —--all은 모든 페이지를 읽고, --max <n>은 그만큼 읽고 멈추며, --ndjson은 한 줄에 JSON 객체 하나를 출력합니다. --json을 주면 목록은 --all일 때도 { items, hasMore, nextCursor } 문서 하나를 출력합니다.
• —커서는 받을 때와 같은 필터와 정렬로 돌려주세요. 그 밖의 것은 invalid_cursor와 종료 코드 7로 거부됩니다.
• —templates list-sends는 대신 --page와 --page-size로 번호로 페이지를 넘기고, total을 보고하며, --all이 없습니다. 메일이 나가는 동안 페이지 번호가 밀리므로, 깊이 넘기기보다 --days나 --minutes로 기간을 좁히세요.
• —templates list-starters와 templates list-fonts는 전체 목록을 한 번에 반환하며, rules reorder는 모든 규칙을 새 순서의 일반 목록으로 반환합니다.
• —메일함에는 규칙을 최대 100개까지 둘 수 있으므로, rules list --limit 100은 항상 모든 규칙을 한 페이지로 반환합니다.

• —--template-version은 본문 필드 version인데, --version이 CLI 버전을 출력하기 때문에 이름이 바뀌었습니다. get-version, restore-version, delete-version의 <version> 인수는 tplv_ ID가 아니라 버전 번호입니다.
• —--conditions, --actions, --document, --slots, --props를 비롯한 JSON 플래그는 JSON을 인라인, @path로 파일에서, -로 stdin에서 받습니다. --data는 본문 전체를 같은 방식으로 받으며, 함께 준 플래그는 해당 키를 덮어씁니다.
• —--html은 파일이 아니라 마크업 자체를 받으므로, --html @page.html은 @page.html이라는 텍스트를 보냅니다. --html "$(cat page.html)"을 넘기거나, --data에 주는 파일에 html을 넣으세요.
• —rules update --conditions와 --actions는 목록 전체를 바꾸며, webhooks update --event-types, --address-allowlist, --domain-allowlist도 마찬가지입니다. 현재 값을 읽고, 바꾼 뒤, 전부 보내세요.
• —빈 --event-types는 사용 오류입니다. 엔드포인트를 기본 집합으로 되돌리려면 --data '{"eventTypes":[]}'를 보내고, 전달을 멈추려면 --no-enabled를 넘기세요.
• —templates update, replace-content, restore-version의 --expected-version은 읽어 둔 head 버전을 받습니다. 그 사이 다른 사람이 head를 옮겼다면 명령은 종료 코드 6과 version_conflict로 멈추고 아무것도 쓰지 않습니다.
• —rules update <id> --no-enabled는 규칙을 끄면서 순서의 자리는 유지하므로, 규칙을 삭제하지 않고 일시 중지하는 방법입니다.