كيف تعمل الأتمتة

يتكوّن definition من trigger، وخطوة entry، وقائمة steps. ولكل خطوة key فريد داخل الأتمتة: حرف صغير يتبعه من 2 إلى 23 حرفًا صغيرًا أو رقمًا. تسمّي الخطوة ما يليها في next، ويسمّي branch خطوتين، yes وno. وnull ينهي ذلك المسار. تشكّل الخطوات شجرة، فلا توصَل خطوة من موضعين ولا يعود شيء إلى الوراء. وتتسع الأتمتة لـ 50 خطوة على الأكثر، بتفرّعات لا يزيد عمقها على 5 مستويات.

• —audience_joined: تُضاف جهة اتصال إلى audienceId. وتُستبعد جهات الاتصال المضافة عبر استيراد ما لم تكن قيمة includeImported هي true.
• —form_submitted: يشترك شخص عبر النموذج formId. ومع التأكيد المزدوج يدخل حين يؤكد.
• —event: ترسل شيفرتك حدثًا اسمه eventName. ويحصر ما يصل إلى 5 من filters على خصائصه من يدخل.
• —date: يحلّ يوم معيّن لكل عضو في audienceId. وقيمة field هي birthday أو joined، أي ذكرى يوم انضمامه إلى ذلك الجمهور. ويزيحه offsetDays بما يصل إلى سنة: قيمة سالبة لأيام قبله، وموجبة لأيام بعده.
• —manual: لا أحد يدخل من تلقاء نفسه. تضيف الأشخاص من التطبيق أو عبر نقطة نهاية التسجيل.

القيمة في props أو update_field تأتي من أحد ثلاثة مواضع: { "source": "static", "value": "…" }، و{ "source": "contact", "field": "firstName" } لـ email أو name أو firstName أو lastName أو attributes.<key>، و{ "source": "event", "path": "orderId" } لخاصية من الحدث الذي بدأ المسار.

الحفظ يغيّر definition المسودة. ولا يعمل شيء حتى يثبّت POST /automations/{id}/publish المسودة بوصفها نسخة مرقّمة، يعرضها published بعد ذلك. ومن هم بداخلها بالفعل يكملون بالنسخة التي دخلوا بها، ومن يدخلون بعد ذلك يحصلون على الجديدة. ويفيد hasUnpublishedChanges بأن المسودة تقدّمت عن المنشور.

• —draft: لم تُنشر قط. لا أحد يدخلها.
• —live: منشورة وتعمل.
• —paused: لا أحد يدخل ويبقى كل من بداخلها في مكانه. ويذكر pausedReason السبب: manual، أو مشكلة واجهها المحرّك، مثل sender_refused أو template_unavailable.
• —archived: أُوقفت نهائيًا. يخرج منها كل من بداخلها، ويبقى السجلّ.

settings منفصلة وتُطبَّق فور حفظها: timezone، وsendWindow تنتظر الرسائل خارجها، وreentryDays قبل أن يتمكن الشخص نفسه من الدخول مجددًا (null تعني مرة واحدة)، وexitOnLeave لإخراج من يغادرون جمهور المشغِّل، وlistAudienceId، وهو الجمهور الذي يُسجَّل فيه إلغاء الاشتراك.

يسرد problems ما في المسودة من مشكلات، ولكل منها code، وpath الحقل، وstepKey، وهل هي blocking. والمسودة التي فيها مشكلة مانعة لا يمكن نشرها.

كل شخص يدخل يحصل على تسجيل. ويكون active ما دام يتنقل بين الخطوات، وcompleted حين يبلغ نهاية مسار، وexited حين يخرج مبكرًا، مع exitReason: exit_step أو unsubscribed أو suppressed أو left_audience أو removed أو archived أو failed.

• —تُنفَّذ الخطوات خلال نحو 15 ثانية من حلول موعدها. ولا يتلقى الشخص أبدًا رسالتين من أتمتة واحدة في الدورة نفسها.
• —رسائل الأتمتة بريد تسويقي، ولذلك تحمل كل رسالة منها رابط إلغاء الاشتراك. ومن يلغي اشتراكه يخرج من الأتمتات التي تراسل تلك القائمة، ومن ارتدّ بريد عنوانه أو اشتكى يخرج عند خطوته التالية.
• —الرسالة التي لا يستطيع عنوانها استقبال البريد تُتخطّى، ويواصل الشخص إلى الخطوة التالية.
• —حين يُرفض الإرسال للجميع، كمُرسِل فقد نطاقه أو قالب أُلغي نشره، تتوقف الأتمتة مؤقتًا ويذكر pausedReason السبب.

يسجّل POST /events أن جهة اتصال فعلت شيئًا: order.placed، trial.started، plan.upgraded. ويبدأ الحدث كل أتمتة منشورة يسمّيه مشغِّلها، ويدفع إلى الأمام كل من ينتظره، ويجيب عن سؤال event في التفرّع. وتُحفظ الأحداث 90 يومًا.

• —القراءة تتطلب automations:read والتغيير يتطلب automations:write. والنشر والاستئناف وإرسال اختبار تتطلب أيضًا emails:send، لأنها تجعل الأتمتة ترسل بريدًا.
• —إرسال حدث يتطلب contacts:write، وقراءة أحداث جهة اتصال تتطلب contacts:read.
• —يرى مفتاح API والمالك كل أتمتة في مساحة العمل. أما التطبيق الذي ربطه عضو فيرى ما أنشأه ذلك العضو منها.
• —حذف أتمتة يطلب من تطبيق OAuth رمز تحقق. أما مفتاح API فلا يحتاج إليه أبدًا.
• —تسمح الخطة بـ 1 أتمتة منشورة في Free، و10 في Starter، و50 في Business، وبأي عدد في Enterprise. وتتسع مساحة العمل افتراضيًا لـ 100 أتمتة.

أحداث webhook automation.entered وautomation.exited وautomation.paused تخبر أنظمتك بمن دخل ومن خرج ومتى توقفت أتمتة. وأرشفة أتمتة تنهي مسار كل من فيها من دون حدث automation.exited لكل شخص.

كل ما هنا متاح أيضًا في SDK بوصفه openemail.automations وopenemail.events، وفي CLI بوصفه openemail automations وopenemail events. ولدى خادم MCP أدوات للأتمتة، فيستطيع الوكيل أن ينشئ أتمتة وينشرها ويتابع من بداخلها.