النماذج
`forms.list` و`get` و`create` و`update` و`delete` و`publish` و`pause` و`resume` و`duplicate` و`analytics` و`listStarters` و`getStarter` و`listSubmissions` و`getSubmission` و`deleteSubmission` و`deleteSubmissions` و`approveSubmission` و`resendConfirmation` و`subscribe`.
كل الدوالّ
const form = await openemail.forms.create({ name: 'Newsletter sign-up', starter: 'newsletter', settings: { audienceIds: ['aud_4c1b8e2a7d9f05c36b4e8a71'] }, publish: true,}) console.log(form.url, form.subscribeUrl) const saved = await openemail.forms.update(form.id, { settings: { doubleOptIn: true, senderAddress: '[email protected]' }, expectedUpdatedAt: form.updatedAt,}) const signup = await openemail.forms.subscribe(form.id, { email: '[email protected]', first_name: 'Ann', consent: true,}) for await (const submission of openemail.forms.iterateSubmissions(form.id, { status: 'pending' })) { if (submission.expired) await openemail.forms.resendConfirmation(form.id, submission.id)} const stats = await openemail.forms.analytics(form.id, { days: 30 })const starters = await openemail.forms.listStarters() await openemail.forms.pause(form.id)await openemail.forms.resume(form.id)const copy = await openemail.forms.duplicate(form.id)await openemail.forms.delete(copy.id) console.log(saved.senderIssue, signup.outcome, stats.totals.conversion, starters.length)يحتفظ النموذج بمسودة document وبـpublishedDocument الذي يراه الزوار. ويغيّر update المسودة والإعدادات، وينشر publish المسودة. وتسري الإعدادات فورًا، سواء نُشر النموذج أم لا، ويرفض expectedUpdatedAt بـ 409 version_conflict أي حفظ قد يكتب فوق حفظ شخص آخر.
القراءة تتطلب forms:read والتغيير يتطلب forms:write. ويتطلب approveSubmission أيضًا contacts:write، لأنه يضيف جهة اتصال. ويتطلب resendConfirmation أيضًا emails:send، وكذلك الاستدعاء الذي يجعل النموذج يرسل بريدًا: تفعيل doubleOptIn، أو تعيين senderAddress أو رسالة التأكيد، أو نشر نموذج ذي تأكيد مزدوج أو استئنافه. ويطلب delete رمز تحقق من رمز وصول OAuth، ولا يطلبه من مفتاح API أبدًا.
يسجّل subscribe اشتراك الشخص كما تفعل صفحة النموذج، ولا يرسل أي بيانات اعتماد، حتى من عميل يحملها. وكل الاشتراكات من شبكة واحدة تتقاسم حدًّا واحدًا قدره 40 اشتراكًا كل عشر دقائق، لذا فالخادم الذي ينقل اشتراكات أشخاص كثيرين يبلغه سريعًا: أضف من تعرفهم بالفعل عبر audiences.importContacts بدلًا من ذلك. ومرّر الصفحة التي كان عليها النموذج بوصفها 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، ويتصفّح listAll وiterate كل الصفحات. أما get وcreate وupdate وpublish وpause وresume وduplicate فتُرجع FormDetailResource، الذي يضيف document وpublishedDocument وsettings وaudiences وsenderIssue وsenderProblem.
idstring- المعرّف الدائم، `frm_` يليه 24 حرفًا ست عشريًا.
status'draft' | 'live' | 'paused'- `draft` حتى أول نشر، ثم `live` ما دام يستقبل الاشتراكات و`paused` ما دام لا يستقبلها. ولا يعود النموذج أبدًا إلى `draft`.
urlstring- الصفحة المستضافة للنموذج المنشور، لمشاركتها رابطًا.
subscribeUrlstring- حيث يرسل نموذج HTML العادي، أو `fetch`، الإجابات.
documentFormDocument- المسودة: `fields` بالترتيب، ونصوص `copy` المحيطة بها، و`style`.
publishedDocumentFormDocument | null- ما يراه الزوار الآن. وقيمته null حتى أول نشر.
settingsFormSettings- إلى أين تذهب الاشتراكات وما يحدث بعد كل اشتراك: `audienceIds` و`doubleOptIn` و`senderAddress` ورسالة التأكيد و`successAction` و`redirectUrl` و`notifyAddresses`.
hasUnpublishedChangesboolean- قيمته true حين تختلف المسودة عما يراه الزوار. وقيمته false دائمًا قبل أول نشر.
senderIssue'missing' | 'not_sendable' | 'not_allowed' | null- لماذا يتعذّر على نموذج ذي تأكيد مزدوج إرسال رسائل التأكيد الآن، أو null حين يمكنه ذلك.
statsFormStats- `views` و`submissions` و`added` و`pending` و`lastSubmittedAt`، محسوبةً لحظة القراءة.
الردود
يُرجع listSubmissions الصفحات من الأحدث إلى الأقدم، مع q للبحث في عناوين البريد الإلكتروني وstatus لاختيار pending أو added، ويتصفّح listAllSubmissions وiterateSubmissions كل الصفحات. ويحتفظ كل FormSubmissionResource بالإجابات كما أُرسلت، بتسمياتها، فتبقى قراءته صحيحة بعد تغيّر النموذج.
يُرجع resendConfirmation الرد مع confirmationSent. وتكون قيمته false حين لا يُرسل شيء: فالعنوان الواحد يتلقى تأكيدًا واحدًا لكل نموذج كل عشر دقائق وخمسة في اليوم عبر مساحة العمل، والرد المُضاف لا يتلقى أي تأكيد. ويميّز expired الاشتراك المعلّق الذي انتهت صلاحية أحدث رابط له.
