Şablonlar, kurallar ve webhook'lar

Bu üç ad alanı, bir posta kutusunun kimse izlemeden çalışmasını sağlar. templates birçok kez gönderdiğiniz gövdeleri saklar, rules postayı geldikçe düzenler, webhooks ise kendi sunucunuza ne olduğunu bildirir. Her komut, kebab-case adıyla bir SDK yöntemidir; bu yüzden webhooks.rotateSecret, openemail webhooks rotate-secret olur ve bağımsız değişkenleri ve bayrakları diğer her kaynak komutu gibi okur.

Bu sayfa her komutu ve onu bir betikte kullanmadan önce bilmeye değer olanları listeler. Her bağımsız değişken ve bayrak için türü, gerektirdiği kapsamlar, uç noktası ve ne döndürdüğüyle birlikte openemail <namespace> <verb> --help çalıştırın. Aynı sayfayı JSON olarak almak için --json ekleyin.

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

Bir kez saklanıp birçok kez gönderilen gövdeler; sürümler, önizlemeler ve tipli prop'larla. <id-or-slug> alan her komut tpl_ id'sini ya da slug'ı kabul eder. Şablon yeniden adlandırıldığında slug asla değişmez, bu yüzden betiklerde slug'ı sabitleyin.

• —Arşivlenmiş bir şablon template_archived ile göndermeyi reddeder. publish onu yeniden etkin yapar.
• —Bir çalışma alanında arşivlenmişler dahil en fazla 200 şablon olabilir, bu yüzden yer açmanın tek yolu silmektir.
• —Zamanlanmış ya da kuyruktaki bir toplu gönderim şablonu hâlâ adlandırdığı sürece delete, template_in_use ile reddedilir.

Gelen posta üzerinde, rules list komutunun gösterdiği sırayla değerlendirilen koşullar ve eylemler. Bir kural yalnızca kendisi etkinken gelen postaya uygulanır. Hiçbir komut bir kuralı posta kutusunda zaten bulunan postaya uygulamaz; neyi yakalayacağını rules test ile görürsünüz. Kural id'leri rul_ ile başlar.

--conditions, --match all ya da --match any ile birleştirilen { field, op, value } nesnelerinden oluşan bir listedir; value her zaman bir dizedir ve negate: true tek bir koşulu tersine çevirir. --actions, sırayla uygulanan { type, value } nesnelerinden oluşan bir listedir. Bir kural 1 ile 20 arası koşul ve 1 ile 10 arası eylem alır; bir posta kutusunda en fazla 100 kural olabilir.

• —Koşul alanları: 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 ve weekday.
• —İşleçler: matches, contains, equals, starts_with, ends_with, gt ve lt. gt ve lt yalnızca sayı alanlarında çalışır; has_attachment ve spam yalnızca true ya da false ile equals alır.
• —Eylem türleri: label, remove_label, archive, mark_read, star, spam, trash, forward, reply, block_sender ve reject. label ve remove_label, USER_RECEIPTS gibi bir etiket id'si; forward bir adres; reply ise bir şablon id'si ya da slug'ı alır.
• —from_domain alt alan adlarıyla da eşleşir; hour ve weekday UTC olarak okunur ve Pazar için 0 kullanılır.
• —reject eylemi olan bir kuralın envelope_from alanını da sınaması gerekir, aksi hâlde reject_needs_envelope ile reddedilir.

Kendi sunucunuzda imzalı posta kutusu olaylarını alan uç noktalar; imzalama gizli anahtarları, teslim günlükleri ve her değişikliğin denetim günlüğüyle. Uç nokta id'leri whe_, teslim id'leri whd_ ile başlar.

--event-types vermezseniz bir uç nokta varsayılan kümeyi, yani email.replied dışındaki email.* olaylarını alır. email.replied, domain.* olayları ve suppression.* olayları ona yalnızca siz adlandırdığınızda ulaşır. --address-allowlist ve --domain-allowlist, bir API anahtarını daralttıkları gibi bir uç noktayı da bazı adreslere ya da alan adlarına daraltır.

• —Destek ekibi sınırını yükseltmediyse bir çalışma alanında 10 uç nokta olabilir.
• —Art arda 100 teslimde başarısız olan bir uç nokta sunucu tarafından kapatılır; webhooks update <id> --enabled onu geri getirir.
• —Bir tarayıcı oturumuyla bir teslimi get-delivery ile yalnızca çalışma alanı sahibi okuyabilir. Diğer herkes owner_only ve 4 çıkış kodu alır.

templates preview, aynı değerlerle yapılacak bir gönderimin üreteceğini, taslaklar dahil, birebir işler ve yalnızca templates:read gerektirir; bu yüzden salt okunur bir anahtar bile onu çalıştırabilir. send komutunun reddedeceği eksik bir zorunlu prop'u uyarı olarak bildirir, bu yüzden herhangi bir uyarıda derlemeyi başarısız sayın. publish her dağıtımda güvenlidir, çünkü zaten yayında olan bir head'i yayımlamak hiçbir şeyi değiştirmez.

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

Sürümü sabitleyin, böylece yarın yayımlanan bir yeniden yazım bu kodun gönderdiğini değiştirmez; gönderime yol açan şeyden türetilmiş bir eş güçlülük anahtarı verin, böylece kaybolan bir yanıttan sonraki yeniden deneme ikinci bir mesaj göndermek yerine ilkini yeniden oynatır. --dry-run yöntemi, URL'yi, kimlik bilginiz gizlenmiş başlıkları ve gövdeyi yazdırır, hiçbir şey göndermez ve 0 koduyla çıkar. Göndermek için --dry-run olmadan yeniden çalıştırın.

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

Kuralı kapalı olarak oluşturun, son posta üzerinde deneme olarak çalıştırın ve istediğinizi yakaladığında açın. Bir tarayıcı oturumuyla rules create ve rules update bir betiğin yazamayacağı bir doğrulama kodu ister, bu yüzden önce openemail verify çalıştırın. Sonraki 60 dakika boyunca o profil bunları sormadan çalıştırır.

[  { "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 çıktısında eşleşmelerden önce uyarıları okuyun. field_unevaluable, bir koşulun saklanan postanın artık taşımadığı bir şeyi okuduğu ve testin bunu değerlendiremediği anlamına gelir; forward_unverified ise bir yönlendirme hedefinin burada barındırılmadığı anlamına gelir. wouldApply kuralın bildirdiklerini listeler: onaylamamış bir adrese yönlendirme, gerçek posta geldiğinde yine başarısız olur.

rules reorder posta kutusundaki her kuralı tam olarak bir kez alır. Dışarıda bırakılan ya da iki kez adlandırılan bir kural reddedilir ve hiçbir şey yer değiştirmez. rules list id'leri çalıştıkları sırayla döndürür, bu yüzden ilk olmasını istediğinizi diğerlerinin önüne koyun.

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 gerçekte ne olduğunun kaydıdır. Her satır, bir kuralın bir mesajla eşleşmesidir; etkili olan eylemler ve failures içinde posta kutusunun geri çevirdikleri, örneğin o gün zaten yanıtlanmış bir gönderene yanıt, yer alır. Her satır kuralın o anki adını saklar, bu yüzden --rule-id o zamandan beri sildiğiniz bir kural için de çalışır.

webhooks create imzalama gizli anahtarını bir kez gösterir ve sonraki hiçbir komut onu yeniden göstermez. --json ile anahtar stdout'taki JSON içindedir, onu saklama hatırlatması ise stderr'e gider; böylece çıktı yine ayrıştırılabilir. webhooks test, uç nokta hangi olaylara abone olursa olsun imzalı, yapay bir email.sent olayı gönderir ve hiç posta gönderilmez.

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

Dosyayı silmeden önce gizli anahtarı gizli anahtar deponuza koyun. test sunucunuz başarısız olsa bile 0 koduyla çıkar, bu yüzden delivery.status değerini okuyun: 2xx yanıt için delivered, yönlendirmeler asla izlenmediğinden bir yönlendirme dahil başka her şey için failed. null değerli bir responseCode hiç yanıt gelmediği anlamına gelir.

Sizin tarafınızdaki bir kesintiden sonra tüm uç noktalarda neyin başarısız olduğunu listeleyin, yeniden göndermenin kabul edileceğini kontrol edin ve olayı yeniden gönderin. Yeniden gönderim aynı olay id'sini taşır, bu yüzden daha önce işlediği id'leri atan bir alıcı onu zaten bildiği olay olarak ele alır.

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 ve --until bir ISO 8601 anı alır.
• —nextAttemptAt alanında bir zaman bulunan başarısız bir satır için hâlâ otomatik bir yeniden deneme sırada demektir.
• —replayRefusal, yeniden gönderim gidebilecekse null olur; aksi hâlde neden reddedileceğini adlandırır, örneğin uç nokta kapalıyken webhook_disabled.
• —Yeniden gönderimler her seferinde tek bir olay için yapılır. Hiçbir komut başarısız teslimlerin tamamını yeniden göndermez.

Bir tarayıcı oturumuyla bu komutlardan dördü, web uygulamasında olduğu gibi, bir şeyi değiştirmeden önce doğrulama kodu ister: rules create, rules update, webhooks create ve webhooks update. Bir API anahtarından asla istenmez. Bu sayfadaki diğer her komut, silmeler ve webhooks rotate-secret dahil, kodsuz çalışır.

• —Terminalde CLI size e-postayla altı haneli bir kod gönderir ya da iki adımlı oturum açma açıksa kimlik doğrulayıcı uygulamanızdan bir kod ister, ardından komutu bir kez çalıştırır.
• —Gözetimsiz çalışırken, yani --json ya da --no-input ile, CI'da ya da terminal olmadan, kodu kimse yazamaz; bu yüzden komut 4 çıkış koduyla durur ve hiçbir şeyi değiştirmez. Önce openemail verify çalıştırın, profil 60 dakika boyunca kod gerektirmez.
• —--yes bir silmeyi onaylar ama asla bir kodu atlamaz.

Buradaki yedi komut bir şeyi kaldırır ya da üzerine yazar, bu yüzden önce onay ister: templates delete, templates delete-version, templates replace-content, templates restore-version, rules delete, webhooks delete ve webhooks rotate-secret. Gözetimsiz çalışırken her biri, --yes vermediğiniz sürece 2 çıkış koduyla durur.

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

--dry-run bir şeyi değiştirecek ilk isteği yazdırır ve göndermeden ya da onay istemeden 0 koduyla çıkar. --json ile tek bir { dryRun, request } belgesi yazdırır. rules test, templates render ve templates preview hiçbir şeyi değiştirmez, ancak POST istekleridir, bu yüzden bir deneme çalıştırması onları çalıştırmak yerine yazdırır.

• —templates list, templates list-versions, rules list, rules list-runs ve her webhooks list… komutu her seferinde tek bir sayfa okur; --limit en fazla 100 istemedikçe 25 satır. Terminal, sonraki sayfa için verilecek --cursor değerini gösterir.
• —--all her sayfayı okur, --max <n> o kadar satırdan sonra durur, --ndjson her satıra bir JSON nesnesi yazdırır. --json ile bir liste, --all dahil, tek bir { items, hasMore, nextCursor } belgesi yazdırır.
• —Bir imleci geldiği filtreler ve sıralamayla geri verin. Başka her şey invalid_cursor olarak, 7 çıkış koduyla reddedilir.
• —templates list-sends ise sayfaları numarayla, --page ve --page-size ile böler, total bildirir ve --all desteklemez. Posta gönderilirken sayfa numaraları kayar, bu yüzden derin sayfalara gitmek yerine zaman aralığını --days ya da --minutes ile daraltın.
• —templates list-starters ve templates list-fonts kataloğun tamamını tek seferde döndürür; rules reorder ise her kuralı yeni sırasıyla düz bir liste olarak döndürür.
• —Bir posta kutusunda en fazla 100 kural olabilir, bu yüzden rules list --limit 100 her zaman tüm kuralları tek sayfada döndürür.

• —--template-version, gövdedeki version alanıdır; --version CLI sürümünü yazdırdığı için yeniden adlandırılmıştır. get-version, restore-version ve delete-version komutlarının <version> bağımsız değişkeni bir tplv_ id'si değil, bir sürüm numarasıdır.
• —--conditions, --actions, --document, --slots, --props ve diğer JSON bayrakları JSON'u satır içi, @path ile bir dosyadan ya da - ile stdin'den alır. --data gövdenin tamamını aynı şekilde alır ve ayrıca verdiğiniz her bayrak kendi anahtarını geçersiz kılar.
• —--html bir dosyayı değil biçimlendirmenin kendisini alır, bu yüzden --html @page.html @page.html metnini gönderir. --html "$(cat page.html)" verin ya da html alanını --data bayrağına verdiğiniz dosyaya koyun.
• —rules update --conditions ve --actions listenin tamamının yerini alır; webhooks update --event-types, --address-allowlist ve --domain-allowlist de öyle. Geçerli değeri okuyun, değiştirin ve tamamını gönderin.
• —Boş bir --event-types bir kullanım hatasıdır. Bir uç noktayı varsayılan kümeye döndürmek için --data '{"eventTypes":[]}' gönderin, teslimlerini durdurmak için --no-enabled verin.
• —templates update, replace-content ve restore-version üzerindeki --expected-version, okuduğunuz head sürümünü alır. Başka biri o zamandan beri head'i ilerlettiyse komut 6 çıkış kodu ve version_conflict ile durur ve hiçbir şey yazmaz.
• —rules update <id> --no-enabled bir kuralı kapatır ve sıradaki yerini korur; bir kuralı silmeden duraklatmanın yolu budur.