كيف تعمل النماذج

يحتفظ النموذج بنسختين مما يراه الزوار. document هو المسودة التي تحرّرها، وpublishedDocument هو ما تستخدمه الصفحة المستضافة والنسخة المضمَّنة ونقطة نهاية الاشتراك. والحفظ لا يغيّر إلا المسودة، وPOST /forms/{id}/publish ينسخها إلى النسخة المنشورة. ويخبرك hasUnpublishedChanges بأن النسختين مختلفتان.

• —draft: لم يُنشر قط. لا يستطيع أحد رؤيته أو الاشتراك عبره.
• —live: منشور ويستقبل الاشتراكات.
• —paused: منشور لكنه مغلق. تعرض الصفحة رسالة الإغلاق من نصوصه، وتُرفض الاشتراكات.

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

يتكون المستند من قائمة fields، ونصوص copy المحيطة بها، وstyle. ولكل حقل إدخال key، وهو الاسم الذي تُرسَل إجابته تحته: حرف صغير يليه حتى 39 من الأحرف الصغيرة أو الأرقام أو الشرطات السفلية، فريد في النموذج، ولا يبدأ أبدًا بـ oe_. ولكل نموذج حقل email واحد بالضبط، مفتاحه email وهو مطلوب.

• —حقول الإدخال: email وtext وtextarea وnumber وphone وurl وdate.
• —الخيارات: select وradio وcheckboxes، ولكل منها options.
• —checkbox لإجابة بنعم أو لا، وconsent لمربع يجب تحديده حين يكون مطلوبًا.
• —يتيح audiences للشخص اختيار القوائم: كل value لخيار هو معرّف جمهور في مساحة العمل هذه.
• —يحمل hidden قيمة لا يراها الزائر أبدًا: القيمة التي ترسلها صفحتك، وإلا فقيمة defaultValue الخاصة به، مثل اسم حملة.
• —أما heading وparagraph وdivider فلا تفعل سوى ترتيب النموذج، ولا ترسل شيئًا.

اضبط mapsTo على firstName أو lastName أو name في حقل نصي، فتصبح الإجابة اسم جهة الاتصال التي ينشئها الاشتراك. وجهة الاتصال الموجودة مسبقًا تحتفظ باسمها. وتُحفظ كل إجابة في الرد مع التسمية التي كانت لها، فتبقى قراءة الردود القديمة صحيحة بعد تغيّر النموذج.

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

• —الصفحة المستضافة على url، وهي صفحة مستقلة يمكنك الربط إليها من أي مكان.
• —سكربت التضمين، الذي يضع النموذج في صفحتك داخل إطار يضبط حجمه بنفسه.
• —HTML أو شيفرتك الخاصة، ترسل الإجابات إلى subscribeUrl.

<script src="https://openemail.uk/embed/form.js" data-openemail-form="frm_3b9d2e7a1c4f80d56e2a9b14" async></script>

<form action="https://api.openemail.uk/subscribe/frm_3b9d2e7a1c4f80d56e2a9b14" method="post">  <input type="email" name="email" required>  <div style="position:absolute;left:-9999px" aria-hidden="true">    <input type="text" name="oe_website" tabindex="-1" autocomplete="off">  </div>  <button type="submit">Subscribe</button></form>

يُعاد توجيه نموذج HTML العادي إلى صفحة الشكر، أو إلى settings.redirectUrl. أما الشيفرة التي ترسل JSON فتتلقى بدلًا من ذلك استجابة بصيغة JSON، موصوفة في صفحة الاشتراك.

عند تفعيل settings.doubleOptIn، يُحفظ الاشتراك بالحالة pending ويُرسل إلى الشخص بريد يحمل رابطًا من settings.senderAddress، وهو عنوان في مساحة العمل هذه. وينضم إلى الجماهير حين يفتحه. والرابط صالح سبعة أيام. ومن ألغى اشتراكه في جمهور سابقًا لا يُعاد اشتراكه إلا بهذه الطريقة، ولا يُعاد أبدًا عبر نموذج بلا تأكيد مزدوج. والاشتراك مرة أخرى قبل التأكيد يحدّث الاشتراك المعلّق بدل إضافة اشتراك آخر.

لحماية الأشخاص الذين تراسلهم، يتلقى العنوان الواحد تأكيدًا واحدًا على الأكثر لكل نموذج كل عشر دقائق، وخمسة في اليوم عبر مساحة العمل. ويمكنك أن توافق بنفسك على اشتراك معلّق، أو أن ترسل إليه رابطًا جديدًا.

• —القراءة تتطلب forms:read والتغيير يتطلب forms:write. والموافقة على اشتراك تتطلب أيضًا contacts:write، لأنها تضيف جهة اتصال.
• —كل ما يجعل النموذج يرسل بريدًا يتطلب emails:send أيضًا: تفعيل التأكيد المزدوج، وتعيين المُرسِل أو رسالة التأكيد، ونشر نموذج ذي تأكيد مزدوج أو استئنافه، وإعادة إرسال تأكيد.
• —يرى مفتاح API والمالك كل نموذج في مساحة العمل. أما التطبيق الذي ربطه عضو فلا يرى إلا النماذج التي أنشأها ذلك العضو، ولا يرى من الجماهير إلا ما أنشأه ذلك العضو إضافةً إلى الجماهير المدمجة.
• —إذا كان مُرسِل النموذج أو عناوين الإشعار فيه خارج ما يحق للمفتاح أو التطبيق المقيّد الوصول إليه، فإن إنشاءه أو تحديثه أو نشره أو استئنافه أو تكراره يجيب بـ 422 capability_unsupported.
• —المفتاح أو التطبيق المقيّد ببعض العناوين لا يستطيع أن يعيّن مُرسِلًا ولا عناوين إشعار إلا من العناوين التي يملكها.
• —حذف نموذج يطلب من تطبيق OAuth رمز تحقق، كما تفعل التغييرات المدمّرة الأخرى. أما مفتاح API فلا يحتاج إليه أبدًا.

تُبلغ خطافات الويب form.submitted وform.confirmed أنظمتك بكل اشتراك. وخطاف الويب المقيّد ببعض العناوين لا يتلقاها أبدًا، لأن الاشتراكات تخص مساحة العمل كلها.

• —الحقل المسمّى oe_website فخ للبرامج الآلية: أبقه فارغًا وخارج الشاشة، كما يفعل HTML أعلاه. والاشتراك الذي يملؤه يتلقى استجابة عادية ثم يُسقط.
• —وتتحقق الصفحة المستضافة والنسخة المضمَّنة أيضًا من وقت بدء موقّع، والنموذج الذي يُعاد إرساله أسرع مما يستطيع شخص أن يملأه يُسقط بالطريقة نفسها.
• —تستطيع الشبكة الواحدة إرسال 40 اشتراكًا في عشر دقائق، عبر كل نماذجك وأيًّا كانت النتيجة. وبعد ذلك تتلقى طلبات JSON الاستجابة 429 form_rate_limited، وينتقل نموذج HTML العادي إلى الصفحة المستضافة مع ?outcome=limited.
• —تتسع مساحة العمل افتراضيًا لـ 100 نموذج.

كل ما هنا متاح أيضًا في SDK بوصفه openemail.forms وفي CLI بوصفه openemail forms، ولدى خادم MCP أدوات للنماذج، فيستطيع الوكيل أن ينشئ نموذجًا وينشره ويتابعه. وعبر MCP يكتب العميل التصميم بنفسه ويمرّره بوصفه document.

الإرسال إلى subscribeUrl من شيفرتك الخاصة لا يتطلب أي بيانات اعتماد. أرسل الإجابات بصيغة JSON، وأضف الصفحة التي كان عليها النموذج بوصفها oe_source، ولا ترسل oe_started، وأرسل oe_website فارغًا أو لا ترسله أصلًا. وكل الاشتراكات من شبكة واحدة تتقاسم حدًّا واحدًا قدره 40 اشتراكًا كل عشر دقائق، لذا فالخادم الذي ينقل اشتراكات أشخاص كثيرين يبلغه سريعًا: أضف من تعرفهم بالفعل عبر استيراد الجمهور بدلًا من ذلك.