إعداد عميل البريد عبر API وMCP

يتيح TrekMail عبر REST وMCP بيانات الاتصال نفسها المستخدمة في التطبيقات والأجهزة داخل لوحة المعلومات. كلتا الواجهتين للقراءة فقط وتتطلبان صلاحية قراءة صندوق البريد.

لا تعيدان مطلقا كلمة مرور الصندوق أو بيانات اعتماد مزود SMTP مخصص. يدخل المستخدم كلمة المرور مباشرة في تطبيق البريد. وحتى عندما يوجّه النطاق الرسائل الصادرة عبر مزود مخصص، ترسل التطبيقات الخارجية إلى endpoint SMTP العام في TrekMail؛ ثم يطبق TrekMail مسار النطاق الخاص داخليا.

الحصول على إعدادات الاتصال

GET /api/v1/mailboxes/{mailbox_id}/client-setup?lang=en
Authorization: Bearer tm_live_...

النطاق الداخلي المطلوب: mailboxes:read. تُطبق قيود الرمز الاختيارية domain_ids وmailbox_ids.

تتضمن الاستجابة:

• مضيف IMAP الوارد ومنفذ SSL واسم المستخدم والجاهزية؛
• مضيف SMTP الصادر ومنفذ SSL واسم المستخدم والجاهزية؛
• عنوان URL لخادم DAV للتقويمات وجهات الاتصال وجاهزية الاتصال وما إذا كان العنوان يحمل العلامة؛
• الأدلة المحلية نفسها من ثلاث خطوات لإعداد Gmail وOutlook وApple Mail وThunderbird وIMAP العام المعروضة في التطبيقات والأجهزة؛
• sending.mode: ‏platform أو profile أو not_configured؛
• sending.reason: سبب ثابت قابل للقراءة آليا عندما لا يكون الإرسال جاهزا؛
• apple_mail_profile.available، وتكون true فقط عند جاهزية الاستقبال والإرسال؛
• shared_mailboxes.native_access_enabled ومساحة الأسماء المضبوطة وإدخال items[] لكل صندوق مشترك مفوض إلى هذا الصندوق العادي؛
• password_included: false كضمان أمان صريح.

يحتوي كل عنصر مفوض على native_access_status/native_access_ready دائمين، والمسارات القياسية الدقيقة ضمن folders، وoperations التي يفرضها الخادم، والقيم الفعلية send_as_ready/send_as_reason. يظل can_send إذن يمكنه الرد الذي عيّنه المسؤول؛ وقد يكون true بينما SMTP غير متاح، لذلك يجب فحص حقلي الجاهزية. يظل الصندوق المشترك ظاهرا إذا كان صندوق العضو غير نشط أو تسجيل دخوله معلقا أو الدخول المباشر معطلا، لكنه يعيد mailbox_unavailable أو mailbox_login_suspended أو direct_login_unavailable كسبب للإرسال باسم. يحتفظ الحقل القديم folder بمسار البريد الوارد الدقيق. انتظر native_access_ready=true قبل إرشاد المستخدم.

ينقل SMTP الرد أو إعادة التوجيه لكنه لا يحفظ نسخة المرسل. لذلك تكون sent_copy.smtp_saves_copy بالقيمة false؛ اضبط العميل لإضافة النسخة إلى sent_copy.folder (القيمة نفسها في folders.sent) ليراها الفريق. تمثل folders.archive وfolders.junk أهداف النقل الدقيقة عندما لا يعيّن العميل الأرشيف أو البريد المزعج تلقائيا. النقل إلى المزعج وحده لا يضمن تدريب مصنف الخادم.

اطلب هذا endpoint دائما باستخدام معرّف صندوق العضو العادي وصادق العميل بعنوان العضو وكلمة مروره. لا تنشئ حسابا ثانيا ولا تحاول المصادقة المباشرة بالعنوان المشترك.

عند تعطيل الوصول الأصلي تكون shared_mailboxes.native_access_enabled بالقيمة false وitems فارغة. وعند تمكينه مع بقاء items فارغة، لا يملك الصندوق العادي حاليا عضوية نشطة في صندوق مشترك. لا تُضمن أي كلمة مرور في الحالتين.

يقبل المعامل الاختياري lang اللغات الـ13 نفسها في endpoint ملف Apple. إذا حُذف، يستخدم TrekMail Accept-Language ثم اللغة الافتراضية. لكل دليل id ثابت وثلاث steps محلية وaction: ‏use_server_settings أو download_apple_profile.

لا تعني connection_status=receiving_only اكتمال الإعداد بنجاح. اضبط مسار النطاق الصادر أو استعده قبل إرشاد المستخدم إلى عميل يتحقق من كلا الخادمين.

تعني connection_status=unavailable أن دورة حياة الصندوق تغيرت ولم يعد يستطيع المصادقة مباشرة. لا تستخدم بيانات الخادم المعادة ولا تعرض ملف Apple Mail؛ حدّث حالة الصندوق بدلا من ذلك.

تنزيل ملف Apple Mail

GET /api/v1/mailboxes/{mailbox_id}/apple-mail-profile?lang=en
Authorization: Bearer tm_live_...
Accept: application/x-apple-aspen-config

الاستجابة مرفق .mobileconfig. قيم lang المدعومة هي en وes وfr وde وpt وit وnl وru وzh وja وko وar وhe. إذا حُذف lang، يستخدم TrekMail Accept-Language ثم اللغة الافتراضية.

يحتوي الملف على إعدادات IMAP وSMTP بلا حقول كلمة مرور. تطلب Apple كلمة مرور الصندوق أثناء التثبيت. يعيد TrekMail 409 mail_client_setup_not_ready بدلا من إنشاء ملف مضلل عندما لا يتوفر الإرسال.

أدوات MCP

تستخدم الأدوات endpoints REST وقواعد التفويض نفسها:

تعيد عمليات نقل MCP محتوى أداة منظما بدلا من تنزيل متصفح. فك ترميز content_base64 إلى وحدات بايت واحفظه باسم file_name؛ لا تفسره كـJSON أو UTF-8 قبل فك الترميز.

تتطلب الأداتان نطاق OAuth المستضاف mail:read الذي يتوسع إلى النطاق الداخلي mailboxes:read. وهما للقراءة فقط ولا تعتمدان على أي علامة بيئية للعمليات التدميرية في خادم stdio المستضاف ذاتيا.

الأخطاء

قد يعيد endpoint الإعداد قيم sending.reason التالية: mailbox_unavailable وdirect_login_unavailable وdomain_unavailable وdomain_deprovisioning وaccount_suspended وemail_verification_required وmailbox_sending_disabled وsmtp_not_configured وmanaged_smtp_not_in_plan وmanaged_smtp_entitlement_inactive وsmtp_profile_unavailable أو smtp_route_invalid.