النطاقات
`domains.list` و`list_all` و`iterate` و`get` و`update`.
كل الدوالّ
from openemail import openemail domains = openemail.domains.list()domain = openemail.domains.get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f') print(domain['receiving']['verified'], domain['sending']['status'])for address in domain['addresses']: print(address['address'], address['enabled']) updated = openemail.domains.update(domain['id'], {'trackingHost': 'links.acme.com'})tracking = updated['tracking']print(tracking['status']) if tracking['record'] is not None: print(tracking['record']['name'], tracking['record']['value']) openemail.domains.update(domain['id'], {'trackingHost': None})الاستقبال والإرسال حقيقتان مستقلتان ويُعادان ككائنين منفصلين. فـ receiving.verified تعني أن سجل MX الخاص بالنطاق يجلب بريده إلى هنا وأن تحدي إثبات الملكية منشور. أما sending فيبلّغ عن فحص التوقيع الصادر: تكون status إحدى القيم verified أو pending أو failed أو no_identity أو unknown، وتبيّن canSend ما إذا كان إرسال من هذا النطاق سيُقبل الآن. والحكم السلبي الأقدم من يوم يُعامل كمجهول لا كرفض، لذا فرّع على canSend لا على status.
يضبط update نطاق التتبع المخصص للنطاق أو يعيد فحصه أو يزيله، وهو نطاق فرعي مثل links.acme.com، ويعيد DomainDetailResource نفسه الذي يعيده get. ويبلّغ tracking عنه في كل قراءة. وإلى أن ينجح فحص، تكون tracking.status بالقيمة pending وتظل الروابط المتتبَّعة وبكسل الفتح تستخدم مضيف OpenEmail الافتراضي. وبمجرد نجاح فحص تصبح active ويستخدم البريد الجديد الصادر من النطاق نطاق التتبع للاثنين معًا.
يسرد get أيضًا العناوين الموجودة على النطاق. والاستدعاء ذو الصلة هو addresses.list(): أي كل عنوان يجوز لهذا المفتاح وضعه في ترويسة From، وهي مجموعة أضيق.
app_host مساحة أسماء مستقلة. تقرأ get وset وverify وdelete عنوان تطبيق الويب لمساحة العمل وتغيّره، وهو نطاق فرعي مثل mailbox.acme.com على أحد هذه النطاقات أو على أي نطاق آخر تتحكم فيه مساحة العمل، يسجّل فيه أفرادها الدخول تحت علامة مساحة العمل. ويعيد set سجلات DNS الواجب نشرها، ويطلب delete من تطبيق OAuth رمز تحقق، وكذلك يفعل set الذي يستبدل مضيفًا تملكه مساحة العمل بالفعل.
branding يضبط تلك العلامة التجارية. get يقرأ روابط الرمز والشعار وشعار الوضع الداكن وصورة تسجيل الدخول، والخطين، وخلفية تسجيل الدخول. update يغيّر الخطوط والخلفية، وupload_image(variant, data, content_type=...) يرفع إحدى الصور الأربع، وremove_image(variant) يزيل واحدة. والشعار هو ما يضفي العلامة التجارية على عنوان تطبيق الويب، وعلى الرسائل المرسلة لمساحة العمل في الخطة المدفوعة.
المعاملات: domains.get
idstrمطلوب- المعرّف المأخوذ من `domains.list`، وهو UUID يُنشأ عند إضافة النطاق، لا اسم المضيف، لذا فإن `get('example.com')` لا يجد شيئًا. والبحث مقيّد باتصال المفتاح نفسه كما هو مقيّد بالمعرّف، فنطاق مساحة عمل أخرى يعطي 404 لا 403.
المعاملات: domains.update
idstrمطلوب- معرّف النطاق نفسه الذي يأخذه `get`. والصلاحية المطلوبة هي `domains:write`.
patch['trackingHost']str | None- نطاق فرعي من النطاق، بحد أقصى 512 حرفًا، مثل `links.acme.com`. تُقلَّم المسافات ويُحوَّل إلى أحرف صغيرة، وتُزال بادئة `https://` أو `http://` والمسار والنقطة الأخيرة. والقيمة الجديدة يجري التحقق منها وحفظها وفحصها في الاستدعاء نفسه. أما القيمة التي يحملها النطاق بالفعل فتعيد تشغيل الفحص، إلا إذا كان الفحص الأخير قبل أقل من 30 ثانية. وتؤدي `None` أو سلسلة فارغة إلى إزالة نطاق التتبع.
المضيف المرفوض يرفع OpenEmailApiError يذكر trackingHost في param: 422 مع invalid_tracking_host لاسم لا يمكن استخدامه، مثل اسم خارج النطاق، و409 مع domain_not_verified لمضيف جديد بينما receiving.verified بقيمة false وسجل TXT باسم _openemail-challenge للنطاق لم يُنشر بعد، و409 مع tracking_host_in_use لاسم يستخدمه نطاق آخر بالفعل، أو حين يكون نطاق التتبع مُدارًا من خادم OpenEmail مختلف. والمفتاح المقيّد بعناوين بعينها يحصل على 422 مع capability_unsupported، لأن نطاق التتبع ينطبق على كل عنوان في النطاق.
الاستجابة: DomainDetailResource
objectLiteral['domain']- دائمًا السلسلة `domain`، في سجلات `list` وفي هذا السجل على حد سواء.
idstr- معرّف UUID للنطاق. ثابت طوال عمر السجل، وهو المقبض الوحيد الذي تقبله بقية دوال domains.
domainstr- اسم المضيف المجرّد بأحرف صغيرة: `example.com`. فريد على مستوى المنتج كله، بمالك واحد لكل نطاق، فلا تستطيع مساحتا عمل المطالبة به معًا.
receiving.verifiedbool- صحيحة بمجرد أن يُظهر DNS أن سجل MX للنطاق يسمي مضيفًا يجلب بريده إلى هنا، وحيث يحمل السجل رمز تحدٍّ، أن سجل TXT المطابق `_openemail-challenge` منشور. وسجل MX وحده لا يثبت شيئًا، لأن كل نطاق نستقبل له ينشر أسماء المضيفات نفسها، ولهذا وُجد الرمز، ولهذا كانت هذه الراية هي البوابة التي يفحصها تسليم البريد الوارد قبل قبول أي رسالة.
receiving.verifiedAtstr | None- متى نجح التحقق، بصيغة ISO-8601. ويكون null ما دام لم ينجح، و`verified` مشتقة من هذا العمود بالضبط، فلا يمكن أن يتناقض الاثنان.
receiving.catchAllbool- ما إذا كان أي جزء محلي مقبولًا. مفعّل افتراضيًا للنطاقات المضافة منذ أن صار هذا هو القاعدة؛ ومع إيقافه لا تُقبل سوى العناوين المسمّاة على النطاق ويُرفض الباقي في وقت SMTP، فيتلقى المرسل ارتدادًا بدل الصمت.
receiving.lastCheckedAtstr | None- متى سُئل DNS آخر مرة عن هذا النطاق. وnull تعني أنه لم يُسأل قط، وهو ما يُقرأ بشكل مختلف تمامًا عن فشل الفحص بالنسبة لمن أضاف نطاقًا قبل دقيقة. وهذه النقطة تبلّغ عن النتيجة المخزَّنة ولا تجري فحصًا خاصًا بها أبدًا.
receiving.errorstr | None- لماذا لم ينجح الفحص الأخير، بكلمات يستطيع المالك التصرف بناءً عليها: ومن أمثلتها المعتادة `No MX records yet. DNS changes can take a few minutes to spread.` ويكون null بمجرد النجاح، وهو مخزَّن لا مشتق، فتقول إعادة التحميل وإعادة الفحص المجدولة الشيء نفسه.
sending.statusLiteral['verified', 'pending', 'failed', 'no_identity', 'unknown']- حالة التوقيع الصادر كما رآها الفحص الأخير. تُقرأ من الفحص المخزَّن ولا تُستقصى مع هذا الطلب، لذا تخبرك `sending.checkedAt` كم عمرها.
sending.canSendbool- ما إذا كان إرسال من هذا النطاق سيُقبل الآن. والحكم السلبي الأقدم من يوم يُعامل كمجهول لا كرفض، فقد تكون هذه القيمة صحيحة بينما `status` بالقيمة `pending`. فرّع عليها قبل الإرسال: فالقيمة الخاطئة تعني أن `emails.send` من هذا النطاق يُرفض بـ 409 مع `domain_not_sendable`.
sending.checkedAtstr | None- متى فُحصت حالة التوقيع آخر مرة، بصيغة ISO-8601. وnull تعني أنها لم تُفحص قط، وهو ما يُقرأ بشكل مختلف تمامًا عن الفشل.
sending.errorstr | None- آخر فشل في التوقيع موصوفًا بالكلمات، أو null بمجرد نجاحه.
sending.notestr- واحدة من خمس جمل، تُختار بحسب `sending.status`، تشرح معنى تلك الحالة بكلمات يستطيع مالك النطاق التصرف بناءً عليها. نص للقراءة البشرية. فرّع على `sending.canSend` لا على هذا الحقل.
trackingDomainTracking- نطاق التتبع المخصص للنطاق، في سجلات `list` وفي هذا السجل على حد سواء، وهو ما يغيّره `update`.
tracking.hoststr | None- نطاق التتبع، مثل `links.acme.com`، أو null عندما لا يكون مضبوطًا.
tracking.statusLiteral['none', 'pending', 'active', 'failed']- تعني `none` أنه لا يوجد نطاق تتبع مضبوط، وتعني `pending` أنه لم ينجح في أي فحص قط، وتعني `active` أن البريد الجديد يستخدمه، وتعني `failed` أنه نجح من قبل ثم خرج من الاستخدام. والمضيف النشط يخرج من الاستخدام بعد ثلاثة فحوص فاشلة متتالية، أو حين يتجاوز عمر آخر فحص ناجح ساعتين.
tracking.activebool- صحيحة تمامًا حين تكون `status` هي `active`، أي حين تستخدم الروابط المتتبَّعة وبكسل الفتح في البريد الجديد من النطاق ذلك المضيف.
tracking.targetstr- العنوان الذي يشير إليه سجل CNAME، مُعدّ لنطاق التتبع هذا وحده. ويكون سلسلة فارغة ما دام `host` بالقيمة null، وكذلك ما دام عنوان مضيف جديد قيد الإعداد.
tracking.recordDomainTrackingRecord | None- السجل الواجب نشره، باسم `host` وقيمته `target`. وهو null حين لا يوجد نطاق تتبع، وكذلك ما دام العنوان الخاص بمضيف جديد قيد التجهيز.
tracking.checkedAtstr | None- متى فُحص المضيف آخر مرة، بصيغة ISO-8601. وهو null حتى أول فحص.
tracking.verifiedAtstr | None- متى اجتاز فحصًا آخر مرة، بصيغة ISO-8601. وهو null لمضيف لم يجتز فحصًا قط.
tracking.errorstr | None- ما وجده آخر فحص، بكلمات يستطيع مالك النطاق التصرف بناءً عليها. وهو null حين ينجح آخر فحص أو حين لم يُجرَ أي فحص بعد. والمضيف الذي أخفق في فحص أو فحصين يظل `active` ويحمل السبب هنا.
addresseslist[DomainDetailResourceAddressesItem]- كل سجلات العناوين على النطاق، وهو ما يضيفه `get` على سجل `list`. ويشمل ذلك السجلات التي كتبها التسليم نفسه في ظل catch-all، وهذه تتوقف عن القبول فور إيقاف catch-all، فالمصفوفة ليست قائمة بما سيستقبل.
addresses[].addressstr- العنوان الكامل، يُعاد بناؤه من الجزء المحلي المخزَّن واسم المضيف ويُحوَّل إلى أحرف صغيرة، فيطابق دائمًا `domain` أعلاه بدلًا من أن ينحرف عنه.
addresses[].enabledbool- القيمة false تعطّل العنوان، والعنوان المعطّل يُرفض حتى مع تفعيل catch-all. وكل سجل يُدرج في الحالتين، لذا رشّح على هذا الحقل بدلًا من قراءة المصفوفة على أنها مجموعة العناوين العاملة.
createdAtstr- متى أُضيف سجل النطاق، بصيغة ISO-8601. وليس وقت التحقق منه: فذاك هو `receiving.verifiedAt`، الذي قد يكون null بينما هذا مضبوط.
المرجع
domains.list()المرجع الكاملdomains.list_all()المرجع الكاملdomains.iterate()المرجع الكاملdomains.get()المرجع الكاملdomains.update()المرجع الكاملapp_host.get()المرجع الكاملapp_host.set()المرجع الكاملapp_host.verify()المرجع الكاملapp_host.delete()المرجع الكاملbranding.get()المرجع الكاملbranding.update()المرجع الكاملbranding.upload_image()المرجع الكاملbranding.remove_image()المرجع الكامل