كلمات مرور تطبيقات البريد عبر API وMCP

يمكن لـREST API وMCP عرض كلمات مرور التطبيقات للصندوق العادي وإنشاؤها واستبدالها وإلغاؤها، وتغيير وضع تسجيل دخول تطبيقات البريد، وضبط إعداد الحساب الافتراضي للصناديق المستقبلية. هذه الصفحة مرجع للتكاملات. لتعليمات لوحة التحكم وبريد الويب، راجع كلمات مرور تطبيقات البريد لأجهزتك.

تتيح كلمة مرور التطبيق الوصول عبر IMAP وSMTP على المنفذين 465 و587 وManageSieve وCalDAV/CardDAV. لا تفتح بريد الويب الجديد أو لوحة التحكم مطلقًا. يسجّل بريد الويب الكلاسيكي الدخول عبر IMAP ويقبل كلمات مرور التطبيقات. تحمي 2FA للصندوق الدخول إلى بريد الويب الجديد فقط؛ ولا تطلب تطبيقات البريد وبريد الويب الكلاسيكي رمزها مطلقًا.

لا تخضع الميزة لقيد مستقل حسب خطة الصندوق. تظل صلاحيات API وMCP الحالية بحسب الخطة سارية؛ راجع نطاقات API والصلاحيات.

المصادقة والنطاقات وصلاحيات الأعضاء

استخدم رمز Bearer مع طلبات REST ضمن /api/v1. تستخدم عمليات كتابة JSON ترويسة Content-Type: application/json وترويسة Idempotency-Key.

تُفحص صلاحية تعيين كلمة المرور في دور العضو، إضافة إلى نطاق API للرمز. ينطبق هذا على رموز الأعضاء والموصلات التي فوّضها أعضاء. لا يحتاج رمز صاحب الحساب إلى نطاق إضافي لتعيين كلمة المرور. عند غياب صلاحية العضو، تُعاد 403 scope_blocked_by_membership.

يمكن لموصلات OAuth المستضافة استخدام نطاقات إمكانات REST المقابلة. في الحزم القديمة، يوفر mail:read نطاقي mailboxes:read وaccount:read؛ ويوفر mail:write نطاق mailboxes:write أيضًا. لا تتجاوز توسعة النطاقات قواعد صلاحيات الأعضاء أو القواعد المقصورة على صاحب الحساب مطلقًا.

تنطبق قيود الرمز domain_ids وmailbox_ids، بما فيها الاختيارات الجماعية. تعيد نقاط كلمات مرور التطبيقات ونقطتا تغيير الوضع 404 not_found عندما تكون الميزة معطلة، بعد فحوص المصادقة والبرمجيات الوسيطة. يعيد الصندوق غير المتاح أو غير الموجود 404 أيضًا، لذا لا تعتبر كل 404 إشارة إلى حالة الميزة.

نظرة سريعة على نقاط النهاية

تتضمن المسارات أدناه البادئة /api/v1. يمثل {mailbox} معرّف الصندوق العادي؛ ويمثل {id} معرّف إدخال كلمة مرور تطبيق تابع له.

تتطلب جميع عمليات الكتابة في هذا الجدول Idempotency-Key. نقطة كلمة المرور عملية إعادة تعيين إدارية موجودة، وهي منفصلة عن استبدال كلمة مرور تطبيق.

عرض كلمات مرور التطبيقات وفهم حقول الإدخالات

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

تتضمن الاستجابة الحقول العليا mailbox_id وclient_auth_mode وlimit وactive_count وdata، وهو مصفوفة الإدخالات. يبلغ limit عدد 25 كلمة نشطة لكل صندوق. تظهر الإدخالات النشطة أولًا، بدءًا من الأحدث؛ وتظل الملغاة ظاهرة 90 يومًا. لا تحتوي أي استجابة قائمة على سر.

يحتوي كل إدخال على:

أسباب الإلغاء العامة هي revoked وrotated وmailbox_password_reset وmailbox_password_changed وlogin_suspended وconverted_to_shared وmailbox_trashed. تستبعد القائمة بيانات الاعتماد التي تنشئها المنصة داخليًا.

إنشاء كلمة مرور تطبيق

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

الحقل name مطلوب: من 1 إلى 64 حرفًا قابلًا للطباعة. تُختصر المسافات المتتالية إلى مسافة واحدة. يجب أن يكون الصندوق عاديًا ونشطًا وغير معلّق تسجيل الدخول، ولديه أقل من 25 كلمة مرور تطبيق نشطة.

تحتوي استجابة 201 على الإدخال الكامل ضمن data، وتضيف data.password وتتضمن message. مثلًا، هذه حقول بيانات الاعتماد داخل تلك الاستجابة:

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

يحذف هذا المثال حقول السجل الأخرى الموضحة أعلاه. السر في المثال للتوضيح فقط. يتكون السر الفعلي من 16 حرفًا لاتينيًا صغيرًا مولّدًا، ويُعاد من دون مسافات. تقبل التطبيقات المسافات والأحرف الكبيرة أيضًا؛ اعرضه في أربع مجموعات من أربعة أحرف عند تقديمه للمستخدم.

تُعاد كلمة المرور مرة واحدة فقط. لا تُدرجها في سجلات التطبيق. يُدخلها المستخدم مباشرة في تطبيق البريد مع عنوان الصندوق الكامل اسمًا للمستخدم. يرسل الإنشاء والاستبدال إشعارًا يذكر اسم كلمة مرور التطبيق إلى الصندوق وعنوان الاسترداد، إن كان محددًا، من دون السر. ويُستثنى من ذلك أول كلمة مرور تطبيق تُصدر مع صندوق جديد (انظر أدناه).

استخدم API لإعداد تطبيق البريد للحصول على إعدادات الاتصال. لا يحتوي ملف Apple المنزل على كلمة مرور؛ ويُدخل المستخدم كلمة مرور التطبيق عندما يطلبها macOS أو iOS أثناء التثبيت.

الحصول على أول كلمة مرور تطبيق مع صندوق جديد

يقبل POST /api/v1/mailboxes وPOST /api/v1/mailboxes:bulk قيمة منطقية اختيارية هي create_app_password. عند تعيينها إلى true، يحصل كل صندوق منشأ أيضًا على أول كلمة مرور تطبيق له، وتُعاد مرة واحدة باسم app_password: حقول السجل الموضحة أعلاه مع password. تحمل الاسم Created with the mailbox، ولا يُرسل إشعار بالبريد الإلكتروني بشأنها، لأن الصندوق جديد وقد تلقى المستدعي كلمة مروره للتو. من دون هذا الحقل (القيمة الافتراضية false) لا تتغير الاستجابة. ويُتجاهل الحقل ما دامت كلمات مرور التطبيقات غير مفعّلة.

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

تحمل استجابة 201 عندئذ one_time_password، وهي كلمة مرور الصندوق لبريد الويب، وapp_password.password لتطبيقات البريد. في الاستجابة الجماعية، يكون لكل صف منشأ app_password خاص به. إذا تعذر إصدارها، تكون قيمة app_password هي null (ويضيف الإنشاء الفردي أيضًا _app_password_warning)؛ ومع ذلك يُنشأ الصندوق، ويمكنك إنشاء واحدة عبر نقطة النهاية الموضحة أعلاه. تُعيد إعادة المحاولة المطابقة لإنشاء فردي بالمفتاح Idempotency-Key نفسه الاستجابة نفسها، بما فيها السرّان، من دون إصدار كلمة مرور تطبيق ثانية. أما إعادة تشغيل الطلب الجماعي فتحذف الأسرار، كما تفعل مع one_time_password.

استبدال كلمة مرور أو إلغاؤها

لا يتطلب الاستبدال جسم طلب JSON:

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

تحتوي استجابة 200 على الإدخال الجديد الكامل ضمن data، وعلى data.password الذي يُعرض مرة واحدة، والحقل العلوي replaced_id الذي يشير إلى الإدخال القديم، وmessage. للبديلة data.id جديد والاسم نفسه. يُلغى الإدخال القديم بالقيمة revoked_reason: "rotated"، ويتوقف سره فورًا، وتُسجّل التطبيقات المستخدمة له خروجها. حدّث الجهاز بالكلمة البديلة.

للإلغاء من دون إصدار بديلة:

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

لا يُطلب جسم للطلب. تتضمن استجابة 200 القيمة status: "revoked" والإدخال الملغى الكامل ضمن data. يفقد التطبيق الوصول؛ وتعاد اتصالات الأجهزة الأخرى ذات كلمات مرور التطبيقات الصالحة تلقائيًا. لا يمكن التراجع عن الإلغاء. تعيد محاولة استبدال إدخال ملغى أو إلغائه مجددًا بطلب جديد 409 conflict.

تغيير وضع تسجيل دخول تطبيقات البريد لصندوق واحد

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

الحقل mode مطلوب ويقبل:

• app_password_only: تتطلب تطبيقات البريد كلمة مرور تطبيق. تُسجّل الاتصالات التي تستخدم كلمة مرور الصندوق خروجها؛ وتعاد اتصالات التطبيقات ذات كلمات مرور التطبيقات الصالحة تلقائيًا.
• password_or_app_password: تقبل تطبيقات البريد كلمة مرور الصندوق أو كلمة مرور تطبيق.

تتضمن استجابة 200 الحقول mailbox_id وclient_auth_mode وmessage. يعيد تعيين الوضع الحالي مجددًا 200 من دون تغيير. لا يؤدي تغيير الوضع إلى إلغاء كلمات مرور التطبيقات الموجودة.

أنشئ كلمات مرور للأجهزة قبل اشتراطها. قد يعرض تسجيل الدخول المرفوض بكلمة مرور الصندوق: "Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords." (فشل تسجيل الدخول. يقبل هذا الصندوق كلمات مرور التطبيقات فقط: أنشئ واحدة في البريد على الويب من الإعدادات > كلمات مرور التطبيقات). تعرض بعض التطبيقات خطأ عامًا في كلمة المرور فقط.

لا تملك الصناديق المشتركة تسجيل دخول مباشرًا، وتعيد 422 mailbox_not_eligible على هذه النقطة. لا يمكن تحويل صناديق النظام التابعة للمنصة إلى app_password_only؛ فهذا يعيد 422 system_mailbox_protected.

لا يغيّر أي وضع الدخول إلى بريد الويب الجديد أو جميع علب البريد أو رموز Message API أو الاستيراد إلى الصندوق أو قواعد البريد أو التحويل. يستخدم أعضاء الصندوق المشترك بيانات اعتماد صندوقهم العادي ووضعه.

تغيير الأوضاع جماعيًا

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

أرسل mode ومعيار اختيار واحدًا فقط:

تضيّق قيود الحساب والرمز كل اختيار. يعيد معرّف صريح خارج نطاق الوصول أو معرّف غير معروف 404 بدلًا من تطبيق اختيار جزئي. يعيد النطاق غير المعروف أو التابع لحساب آخر 422 validation_error. يعيد غياب معيار الاختيار أو تعدده 422 invalid_selection.

يمكن أن يطابق الاختيار 1000 صندوق كحد أقصى. يعيد الاختيار الأكبر 422 selection_too_large قبل أي تغيير. ضيّق اختيار النطاق أو أرسل دفعات صريحة.

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

يحسب matched الصناديق المختارة؛ ويحسب updated تغييرات الوضع الفعلية؛ ويحسب skipped الصناديق المشتركة أو المنقولة إلى المحذوفة أو الجاري حذفها، إضافة إلى صناديق النظام عند اشتراط كلمات مرور التطبيقات. يمكن تحديث وضع الصناديق الموقوفة مؤقتًا أو المعلّق دخولها استعدادًا لعودة الوصول. تُحسب الصناديق المطابقة أصلًا ضمن matched، لا ضمن updated أو skipped، لذا يمكن تكرار العملية بأمان. تُرفض الحسابات المعلّقة بالرمز 403.

قراءة حالة الصندوق وضبط إعداد الحساب الافتراضي

عندما تكون كلمات مرور التطبيقات مفعّلة، يتضمن GET /api/v1/mailboxes وGET /api/v1/mailboxes/{mailbox} الحقول التالية في موارد الصناديق:

• client_auth_mode: القيمة app_password_only أو password_or_app_password.
• app_passwords_count: عدد صحيح لكلمات مرور التطبيقات النشطة الظاهرة، باستثناء بيانات اعتماد المنصة الداخلية.

يُحذف الحقلان عندما تكون الميزة معطلة. لا تملك الصناديق المشتركة وضع دخول مباشرًا قابلًا للاستخدام أو كلمات مرور تطبيقات؛ اطلب بيانات اعتماد الصندوق العادي للعضو بدلًا من ذلك.

يتطلب GET /api/v1/account النطاق account:read. تظل حقوله العليا المعتادة متاحة: id وname وemail وplan وeffective_plan_slug وsubscription_status وlimits وfeatures وusage وsafety_limits وcreated_at. يضيف new_mailbox_client_auth_mode فقط عندما تكون كلمات مرور التطبيقات مفعّلة وتطبّق المنصة إعداد الحساب الافتراضي على الصناديق الجديدة. خلاف ذلك، يظل GET متاحًا ويحذف ذلك الحقل.

يستطيع صاحب الحساب فقط تغيير الإعداد الافتراضي:

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

يقبل الحقل المطلوب الوضعين نفسيهما. هذا هو حقل الحساب الوحيد القابل للكتابة هنا. تتضمن الاستجابة الحقول العليا id وnew_mailbox_client_auth_mode وmessage. يعيد PATCH الرمز 404 ما لم يتحقق شرطان إظهار الحقل، ويعيد 403 scope_blocked_by_membership لأي رمز عضو أو موصل فوّضه عضو.

يعيد رمز صاحب الحساب المقيّد بواسطة domain_ids أو mailbox_ids الخطأ 403 token_resource_constrained. استخدم رمز صاحب الحساب دون قيود على الموارد، أو غيّر الإعداد الافتراضي في إعدادات الحساب.

يؤثر الإعداد الافتراضي في الصناديق المستقبلية المنشأة من لوحة التحكم أو جماعيًا أو بالدعوات أو API أو الوكلاء. ولا يغيّر الموجودة مطلقًا. يستطيع إنشاء صندوق واحد عبر API تحديد client_auth_mode صراحة في POST /api/v1/mailboxes؛ ويتبع إغفاله إعداد الحساب. تحتفظ الصناديق الموجودة بالقيمة password_or_app_password عند طرح الميزة. الإعداد الافتراضي للصناديق الجديدة هو app_password_only ما لم يغيّره صاحب الحساب.

إعادة تعيين كلمة مرور الصندوق تلغي كلمات مرور التطبيقات تلقائيًا

يتطلب POST /api/v1/mailboxes/{mailbox}/password النطاق mailboxes:write وصلاحية تعيين كلمة المرور نفسها للعضو وIdempotency-Key. يتطلب جسم الطلب password، أي كلمة مرور الصندوق الجديدة وفق سياسة كلمات مرور الصناديق. ليست هذه نقطة إنشاء كلمة مرور تطبيق.

تلغي كل إعادة تعيين إدارية ناجحة عبر هذه النقطة، بما فيها تغيير كلمة المرور بواسطة وكيل MCP، جميع كلمات مرور التطبيقات بالسبب mailbox_password_reset. لا يمكن تعطيل الإلغاء. عندما تكون الميزة مفعّلة، تتضمن الاستجابة app_passwords_revoked، وهو عدد صحيح، إلى جانب status وsync_pending وmessage:

• 200 وstatus: "updated" وsync_pending: false عندما يكتمل التزامن مع خادم البريد.
• 202 وstatus: "update_pending" وsync_pending: true عندما تُحفظ كلمة المرور ويظل التزامن معلقًا. تكون كلمات مرور التطبيقات قد أُلغيت بالفعل في هذه المرحلة.

تلغي إعادة التعيين أيضًا رموز الرسائل الحالية للصندوق. هذه نتيجة إعادة تعيين كلمة مرور الصندوق، وليست نتيجة استبدال كلمة مرور تطبيق واحدة أو تغيير وضع تطبيقات البريد.

لا تلغي تغييرات كلمة المرور الذاتية في بريد الويب كلمات مرور التطبيقات إلا عندما يحدد المستخدم ألغِ أيضًا جميع كلمات مرور التطبيقات. يلغي استرداد كلمة المرور وتعليق تسجيل الدخول والتحويل إلى صندوق مشترك والنقل إلى المحذوفة مؤخرًا جميعها. لا تعيد استعادة الوصول أو الصندوق الأسرار الملغاة. راجع تعليق تسجيل دخول الصندوق عبر API.

منع تكرار العمليات والأسرار التي تُعرض مرة واحدة

استخدم Idempotency-Key جديدًا لكل عملية كتابة مقصودة، ولا تُعد استخدامه إلا لإعادة محاولة النقل بالطريقة والمسار والجسم أنفسها. المفاتيح مطلوبة، وطولها الأقصى 255 حرفًا. تُخزن الاستجابات الناجحة مؤقتًا لمدة 24 ساعة افتراضيًا؛ وتعيد إعادة استخدام مفتاح لطلب مختلف 409 idempotency_mismatch.

تعيد استجابة إعادة التشغيل لطلب إنشاء أو استبدال كلمة مرور تطبيق المعرّفات الآمنة نفسها لكنها تحذف data.password. تتضمن _idempotency_replay_warning وترويسة الاستجابة X-Idempotency-Replayed: true. لا تستطيع إعادة التشغيل استرداد سر مفقود. استخدم data.id المعاد لاستبدال الإدخال النشط بمفتاح جديد والحصول على بديلة صالحة. تتبّع المعرّف الجديد بعد الاستبدال.

تعيد إعادة تشغيل إلغاء ناجح بالمفتاح نفسه النتيجة المحفوظة. يعيد طلب إلغاء جديد لذلك الإدخال الملغى 409 conflict. يمكن تكرار تغييرات الوضع بطبيعتها، لكن امنح كل تغيير مقصود مفتاحًا جديدًا: قد تعيد إعادة استخدام مفتاح سابق بعد تبديل الأوضاع استجابة قديمة بدلًا من تطبيق التغيير الجديد الذي تقصده.

حدود المعدل والأخطاء

يقتصر الإنشاء على 60 في الساعة لكل حساب، والاستبدال على 30 في الساعة لكل حساب. يتشارك مستخدمو API وMCP هذه الحصص على مستوى الحساب، وليست حصصًا مستقلة لكل رمز. تخضع تغييرات الوضع الجماعية لحد إضافي قدره 10 طلبات في الدقيقة. ينطبق محدد API المعتاد على هذه المسارات أيضًا؛ وحده الافتراضي 60 طلبًا في الدقيقة لكل بيانات اعتماد. يعيد الطلب المحدود 429 rate_limited؛ التزم بترويسة Retry-After قبل إعادة المحاولة.

تستخدم الأخطاء كائن error المعتاد بالحقول code وmessage وhint وrequest_id وretryable. تعامل مع الرمز الذي تقرؤه الآلة بدلًا من مطابقة النص.

أدوات MCP والقيود على العمليات التي تغيّر الوصول

يستخدم MCP صلاحيات REST وحقول الاستجابة نفسها. الأدوات المباشرة هي:

تقبل أداتا إنشاء الصناديق create_mailbox_generated_password وbulk_create_mailboxes المدخل الاختياري نفسه create_app_password كما في REST.

تقبل أدوات الكتابة أيضًا idempotency_key اختياريًا. يستخدم REST حقل الجسم mode لتغيير وضع الصندوق؛ وتسمي أداة MCP هذا المدخل client_auth_mode. تخضع معاييرها الجماعية لقواعد الوصول نفسها وحد 1000 صندوق كما في REST.

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

في الخادم المستضاف ذاتيًا، تتطلب كل عملية كتابة أعلاه TREKMAIL_ALLOW_DESTRUCTIVE=true. يخضع إنشاء بيانات اعتماد لهذا القيد أيضًا، لأنه يمنح وصولًا إلى الصندوق. لا تتطلب القائمة وقراءة الحساب هذه العلامة. اطلب موافقة المستخدم على تغيير بيانات الاعتماد أو الوصول المقصود قبل استدعاء عملية كتابة. تُوجّه الأدوات المباشرة التي تعيد الأسرار الوكيل لعرض كلمة المرور مرة واحدة، وطلب لصقها في التطبيق، وعدم حفظها مطلقًا في ملفات أو ذاكرة أو تكرارها في رسائل أو استدعاءات أدوات لاحقة.

ملفات الاتصال عبر دليل ChatGPT/OpenAI وClaude

توفر هذه الملفات رابط إعداد آمنًا إلى لوحة التحكم للإنشاء والاستبدال بدلًا من إصدار سر في المحادثة. ويتم إنشاء الصندوق هناك أيضًا عبر رابط إلى لوحة التحكم، لذا تأتي أول كلمة مرور تطبيق من بطاقة تم إنشاء صندوق البريد في لوحة التحكم، لا من create_app_password. الوجهة هي /app/mailboxes/{mailbox_id}/security#app-passwords؛ ويسجّل المستخدم الدخول ويكمل الإجراء هناك.

يعرض ملف OpenAI الأداتين get_mailbox_app_password_setup_link و**get_mailbox_app_password_replacement_setup_link. يحتفظ ملف Claude بالاسمين create_mailbox_app_password وrotate_mailbox_app_password**، لكنه يعيد رابط الإعداد الآمن بدلًا من data.password. لا تعد بسر من أدوات الدليل هذه ولا تطلب من المستخدم لصق واحد في المحادثة.

لبيانات الاتصال، استخدم get_mail_client_setup. للإعداد العام للموصلات، راجع ربط وكلاء الذكاء الاصطناعي. تستخدم صناديق White Label ميزة API نفسها ومضيفي بريد ويب وبريد مخصصين للعلامة؛ سمِّ بيانات الاعتماد كلمة مرور تطبيق في التعليمات الظاهرة للمستخدم.