Шаблоны, правила и вебхуки

Эти три пространства имён позволяют ящику работать без присмотра. templates хранит тела, которые вы отправляете много раз, rules раскладывает почту по мере поступления, а webhooks сообщает вашему серверу, что произошло. Каждая команда это метод SDK под своим именем в kebab-case, поэтому webhooks.rotateSecret становится openemail webhooks rotate-secret, и она читает аргументы и флаги, как любая другая команда ресурса.

На этой странице перечислены все команды и то, что стоит знать, прежде чем писать для них скрипт. Чтобы увидеть каждый аргумент и флаг с типом, нужными scope, эндпоинтом и тем, что он возвращает, запустите openemail <namespace> <verb> --help. Добавьте --json, чтобы получить ту же страницу в виде JSON.

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

Тела, сохранённые один раз и отправляемые много раз, с версиями, предпросмотром и типизированными props. Каждая команда, принимающая <id-or-slug>, принимает идентификатор tpl_ или slug. Slug никогда не меняется при переименовании шаблона, поэтому закрепляйте в скриптах slug.

• —Архивный шаблон отказывается отправлять с template_archived. publish снова делает его активным.
• —В рабочем пространстве может быть не больше 200 шаблонов, включая архивные, поэтому освободить место можно только удалением.
• —delete отклоняется с template_in_use, пока запланированная рассылка или рассылка в очереди всё ещё ссылается на шаблон.

Условия и действия, которые проверяются на приходящей почте в том порядке, который показывает rules list. Правило действует только на почту, пришедшую, пока оно включено. Ни одна команда не применяет правило к почте, которая уже в ящике, а увидеть, что оно поймало бы, позволяет rules test. Идентификаторы правил начинаются с 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 принимают только equals с true или false.
• —Типы действий: label, remove_label, archive, mark_read, star, spam, trash, forward, reply, block_sender и reject. label и remove_label принимают идентификатор метки, например USER_RECEIPTS, forward принимает адрес, а reply идентификатор или slug шаблона.
• —from_domain совпадает и с поддоменами, а hour и weekday читаются в UTC, причём воскресенье это 0.
• —Правило с действием reject должно также проверять envelope_from, иначе оно отклоняется с reject_needs_envelope.

Эндпоинты на вашем сервере, которые получают подписанные события ящика, с их секретами подписи, журналом доставок и журналом аудита каждого изменения. Идентификаторы эндпоинтов начинаются с whe_, а идентификаторы доставок с whd_.

Если не указать --event-types, эндпоинт получает набор по умолчанию: события email.*, кроме email.replied. 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 отказался бы, поэтому валите сборку при любом предупреждении. 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 возвращает идентификаторы в порядке выполнения, поэтому поставьте нужное правило перед остальными.

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 он есть в JSON в stdout, а напоминание сохранить его уходит в 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: delivered для ответа 2xx и failed для всего остального, включая перенаправление, поскольку перенаправления никогда не выполняются. responseCode, равный null, значит, что ответ не пришёл вообще.

После сбоя на вашей стороне перечислите, что не прошло, по всем эндпоинтам, проверьте, что повтор будет принят, и отправьте событие снова. Повтор несёт тот же идентификатор события, поэтому получатель, который отбрасывает уже обработанные идентификаторы, воспримет его как знакомое событие.

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 присылает на почту шестизначный код или, если включён двухфакторный вход, просит код из приложения-аутентификатора, а затем выполняет команду один раз.
• —Без присмотра, с --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. Без присмотра каждая останавливается с кодом выхода 2, если вы не передадите --yes.

$ 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… читают по одной странице, 25 строк, если --limit не просит до 100. Терминал показывает --cursor, который нужно передать для следующей страницы.
• —--all читает все страницы, --max <n> останавливается после стольких строк, а --ndjson выводит по одному JSON-объекту в строке. С --json список выводит один документ { items, hasMore, nextCursor }, в том числе с --all.
• —Передавайте курсор обратно с теми же фильтрами и сортировкой, с которыми он пришёл. Всё остальное отклоняется как 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. Аргумент <version> у get-version, restore-version и delete-version это номер версии, а не идентификатор tplv_.
• —--conditions, --actions, --document, --slots, --props и другие флаги JSON принимают JSON встроенно, из файла через @path или из stdin через -. --data принимает так же всё тело, а любой флаг, переданный вдобавок, переопределяет свой ключ.
• —--html принимает саму разметку, а не файл, поэтому --html @page.html отправляет текст @page.html. Передайте --html "$(cat page.html)" или поместите html в файл, который отдаёте --data.
• —rules update --conditions и --actions заменяют весь список, как и webhooks update --event-types, --address-allowlist и --domain-allowlist. Прочитайте текущее значение, измените его и отправьте целиком.
• —Пустой --event-types это ошибка использования. Чтобы вернуть эндпоинт на набор по умолчанию, отправьте --data '{"eventTypes":[]}', а чтобы остановить его доставки, передайте --no-enabled.
• —--expected-version у templates update, replace-content и restore-version принимает головную версию, которую вы прочитали. Если с тех пор головную версию сдвинул кто-то другой, команда останавливается с кодом выхода 6 и version_conflict и ничего не записывает.
• —rules update <id> --no-enabled выключает правило и сохраняет его место в порядке, и так правило ставят на паузу, не удаляя его.