टेम्पलेट, नियम और वेबहुक

ये तीन नेमस्पेस मेलबॉक्स को बिना किसी की निगरानी के चलने देते हैं। templates बार-बार भेजी जाने वाली बॉडी सहेजता है, rules आते ही मेल को छाँटता है, और webhooks आपके अपने सर्वर को बताता है कि क्या हुआ। हर कमांड अपने kebab-case नाम के तहत एक 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 चाहिए, इसलिए सिर्फ़ पढ़ने वाली कुंजी भी इसे चला सकती है। यह छूटे ज़रूरी 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 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 आपको छह अंकों का कोड ईमेल करती है, या दो-चरणीय साइन-इन चालू हो तो आपके ऑथेंटिकेटर ऐप से कोड माँगती है, फिर कमांड एक बार चलाती है।
• —बिना निगरानी के, --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… कमांड एक बार में एक पेज पढ़ती है, 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 का वर्ज़न प्रिंट करता है। get-version, restore-version और delete-version का <version> आर्ग्युमेंट वर्ज़न नंबर है, tplv_ ID नहीं।
• —--conditions, --actions, --document, --slots, --props और दूसरे JSON फ़्लैग JSON इनलाइन, @path से फ़ाइल से, या - से stdin से लेते हैं। --data पूरी बॉडी इसी तरह लेता है, और साथ में दिया गया कोई भी फ़्लैग उसी नाम की JSON कुंजी को बदल देता है।
• —--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 दें।
• —templates update, replace-content और restore-version पर --expected-version वह हेड वर्ज़न लेता है जो आपने पढ़ा। अगर तब से किसी और ने हेड आगे बढ़ा दिया हो, तो कमांड एग्ज़िट कोड 6 और version_conflict के साथ रुकती है, और कुछ नहीं लिखती।
• —rules update <id> --no-enabled नियम को बंद करती है और क्रम में उसकी जगह बनाए रखती है, जो किसी नियम को हटाए बिना रोकने का तरीका है।