إعداد تطبيق البريد باستخدام API وMCP

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

لا تعيد هذه الواجهات كلمة مرور الصندوق أو كلمة مرور تطبيق أو بيانات اعتماد مزود SMTP مخصص. يُدخل المستخدم كلمة مرور تطبيق مباشرة في تطبيق البريد، أو كلمة مرور الصندوق إذا كان لا يزال يقبلها. حتى عندما يوجّه النطاق الرسائل الصادرة عبر مزود مخصص، ترسل تطبيقات البريد الخارجية إلى نقطة 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, namespace, items[];
• authentication.client_auth_mode: القيمة app_password_only أو password_or_app_password؛
• authentication.accepted_passwords: القيمة ["app_password"] أو ["mailbox_password", "app_password"] على الترتيب؛
• authentication.app_passwords_endpoint: نقطة نهاية إدارة كلمات مرور التطبيقات للصندوق؛
• password_included: false كضمان أمان صريح.

تشمل shared_mailboxes.items[] العضويات التي لديها صلاحية قراءة عند تفعيل الوصول الأصلي للمجلدات فقط. delegated_send_addresses قائمة منفصلة بعناوين المرسل المتاحة للفريق في حقل من، ولكل منها id وemail وdisplay_name؛ قد تكون فارغة. لا تمنح وصولا للمجلدات ولا تؤكد جاهزية الإرسال. هذه العناوين ليست هويات Message API. استخدم الخوادم المعادة، بما في ذلك White Label، بدلا من نسخ اسم خادم المنصة.

يحتوي كل عنصر مفوض على 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 أهداف النقل الدقيقة عندما لا يعيّن العميل الأرشيف أو البريد المزعج تلقائيا. النقل إلى المزعج وحده لا يضمن تدريب مصنف الخادم.

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

تصف قائمة مجلدات shared_mailboxes الوصول الأصلي لمن يمكنهم قراءة الوارد المشترك. إذا كانت 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 كلمة مرور أثناء التثبيت: استخدم كلمة مرور تطبيق مع app_password_only، أو أيًا من كلمتي المرور المقبولتين مع password_or_app_password. تعيد TrekMail الخطأ 409 mail_client_setup_not_ready بدلًا من إنشاء ملف مضلل عندما لا يكون البريد الصادر متاحًا.

أنشئ كلمة مرور تطبيق في البريد على الويب من الإعدادات، كلمات مرور التطبيقات، أو في لوحة التحكم من صناديق البريد، (صندوق البريد)، الأمان، كلمات مرور التطبيقات. لا تنشئها نقطة نهاية الإعداد المخصصة للقراءة فقط. لنقاط REST وأدوات MCP التي تدير هذه الكلمات ووضع تسجيل الدخول، راجع كلمات مرور تطبيقات البريد عبر API وMCP.

أدوات 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.