النطاقات
`domains.list` و`list_all` و`iterate` و`get` و`update`.
كل الدوالّ
page = client.domains.listpage.items.each { |row| puts "#{row[:domain]} #{row.dig(:sending, :canSend)}" } domain = client.domains.get("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f")puts domain.dig(:receiving, :verified), domain.dig(:sending, :status) domain[:addresses].each do |entry| puts "#{entry[:address]} #{entry[:enabled]}"endالاستقبال والإرسال حقيقتان مستقلتان وتُعادان في صورة Hash منفصلين. فـ receiving.verified تعني أن سجل MX الخاص بالنطاق يجلب بريده إلى هنا وأن تحدي إثبات الملكية منشور. أما sending فيبلّغ عن فحص التوقيع الصادر: تكون status إحدى القيم verified أو pending أو failed أو no_identity أو unknown، وتبيّن canSend ما إذا كان إرسال من هذا النطاق سيُقبل الآن. والحكم السلبي الأقدم من يوم يُعامل كمجهول لا كرفض، لذا فرّع على canSend، الذي يُقرأ عبر domain.dig(:sending, :canSend)، لا على status.
يعيد list صفحة OpenEmail::Page واحدة من النطاقات بالترتيب الأبجدي، ويعيدها list_all كلها في Array واحدة. ويمرّرها iterate واحدًا تلو الآخر إلى كتلة. ودون كتلة يعيد Enumerator.
domain_id = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" updated = client.domains.update(domain_id, trackingHost: "links.acme.com")puts updated.dig(:tracking, :status), updated.dig(:tracking, :record, :name), updated.dig(:tracking, :record, :value) client.domains.update(domain_id, trackingHost: nil)يضبط update نطاق التتبّع المخصص للنطاق أو يعيد فحصه أو يزيله، وهو نطاق فرعي مثل links.acme.com، ويعيد الـ Hash نفسه الذي يعيده get. ويبلّغ tracking عنه في كل قراءة. وإلى أن ينجح فحص، تكون tracking.status بالقيمة pending وتظل الروابط المتتبَّعة وبكسل الفتح تستخدم مضيف OpenEmail الافتراضي. وبمجرد نجاح فحص تصبح active ويستخدم البريد الجديد الصادر من النطاق نطاق التتبّع للاثنين معًا.
يسرد get أيضًا العناوين الموجودة على النطاق. والاستدعاء ذو الصلة هو addresses.list: أي العناوين التي يجوز لهذا المفتاح وضعها في ترويسة From، وهي مجموعة أضيق، ولكل منها حكم canSend. ويعيد OpenEmail::AddressBookPage، الذي يحملها في addresses لا في items، إلى جانب domains وunrestricted. ويعيد list_all الخاص به OpenEmail::AddressBook واحدًا.
app_host مساحة أسماء مستقلة، client.app_host. تقرأ get وset وverify وdelete عنوان تطبيق الويب لمساحة العمل وتغيّره، وهو نطاق فرعي مثل mailbox.acme.com على أحد هذه النطاقات أو على أي نطاق آخر تتحكم فيه مساحة العمل، يسجّل فيه أفرادها الدخول تحت علامة مساحة العمل. ويعيد set سجلات DNS الواجب نشرها، في record، وفي ownershipRecord إن كان النطاق خارج مساحة العمل. ويطلب delete، وكذلك set الذي يستبدل عنوانًا، من تطبيق OAuth رمز تحقق: وإلى أن يحصل عليه، يرفع الاستدعاء خطأ 403 تكون قيمة step_up_required? فيه true.
يضبط branding تلك العلامة التجارية. يقرأ get روابط الرمز والشعار وشعار الوضع الداكن وصورة تسجيل الدخول، والخطين، وخلفية تسجيل الدخول. ويغيّر update الخطوط والخلفية، ويرفع upload_image(variant, data, content_type: nil) إحدى الصور الأربع، ويزيل remove_image(variant) واحدة منها. وقيمة variant هي mark أو wordmark أو wordmark-dark أو login-background، ويسمّيها OpenEmail::BRAND_IMAGE_VARIANTS. وdata هو String ثنائي أو IO أو Pathname. وPathname مثل Pathname("logo.svg") أو File أو ملف مرفوع في Rails يحمل نوعه معه. أما البايتات الأخرى فتحتاج إلى content_type:، والصورة بلا نوع تُرفض بالخطأ 422 invalid_image. والشعار هو ما يضفي العلامة التجارية على عنوان تطبيق الويب، وعلى الرسائل المرسلة لمساحة العمل في الخطة المدفوعة.
المعاملات: domains.get
idStringمطلوب- المعرّف المأخوذ من `domains.list`، وهو UUID يُنشأ عند إضافة النطاق، لا اسم المضيف، لذا فإن `get("example.com")` لا يجد شيئًا. والبحث مقيّد بمساحة عمل المفتاح نفسها كما هو مقيّد بالمعرّف، فنطاق مساحة عمل أخرى يعطي 404، يُرفع في صورة `OpenEmail::NotFoundError`، لا 403. والمعرّف nil أو الفارغ يرفع ArgumentError قبل إرسال أي شيء.
المعاملات: domains.update
idStringمطلوب- معرّف النطاق نفسه الذي يأخذه `get`. والصلاحية المطلوبة هي `domains:write`.
trackingHostString or nil- نطاق فرعي من النطاق، بحد أقصى 512 حرفًا، مثل `links.acme.com`. تُشذَّب المسافات ويُحوَّل إلى أحرف صغيرة، وتُزال بادئة `https://` أو `http://` والمسار والنقطة الأخيرة. والقيمة الجديدة يجري التحقق منها وحفظها وفحصها في الاستدعاء نفسه. أما القيمة التي يحملها النطاق بالفعل فتعيد تشغيل الفحص، إلا إذا كان الفحص الأخير قبل أقل من 30 ثانية. مرّر nil أو String فارغًا لإزالة نطاق التتبّع، واترك الحقل ليبقى كما هو.
المضيف المرفوض يرفع OpenEmail::ApiError يذكر trackingHost في param: 422 مع invalid_tracking_host لاسم لا يمكن استخدامه، مثل اسم خارج النطاق، و409 مع domain_not_verified لمضيف جديد بينما receiving.verified قيمتها false وسجل TXT باسم _openemail-challenge الخاص بالنطاق لم يُنشر بعد، و409 مع tracking_host_in_use لاسم يستخدمه نطاق آخر بالفعل، أو حين يكون نطاق التتبّع مُدارًا من خادم OpenEmail مختلف. ويصل الخطأ 422 في صورة OpenEmail::ValidationError وكل 409 في صورة OpenEmail::ConflictError. والمفتاح المقيّد بعناوين بعينها يحصل على 422 مع capability_unsupported، لأن نطاق التتبّع ينطبق على كل عنوان في النطاق.
التعديل وسائط مسمّاة أو Hash واحد، وتحتفظ حقوله بأسماء API بصيغة camelCase، فيُرسل tracking_host: كما كُتب ويُرفض بالخطأ 422 unknown_parameter. ويأخذ update أيضًا catchAll، وstorageHost لنطاق ملفات مثل files.acme.com، وdmarcPolicy. وكل حقل اختياري، ويشرح مرجع التوابع كلًّا منها. ويعيد الـ gem محاولة update كما يفعل مع القراءة، لأن التكرار يجد المضيف مضبوطًا أصلًا وفي أقصى الأحوال يفحصه مجددًا.
الاستجابة: نطاق (domains.get)
objectString- دائمًا السلسلة `domain`، في سجلات `list` وفي هذا السجل على حد سواء.
idString- UUID الخاص بالنطاق. ثابت طوال عمر الصف، وهو المقبض الوحيد الذي تقبله استدعاءات النطاق الأخرى.
domainString- اسم المضيف المجرّد بأحرف صغيرة: `example.com`. فريد على مستوى المنتج كله، بمالك واحد لكل نطاق، فلا تستطيع مساحتا عمل المطالبة به معًا.
receiving.verifiedBoolean- صحيحة بمجرد أن يُظهر DNS أن سجل MX للنطاق يسمي مضيفًا يجلب بريده إلى هنا، وحيث يحمل السجل رمز تحدٍّ، أن سجل TXT المطابق `_openemail-challenge` منشور. وسجل MX وحده لا يثبت شيئًا، لأن كل نطاق نستقبل له ينشر أسماء المضيفات نفسها، ولهذا وُجد الرمز، ولهذا كانت هذه الراية هي البوابة التي يفحصها تسليم البريد الوارد قبل قبول أي رسالة.
receiving.verifiedAtString or nil- متى نجح التحقق، في صورة String بصيغة ISO 8601. ويكون nil ما دام لم ينجح، و`verified` مشتق من هذا العمود بالضبط، فلا يمكن أن يختلف الاثنان أبدًا.
receiving.catchAllBoolean- ما إذا كان أي جزء محلي مقبولًا. وهو مفعّل افتراضيًا للنطاقات المضافة منذ أن صار هذا هو القاعدة. ومع إيقافه لا تُقبل سوى العناوين المسمّاة على النطاق ويُرفض الباقي في وقت SMTP، فيتلقى المرسل ارتدادًا بدل الصمت.
receiving.lastCheckedAtString or nil- متى سُئل DNS آخر مرة عن هذا النطاق. ويكون nil حين لم يُسأل DNS قط، وهو ما يُقرأ بشكل مختلف تمامًا عن الفشل بالنسبة لمن أضاف نطاقًا قبل دقيقة. وقراءة نطاق غير متحقق منه تسأل DNS مجددًا بمجرد أن يمضي على الفحص الأخير أكثر من 20 ثانية، فاستطلاع `get` طريقة لانتظار التحقق، ويفحص `verify` فورًا.
receiving.errorString or nil- لماذا لم ينجح الفحص الأخير، بكلمات يستطيع المالك التصرف بناءً عليها: ومن أمثلتها المعتادة `No MX records yet. DNS changes can take a few minutes to spread.` ويكون nil بمجرد نجاح الفحص، وهو مخزَّن لا مشتق، فتقول إعادة التحميل وإعادة الفحص المجدولة الشيء نفسه.
sending.statusString- حالة التوقيع الصادر كما رآها الفحص الأخير: `verified` أو `pending` أو `failed` أو `no_identity` أو `unknown`. وتُقرأ من الفحص المخزَّن، لذا تخبرك `sending.checkedAt` كم عمرها.
sending.canSendBoolean- ما إذا كان إرسال من هذا النطاق سيُقبل الآن. والحكم السلبي الأقدم من يوم يُعامل كمجهول لا كرفض، فقد تكون هذه القيمة صحيحة بينما `status` بالقيمة `pending`. فرّع عليها قبل الإرسال: فالقيمة الخاطئة تعني أن `emails.send` من هذا النطاق يُرفض بـ 409 مع `domain_not_sendable`.
sending.checkedAtString or nil- متى فُحصت حالة التوقيع آخر مرة، في صورة String بصيغة ISO 8601. وتكون nil حين لم تُفحص قط، وهو ما يُقرأ بشكل مختلف تمامًا عن الفشل.
sending.errorString or nil- آخر فشل في التوقيع بالكلمات، أو nil بمجرد النجاح.
sending.noteString- واحدة من خمس جمل، تُختار بحسب `sending.status`، تشرح معنى تلك الحالة بكلمات يستطيع مالك النطاق التصرف بناءً عليها. وهي نص للقراءة البشرية، لذا فرّع على `sending.canSend` لا على هذا الحقل.
trackingHash- نطاق التتبع المخصص للنطاق، في سجلات `list` وفي هذا السجل على حد سواء، وهو ما يغيّره `update`.
tracking.hostString or nil- نطاق التتبّع، مثل `links.acme.com`، أو nil حين لا يُضبط أي نطاق.
tracking.statusString- تعني `none` أنه لا يوجد نطاق تتبع مضبوط، وتعني `pending` أنه لم ينجح في أي فحص قط، وتعني `active` أن البريد الجديد يستخدمه، وتعني `failed` أنه نجح من قبل ثم خرج من الاستخدام. والمضيف النشط يخرج من الاستخدام بعد ثلاثة فحوص فاشلة متتالية، أو حين يتجاوز عمر آخر فحص ناجح ساعتين.
tracking.activeBoolean- صحيحة تمامًا حين تكون `status` هي `active`، أي حين تستخدم الروابط المتتبَّعة وبكسل الفتح في البريد الجديد من النطاق ذلك المضيف.
tracking.targetString- العنوان الذي يشير إليه سجل CNAME، والمُعدّ لنطاق التتبّع هذا وحده. ويكون String فارغًا ما دام `host` بقيمة nil، وما دام عنوان مضيف جديد قيد الإعداد.
tracking.recordHash or nil- السجل الواجب نشره، Hash فيه `type` (دائمًا `CNAME`) و`name` و`value`، باسم `host` وقيمته `target`. ويكون nil عندما لا يوجد نطاق تتبّع، وكذلك ما دام عنوان مضيف جديد قيد الإعداد، لذا يقرؤه `dig(:tracking, :record, :value)` بأمان.
tracking.checkedAtString or nil- متى فُحص المضيف آخر مرة، في صورة String بصيغة ISO 8601. ويكون nil حتى الفحص الأول.
tracking.verifiedAtString or nil- متى نجح فحص آخر مرة، في صورة String بصيغة ISO 8601. ويكون nil لمضيف لم ينجح في أي فحص قط.
tracking.errorString or nil- ما وجده الفحص الأخير، بكلمات يستطيع مالك النطاق التصرف بناءً عليها. ويكون nil عندما ينجح الفحص الأخير أو عندما لا يكون أي فحص قد جرى. والمضيف الذي فشل في فحص أو فحصين يظل `active` ويحمل السبب هنا.
addressesArray<Hash>- كل صفوف العناوين على النطاق، وهو ما يضيفه `get` على صف `list`. ويشمل ذلك الصفوف التي كتبها التسليم نفسه في ظل catch-all، وهذه تتوقف عن القبول فور إيقاف catch-all، فالـ Array ليست قائمة بما سيستقبل البريد.
addresses[].addressString- العنوان الكامل، يُعاد بناؤه من الجزء المحلي المخزَّن واسم المضيف ويُحوَّل إلى أحرف صغيرة، فيطابق دائمًا `domain` أعلاه بدلًا من أن ينحرف عنه.
addresses[].enabledBoolean- القيمة false تعطّل العنوان، والعنوان المعطَّل يُرفض حتى حين يكون catch-all مفعّلًا. وكل صف يُسرد في الحالتين، فرشّح على هذا الحقل بدل قراءة الـ Array كمجموعة العناوين العاملة.
createdAtString- متى أُضيف صف النطاق، في صورة String بصيغة ISO 8601. وليس وقت التحقق من النطاق: فذاك هو `receiving.verifiedAt`، الذي قد يكون nil بينما هذا مضبوط.