النماذج
`forms.list` و`get` و`create` و`update` و`delete` و`publish` و`pause` و`resume` و`duplicate` و`analytics` و`list_starters` و`get_starter` و`list_submissions` و`get_submission` و`delete_submission` و`delete_submissions` و`approve_submission` و`resend_confirmation` و`subscribe`.
كل الدوالّ
from openemail import openemail form = openemail.forms.create({ 'name': 'Newsletter sign-up', 'starter': 'newsletter', 'settings': {'audienceIds': ['aud_4c1b8e2a7d9f05c36b4e8a71']}, 'publish': True,}) print(form['url'], form['subscribeUrl']) saved = openemail.forms.update(form['id'], { 'settings': {'doubleOptIn': True, 'senderAddress': '[email protected]'}, 'expectedUpdatedAt': form['updatedAt'],}) signup = openemail.forms.subscribe(form['id'], { 'email': '[email protected]', 'first_name': 'Ann', 'consent': True,}) for submission in openemail.forms.iterate_submissions(form['id'], status='pending'): if submission['expired']: openemail.forms.resend_confirmation(form['id'], submission['id']) stats = openemail.forms.analytics(form['id'], days=30)starters = openemail.forms.list_starters() openemail.forms.pause(form['id'])openemail.forms.resume(form['id'])copy = openemail.forms.duplicate(form['id'])openemail.forms.delete(copy['id']) print(saved['senderIssue'], signup['outcome'], stats['totals']['conversion'], len(starters))يحتفظ النموذج بمسودة document وبـpublishedDocument الذي يراه الزوار. ويغيّر update المسودة والإعدادات، وينشر publish المسودة. وتسري الإعدادات فورًا، سواء نُشر النموذج أم لا، ويرفض expectedUpdatedAt بـ 409 version_conflict أي حفظ قد يكتب فوق حفظ شخص آخر.
القراءة تتطلب forms:read والتغيير يتطلب forms:write. ويتطلب approve_submission أيضًا contacts:write، لأنه يضيف جهة اتصال. ويتطلب resend_confirmation أيضًا emails:send، وكذلك الاستدعاء الذي يجعل النموذج يرسل بريدًا: تفعيل doubleOptIn، أو تعيين senderAddress أو رسالة التأكيد، أو نشر نموذج ذي تأكيد مزدوج أو استئنافه. ويطلب delete رمز تحقق من رمز وصول OAuth، ولا يطلبه من مفتاح API أبدًا.
يسجّل subscribe اشتراك الشخص كما تفعل صفحة النموذج، ولا يرسل أي بيانات اعتماد، حتى من عميل يحملها. وكل الاشتراكات من شبكة واحدة تتقاسم حدًّا واحدًا قدره 40 اشتراكًا كل عشر دقائق، لذا فالخادم الذي ينقل اشتراكات أشخاص كثيرين يبلغه سريعًا: أضف من تعرفهم بالفعل عبر audiences.import_contacts بدلًا من ذلك. ومرّر الصفحة التي كان عليها النموذج بوصفها oe_source، ولا ترسل oe_started، وأرسل oe_website فارغًا أو لا ترسله أصلًا.
الاستجابة 422 من subscribe هي invalid_form_submission، ويسرد fields في الخطأ كل إجابة مفقودة أو غير صالحة بالشكل {'key': ..., 'error': ...}، بأسباب مثل required وemail وoption. والعميل مخصّص للخوادم. أما في المتصفح فأرسل الإجابات عبر fetch إلى subscribeUrl الخاص بالنموذج، في متن بصيغة JSON أو مع ترويسة Accept: application/json، وهو يجيب بصيغة JSON من أي أصل. ومن دون أيٍّ منهما يجيب بإعادة توجيه 303 إلى الصفحة المستضافة.
الاستجابة: FormDetailResource
يُرجع list صفحة واحدة من FormResource، من الأحدث إلى الأقدم، دون document وsettings، ويتصفّح list_all وiterate كل الصفحات. أما get وcreate وupdate وpublish وpause وresume وduplicate فتُرجع FormDetailResource، الذي يضيف document وpublishedDocument وsettings وaudiences وsenderIssue وsenderProblem.
idstr- المعرّف الدائم، `frm_` يليه 24 حرفًا ست عشريًا.
statusLiteral['draft', 'live', 'paused']- `draft` حتى أول نشر، ثم `live` ما دام يستقبل الاشتراكات و`paused` ما دام لا يستقبلها. ولا يعود النموذج أبدًا إلى `draft`.
urlstr- الصفحة المستضافة للنموذج المنشور، لمشاركتها رابطًا.
subscribeUrlstr- حيث يرسل نموذج HTML العادي، أو `fetch`، الإجابات.
documentFormDocument- المسودة: `fields` بالترتيب، ونصوص `copy` المحيطة بها، و`style`.
publishedDocumentFormDocument | None- ما يراه الزوار الآن. وقيمته `None` حتى أول نشر.
settingsFormSettings- إلى أين تذهب الاشتراكات وما يحدث بعد كل اشتراك: `audienceIds` و`doubleOptIn` و`senderAddress` ورسالة التأكيد و`successAction` و`redirectUrl` و`notifyAddresses`.
hasUnpublishedChangesbool- قيمته `True` حين تختلف المسودة عما يراه الزوار. وقيمته `False` دائمًا قبل أول نشر.
senderIssueLiteral['missing', 'not_sendable', 'not_allowed'] | None- لماذا يتعذّر على نموذج ذي تأكيد مزدوج إرسال رسائل التأكيد الآن، أو `None` حين يمكنه ذلك.
statsFormStats- `views` و`submissions` و`added` و`pending` و`lastSubmittedAt`، محسوبةً لحظة القراءة.
الردود
يُرجع list_submissions الصفحات من الأحدث إلى الأقدم، مع q للبحث في عناوين البريد الإلكتروني وstatus لاختيار pending أو added، ويتصفّح list_all_submissions وiterate_submissions كل الصفحات. ويحتفظ كل FormSubmissionResource بالإجابات كما أُرسلت، بتسمياتها، فتبقى قراءته صحيحة بعد تغيّر النموذج.
يُرجع resend_confirmation الرد مع confirmationSent. وتكون قيمته False حين لا يُرسل شيء: فالعنوان الواحد يتلقى تأكيدًا واحدًا لكل نموذج كل عشر دقائق وخمسة في اليوم عبر مساحة العمل، والرد المُضاف لا يتلقى أي تأكيد. ويميّز expired الاشتراك المعلّق الذي انتهت صلاحية أحدث رابط له.
المرجع
forms.list()المرجع الكاملforms.list_all()المرجع الكاملforms.iterate()المرجع الكاملforms.get()المرجع الكاملforms.create()المرجع الكاملforms.update()المرجع الكاملforms.delete()المرجع الكاملforms.publish()المرجع الكاملforms.pause()المرجع الكاملforms.resume()المرجع الكاملforms.duplicate()المرجع الكاملforms.analytics()المرجع الكاملforms.list_starters()المرجع الكاملforms.get_starter()المرجع الكاملforms.list_submissions()المرجع الكاملforms.list_all_submissions()المرجع الكاملforms.iterate_submissions()المرجع الكاملforms.get_submission()المرجع الكاملforms.delete_submission()المرجع الكاملforms.delete_submissions()المرجع الكاملforms.approve_submission()المرجع الكاملforms.resend_confirmation()المرجع الكاملforms.subscribe()المرجع الكامل