API

إنشاء قاعدة

الشروط في جانب، والإجراءات في الآخر. مفعَّلة ما لم تقل غير ذلك.

POSTapi.openemail.uk/rules

ينفّذ الاستدعاء الحقيقي على مساحة عملك، بمفتاحك أنت.

POST /rules

الشروط في جانب، والإجراءات في الآخر. مفعَّلة ما لم تقل غير ذلك.

مثال

يتطلب rules:write. يُعيد 201. وposition غير مقبول. فالقاعدة الجديدة تُلحَق بنهاية القائمة، ونقلها يتم بـ POST /rules/reorder.

curl

curl -X POST "$OE/rules" -H "$AUTH" -H "Content-Type: application/json" \  -d '{    "name": "Receipts to their own label",    "match": "all",    "conditions": [      { "field": "from_domain", "op": "matches", "value": "*.stripe.com" },      { "field": "subject", "op": "contains", "value": "receipt" }    ],    "actions": [      { "type": "label", "value": "USER_RECEIPTS" },      { "type": "archive" }    ],    "stopProcessing": true  }'

الاستجابة

{  "object": "rule",  "id": "rul_7f3a1c94e05d3862c1f0a44b",  "name": "Receipts to their own label",  "description": null,  "enabled": true,  "position": 3,  "match": "all",  "conditions": [    { "field": "from_domain", "op": "matches", "value": "*.stripe.com", "negate": false },    { "field": "subject", "op": "contains", "value": "receipt", "negate": false }  ],  "actions": [    { "type": "label", "value": "USER_RECEIPTS" },    { "type": "archive" }  ],  "stopProcessing": true,  "lastMatchedAt": null,  "matchCount": 0,  "createdAt": "2026-08-30T10:41:02.000Z",  "updatedAt": "2026-08-30T10:41:02.000Z"}

القاعدة المنشأة هنا مفعَّلة، وتبدأ العمل على الرسالة التالية. وهذا هو الافتراض الصحيح لنداء صنعه شخص عن قصد، وهو عكس أداة MCP createRule، التي تكتب القاعدة نفسها معطَّلة لأن نموذجًا يقرر أرشفة البريد ينبغي ألّا يبدأ الأرشفة قبل أن يقرأ شخص القاعدة.

تكرار name على الاتصال نفسه هو rule_name_taken، وهو 409. فالأسماء هي ما تُعرَف به القاعدة في سجل التشغيل وفي شاشة الإعدادات، فقاعدتان باسم «Newsletters» تقريرٌ لا يستطيع أحد قراءته.

القاعدة رقم 101 هي rule_limit_reached، وهو 422. والسقف حرس ضد نص برمجي في حلقة لا حد محاسبي، وهو غير مُقفَل. فإنشاءان متسابقان عند 99 قد ينجحان معًا.

ما الذي يستطيع الشرط سؤاله

الشرط هو { field, op, value }، مع header اختياري يسمّي أي ترويسة تُقرأ، وnegate اختياري. وvalue هي دائمًا string على السلك. الحقول العددية تُقارَن كأرقام بعد Number(value)، والحقلان المنطقيان يأخذان السلسلتين الحرفيتين "true" و"false"، لأن حقلًا واحدًا بنوع واحد مخطط يستطيع مولّد OpenAPI وصفه، واتحاد ثلاثة أنواع لا يستطيع.

الحقل	يقرأ	العوامل
`from`	ترويسة `From:`، مُطبَّعة بالطريقة التي تطبّعها بها قائمة الحظر.	text
`from_domain`	نطاق `From:` ونطاقاته الأصل، نزولًا إلى تسميتين: رسالة من `mail.corp.example.com` تطابق `corp.example.com` و`example.com` أيضًا، ولا تطابق شيئًا لـ `com`.	text
`envelope_from`	قيمة `MAIL FROM` في SMTP. تختلف عن `from` في كل قائمة بريدية، وهي الهوية الوحيدة التي يجوز كتابة `reject` في مقابلها.	text
`to`, `cc`, `bcc`	أي عنوان واحد في تلك الترويسة.	text
`recipient`	أي عنوان في `to` أو `cc` أو `bcc`: اختصار الثلاثة معًا.	text
`reply_to`	ترويسة `Reply-To`.	text
`delivered_to`	العنوان المعياري الذي سُلِّمت إليه هذه النسخة، منزوع وسم الزائد ومحوَّل إلى حروف صغيرة، وهي الطريقة التي يُطابَق بها اسم مستعار من نوع catch-all.	text
`subject`	سطر الموضوع كما وصل.	text
`body`	الجزء النصي، أو HTML مختزلًا إلى نص. مسقوف، فلا يُفحَص نص بحجم 20 MB كاملًا.	text
`header`	أي ترويسة، مسمّاة في حقل `header` الخاص بالشرط. مطلوب هناك ويُحوَّل إلى حروف صغيرة قبل المقارنة.	text
`list_id`	ترويسة `List-Id`: المعرّف الذي تعرّف به القائمة البريدية نفسها.	text
`attachment_name`	اسم ملف أي مرفق.	text
`attachment_type`	نوع MIME لأي مرفق، مثل `application/pdf`.	text
`has_attachment`	هل يوجد مرفق أصلًا.	`equals` `"true"` / `"false"`
`spam`	حكم البريد المزعج الذي بلغه مسار التسليم، قبل تشغيل قواعدك.	`equals` `"true"` / `"false"`
`attachment_size`	حجم مرفق بالبايت. والمقارنة تتطابق حين يحققها أي مرفق واحد.	`gt`, `lt`, `equals`
`message_size`	الرسالة كاملة على السلك، بالبايت.	`gt`, `lt`, `equals`
`hour`	ساعة الوصول، 0–23، بتوقيت UTC.	`gt`, `lt`, `equals`
`weekday`	يوم الوصول، 0–6، الأحد هو 0، بتوقيت UTC.	`gt`, `lt`, `equals`

العامل	ما الذي يفعله
`matches`	نمط glob، وglob فقط: `*` لأي سلسلة من المحارف، و`?` لمحرف واحد. لا تعابير نمطية. فالنمط القادم من عميل API يعمل على مسار التسليم، والنمط الكارثي التراجع هناك هو صندوق بريد يتوقف عن الاستقبال.
`contains`	سلسلة فرعية، غير حساسة لحالة الأحرف.
`equals`	القيمة كاملة، غير حساسة لحالة الأحرف. وعلى حقل عددي، تَساوٍ عددي.
`starts_with`	بادئة، غير حساسة لحالة الأحرف.
`ends_with`	لاحقة، غير حساسة لحالة الأحرف.
`gt`, `lt`	عددي، على الحقول العددية الأربعة فقط. والحقل النصي مع `gt` لا يتطابق أبدًا.

يجب أن يحمل نمط matches محرفين أبجديين رقميين على الأقل من عنده، وهو المعيار نفسه الذي تطبّقه قائمة الحظر. و* المجرّد يُرفَض عند الكتابة بدل أن يُقبَل ثم يطابق بصمت كل رسالة ستصل يومًا، وهو انقطاع خدمة لا قاعدة.

الشرط الذي لا يستطيع المحرك الإجابة عنه (حقل مجهول من عميل أحدث، أو نمط لن يُترجَم، أو contains "") يُعامَل كسؤال لم يُطرح قط لا كقيمة خاطئة، وnegate لا تقلبه. وهذا التمييز حامل للحِمل: فالشرط المعطوب المنفي لو عُومل كخاطئ لأطلق قاعدته على كل رسالة في صندوق البريد. أما equals "" فيُحترم، لأن «سطر الموضوع فارغ» سؤال حقيقي.

ما الذي تستطيع القاعدة فعله

الإجراء	`value`	ما الذي يحدث
`label`	معرّف تسمية	يضيف التسمية. ومعرّفات `USER_…` تأتي من `GET /labels`.
`remove_label`	معرّف تسمية	يزيلها. وتسمية الشيء نفسه في الاثنين تُحسَم قبل حفظ الرسالة لا تُترك لأيهما نُفِّذ أخيرًا.
`archive`	لا شيء	يحفظها خارج صندوق الوارد.
`mark_read`	لا شيء	يُسقط `UNREAD`.
`star`	لا شيء	يضيف `STARRED`.
`spam`	لا شيء	يحفظها تحت Spam.
`trash`	لا شيء	يحفظها تحت Trash، ماسحًا التسميات التي لا تحتفظ بها رسالة محذوفة.
`forward`	عنوان	يرسل نسخة. اقرأ الملاحظة أدناه قبل استخدامه.
`reply`	معرّف قالب أو slug	يرد تلقائيًا بقالب منشور، رهنًا بحارس الحلقة أدناه.
`block_sender`	لا شيء	يضيف المرسِل إلى قائمة الحظر، فتُرفض الرسالة التالية عند الباب.
`reject`	لا شيء	يرفض الرسالة وقت SMTP بالرد `550 5.7.1 Message refused by the recipient`. على المغلّف فقط. انظر أدناه.

reject يُرفَض عند الكتابة ما لم تحمل القاعدة نفسها شرط envelope_from واحدًا على الأقل: reject_needs_envelope، وهو 422. فالرد 550 يجيب من سلّمنا الرسالة، وعلى قائمة بريدية يكون ذلك هو القائمة، التي تقرأ الرفض كمشترك مرتدّ وتلغي اشتراك القارئ من شيء أراد فقط أن يتوقف شخص واحد عن النشر فيه. وحتى مع كتابة الشرط، فإن تطابقًا جاء من هويات الترويسة وحدها يُخفَّض إلى الحفظ تحت Spam، لأن المغلّف هو الهوية الوحيدة التي يمكن توجيه الرفض إليها بصدق.

forward المدفوع بقاعدة يخرج عبر مسار الإرسال، الذي يعيد بناء الرسالة: فتوقيع DKIM الأصلي لا ينجو، ولا تنجو الأجزاء الغريبة ولا الترويسات غير المعتادة ولا أي شيء يتجاوز سقف الحجم الصادر، وهو ما ستتجاوزه رسالة بحجم 25 MB بمرفقاتها. إنها نسخة مما وصل لا الرسالة التي وصلت. ويُفحَص العنوان حين تُكتب القاعدة، فالوجهة غير الموثَّقة هي 422 على النداء لا قاعدة تُسقط بصمت كل رسالة عاشرة.

reply لن يرد على آلة. فهو مكبوت حين تحمل الرسالة Auto-Submitted (بقيمة غير no)، أو Precedence: bulk|list|junk، أو List-Id، أو List-Unsubscribe، أو X-Autoreply، أو X-Autorespond، وحين يكون مرسِل المغلّف فارغًا (وهو شكل كل ارتداد)، وحين يتعذّر قراءة الترويسات إطلاقًا. وفوق ذلك، يحصل المرسِل الواحد على رد تلقائي واحد على الأكثر كل 24 ساعة من صندوق بريد معين. فصندوقان بقواعد رد وبلا حارس يراسل أحدهما الآخر حتى يلاحظ أحد.