القوالب والقواعد وخطافات الويب

تتيح مساحات الأسماء الثلاث هذه لصندوق البريد أن يعمل دون أن يراقبه أحد. يخزّن 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

أجسام تُخزَّن مرة وتُرسل مرات كثيرة، مع إصدارات ومعاينات وخصائص ذات أنواع. كل أمر يأخذ <id-or-slug> يقبل معرّف tpl_ أو المعرّف النصي. والمعرّف النصي لا يتغير أبدًا عند إعادة تسمية القالب، لذا ثبّته في السكربتات.

• —القالب المؤرشف يرفض الإرسال بـ 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 معرّف قالب أو معرّفه النصي.
• —يطابق 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 قاعدة ويحتفظ بمكانها في الترتيب، وهذه طريقة إيقاف قاعدة مؤقتًا دون حذفها.