قالب‌ها، قاعده‌ها و وب‌هوک‌ها

این سه فضای نام به یک صندوق پستی اجازه می‌دهند بدون اینکه کسی مراقبش باشد کار کند. templates بدنه‌هایی را که بارها می‌فرستید ذخیره می‌کند، rules نامه را هنگام رسیدن مرتب می‌کند، و webhooks به سرور خودتان می‌گوید چه رخ داده است. هر فرمان یک متد SDK با نام kebab-case آن است، پس 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_ یا 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 لازم دارد، پس حتی کلیدِ فقط‌خواندنی هم می‌تواند اجرایش کند. prop الزامیِ ناموجود را به‌صورت هشدار گزارش می‌دهد، جایی که 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

نسخه را ثابت کنید تا بازنویسی‌ای که فردا منتشر می‌شود آنچه این کد می‌فرستد را تغییر ندهد، و یک کلید idempotency برگرفته از آنچه باعث ارسال شده بدهید، تا تلاش دوباره پس از گم شدن پاسخ پیام نخست را بازپخش کند نه اینکه پیام دومی بفرستد. --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 یک قاعده را خاموش می‌کند و جایش را در ترتیب نگه می‌دارد، که راه مکث دادن به یک قاعده بدون حذف آن است.