SDK
النطاقات
`domains.list` و`get` و`update`.
كل الدوال
const domains = await openemail.domains.list()const domain = await openemail.domains.get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f') console.log(domain.receiving.verified, domain.sending.status)for (const address of domain.addresses) console.log(address.address, address.enabled) const updated = await openemail.domains.update(domain.id, { trackingHost: 'links.acme.com' })console.log(updated.tracking.status, updated.tracking.record?.name, updated.tracking.record?.value) await openemail.domains.update(domain.id, { trackingHost: null })الاستقبال والإرسال حقيقتان مستقلتان ويُعادان ككائنين منفصلين. فـ 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، وهي مجموعة أضيق.
المعاملات: domains.get
domainIdstringمطلوب- المعرّف المأخوذ من `domains.list`، وهو UUID يُنشأ عند إضافة النطاق، لا اسم المضيف، لذا فإن `get('example.com')` لا يجد شيئًا. والبحث مقيّد باتصال المفتاح نفسه كما هو مقيّد بالمعرّف، فنطاق مساحة عمل أخرى يعطي 404 لا 403.
المعاملات: domains.update
idstringمطلوب- معرّف النطاق نفسه الذي يأخذه `get`. والصلاحية المطلوبة هي `domains:write`.
patch.trackingHoststring | nullمطلوب- نطاق فرعي من النطاق، بحد أقصى 512 حرفًا، مثل `links.acme.com`. تُقلَّم المسافات ويُحوَّل إلى أحرف صغيرة، وتُزال بادئة `https://` أو `http://` والمسار والنقطة الأخيرة. والقيمة الجديدة يجري التحقق منها وحفظها وفحصها في الاستدعاء نفسه. أما القيمة التي يحملها النطاق بالفعل فتعيد تشغيل الفحص، إلا إذا كان الفحص الأخير قبل أقل من 30 ثانية. وتؤدي `null` أو سلسلة فارغة إلى إزالة نطاق التتبع.
المضيف المرفوض يرمي OpenEmailApiError يذكر trackingHost في param: 422 مع invalid_tracking_host لاسم لا يمكن استخدامه، مثل اسم خارج النطاق، و409 مع domain_not_verified لمضيف جديد بينما receiving.verified خاطئة وسجل TXT باسم _openemail-challenge لم يُنشر بعد، و409 مع tracking_host_in_use لاسم يستخدمه نطاق آخر بالفعل، أو حين يكون نطاق التتبع مُدارًا من خادم OpenEmail مختلف. والمفتاح المقيّد بعناوين بعينها يحصل على 422 مع capability_unsupported، لأن نطاق التتبع ينطبق على كل عنوان في النطاق.
الاستجابة: DomainDetailResource
object'domain'- دائمًا السلسلة `domain`، في سجلات `list` وفي هذا السجل على حد سواء.
idstring- معرّف UUID للنطاق. ثابت طوال عمر السجل، وهو المقبض الوحيد الذي تقبله بقية دوال domains.
domainstring- اسم المضيف المجرّد بأحرف صغيرة: `example.com`. فريد على مستوى المنتج كله، بمالك واحد لكل نطاق، فلا تستطيع مساحتا عمل المطالبة به معًا.
receiving.verifiedboolean- صحيحة بمجرد أن يُظهر DNS أن سجل MX للنطاق يسمي مضيفًا يجلب بريده إلى هنا، وحيث يحمل السجل رمز تحدٍّ، أن سجل TXT المطابق `_openemail-challenge` منشور. وسجل MX وحده لا يثبت شيئًا، لأن كل نطاق نستقبل له ينشر أسماء المضيفات نفسها، ولهذا وُجد الرمز، ولهذا كانت هذه الراية هي البوابة التي يفحصها تسليم البريد الوارد قبل قبول أي رسالة.
receiving.verifiedAtstring | null- متى نجح التحقق، بصيغة ISO-8601. ويكون null ما دام لم ينجح، و`verified` مشتقة من هذا العمود بالضبط، فلا يمكن أن يتناقض الاثنان.
receiving.catchAllboolean- ما إذا كان أي جزء محلي مقبولًا. مفعّل افتراضيًا للنطاقات المضافة منذ أن صار هذا هو القاعدة؛ ومع إيقافه لا تُقبل سوى العناوين المسمّاة على النطاق ويُرفض الباقي في وقت SMTP، فيتلقى المرسل ارتدادًا بدل الصمت.
receiving.lastCheckedAtstring | null- متى سُئل DNS آخر مرة عن هذا النطاق. وnull تعني أنه لم يُسأل قط، وهو ما يُقرأ بشكل مختلف تمامًا عن فشل الفحص بالنسبة لمن أضاف نطاقًا قبل دقيقة. وهذه النقطة تبلّغ عن النتيجة المخزَّنة ولا تجري فحصًا خاصًا بها أبدًا.
receiving.errorstring | null- لماذا لم ينجح الفحص الأخير، بكلمات يستطيع المالك التصرف بناءً عليها: ومن أمثلتها المعتادة `No MX records yet. DNS changes can take a few minutes to spread.` ويكون null بمجرد النجاح، وهو مخزَّن لا مشتق، فتقول إعادة التحميل وإعادة الفحص المجدولة الشيء نفسه.
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown'- حالة التوقيع الصادر كما رآها الفحص الأخير. تُقرأ من الفحص المخزَّن ولا تُستقصى مع هذا الطلب، لذا تخبرك `sending.checkedAt` كم عمرها.
sending.canSendboolean- ما إذا كان إرسال من هذا النطاق سيُقبل الآن. والحكم السلبي الأقدم من يوم يُعامل كمجهول لا كرفض، فقد تكون هذه القيمة صحيحة بينما `status` بالقيمة `pending`. فرّع عليها قبل الإرسال: فالقيمة الخاطئة تعني أن `emails.send` من هذا النطاق يُرفض بـ 409 مع `domain_not_sendable`.
sending.checkedAtstring | null- متى فُحصت حالة التوقيع آخر مرة، بصيغة ISO-8601. وnull تعني أنها لم تُفحص قط، وهو ما يُقرأ بشكل مختلف تمامًا عن الفشل.
sending.errorstring | null- آخر فشل في التوقيع موصوفًا بالكلمات، أو null بمجرد نجاحه.
sending.notestring- واحدة من خمس جمل، تُختار بحسب `sending.status`، تشرح معنى تلك الحالة بكلمات يستطيع مالك النطاق التصرف بناءً عليها. نص للقراءة البشرية. فرّع على `sending.canSend` لا على هذا الحقل.
trackingDomainTracking- نطاق التتبع المخصص للنطاق، في سجلات `list` وفي هذا السجل على حد سواء، وهو ما يغيّره `update`.
tracking.hoststring | null- نطاق التتبع، مثل `links.acme.com`، أو null عندما لا يكون مضبوطًا.
tracking.status'none' | 'pending' | 'active' | 'failed'- تعني `none` أنه لا يوجد نطاق تتبع مضبوط، وتعني `pending` أنه لم ينجح في أي فحص قط، وتعني `active` أن البريد الجديد يستخدمه، وتعني `failed` أنه نجح من قبل ثم خرج من الاستخدام. والمضيف النشط يخرج من الاستخدام بعد ثلاثة فحوص فاشلة متتالية، أو حين يتجاوز عمر آخر فحص ناجح ساعتين.
tracking.activeboolean- صحيحة تمامًا عندما تكون `status` بالقيمة `active`، وهي الحالة التي تستخدم فيها الروابط المتتبَّعة وبكسل الفتح في البريد الجديد الصادر من النطاق هذا المضيف.
tracking.targetstring- العنوان الذي يشير إليه سجل CNAME، مُعدّ لنطاق التتبع هذا وحده. ويكون سلسلة فارغة ما دام `host` بالقيمة null، وكذلك ما دام عنوان مضيف جديد قيد الإعداد.
tracking.record{ type: 'CNAME'; name: string; value: string } | null- السجل الواجب نشره، باسم `host` وقيمته `target`. ويكون null عندما لا يوجد نطاق تتبع، وكذلك ما دام عنوان مضيف جديد قيد الإعداد.
tracking.checkedAtstring | null- متى فُحص المضيف آخر مرة، بصيغة ISO-8601. ويكون null حتى أول فحص.
tracking.verifiedAtstring | null- متى نجح فحص آخر مرة، بصيغة ISO-8601. ويكون null لمضيف لم ينجح في أي فحص قط.
tracking.errorstring | null- ما وجده الفحص الأخير، بكلمات يستطيع مالك النطاق التصرف بناءً عليها. ويكون null عندما ينجح الفحص الأخير أو عندما لا يكون أي فحص قد جرى. والمضيف الذي فشل في فحص أو فحصين يظل `active` ويحمل السبب هنا.
addressesArray<{ address: string; enabled: boolean }>- كل سجلات العناوين على النطاق، وهو ما يضيفه `get` على سجل `list`. ويشمل ذلك السجلات التي كتبها التسليم نفسه في ظل catch-all، وهذه تتوقف عن القبول فور إيقاف catch-all، فالمصفوفة ليست قائمة بما سيستقبل.
addresses[].addressstring- العنوان الكامل، يُعاد بناؤه من الجزء المحلي المخزَّن واسم المضيف ويُحوَّل إلى أحرف صغيرة، فيطابق دائمًا `domain` أعلاه بدلًا من أن ينحرف عنه.
addresses[].enabledboolean- القيمة false تعطّل العنوان، والعنوان المعطّل يُرفض حتى مع تفعيل catch-all. وكل سجل يُدرج في الحالتين، لذا رشّح على هذا الحقل بدلًا من قراءة المصفوفة على أنها مجموعة العناوين العاملة.
createdAtstring- متى أُضيف سجل النطاق، بصيغة ISO-8601. وليس وقت التحقق منه: فذاك هو `receiving.verifiedAt`، الذي قد يكون null بينما هذا مضبوط.