إدارة فرق White Label عبر API وMCP في TrekMail

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

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

الميزات المتاحة

يتضمن كتالوج MCP الكامل الآن 284 أداة عبر stdio وما يصل إلى 283 أداة عبر HTTP المستضاف. تساهم White Label بعدد 23 أداة: سبع للعلامة التجارية و13 لإدارة الحساب والأعضاء والنشاط وثلاث لحدود تخزين العملاء.

لا تُحمّل هذه الأدوات للجميع. يقيّم TrekMail استحقاق White Label الحالي للحساب، وعضوية الشخص الحالية، والرمز أو تفويض OAuth، وأي قيد على النطاق، ومجموعات الأدوات المحددة، وإعدادات الأمان المحلية قبل إنشاء tools/list. لا يتلقى الاتصال الذي لا يملك وصول White Label المخططات مطلقا.

حالات الاستحقاق

عند توفر وصول قراءة White Label، استدع GET /api/v1/white-label أو أداة get_white_label للتمييز بين active وgrace المخصص للقراءة فقط، ولرؤية تقدم الإعداد وموعد انتهاء المهلة. لا يستطيع الحساب غير المتاح استدعاء نقطة النهاية هذه. عندما تظل بيانات اعتماد محفوظة تشير إلى نطاق White Label لم يعد الحساب قادرا على استخدامه، تعيد API الرمز scope_blocked_by_entitlement وتوضح مكان إعادة التفعيل.

النطاقات

تحتاج نقطة نهاية نشاط العضو إلى activity:read وmembers:read معا، لأن استجابتها تحتوي على سجل عضو بالإضافة إلى النشاط. يستخدم اتصال OAuth المستضاف محدد tools:white_label لطلب مجموعة الأدوات هذه؛ وتظل نطاقات REST الفعلية مقيدة بالحساب والعضوية.

بالنسبة إلى خادم MCP مستضاف ذاتيا، أضف white_label إلى TREKMAIL_TOOLSETS عند استخدام قائمة سماح لمجموعات الأدوات. تحترم أدوات الكتابة أيضا بوابات الأمان المحلية الموضحة أدناه.

نقاط نهاية REST

تقع جميع المسارات تحت https://trekmail.net/api/v1.

تتطلب كل عملية كتابة في هذا الجدول ترويسة Idempotency-Key. يؤدي تكرار الطلب نفسه بالمفتاح نفسه إلى إعادة النتيجة الآمنة الأصلية؛ وتُحجب الأسرار المستخدمة مرة واحدة في إعادة التشغيل، مثل رمز الدعوة. تؤدي إعادة استخدام مفتاح مع نص طلب مختلف إلى idempotency_mismatch.

اقرأ كتالوج الوصول أولا

لا تضع صلاحيات الأدوار كثوابت في عملية التكامل. استدع كتالوج الوصول قبل دعوة أو تغيير في الوصول. تعكس علامات grantable عضوية المستدعي الحالية، ويمكن أن تتغير عندما يعدّل المالك تلك العضوية.

الأدوار المتاحة حاليا للدعوات الجديدة هي:

• client - يدير النطاقات وصناديق البريد المخصصة دون رؤية علاقة الموزع الخاصة مع TrekMail.
• webmail_only - يظهر في قائمة الفريق لكنه لا يتلقى صلاحيات لوحة التحكم.
• domain_admin - يدير النطاقات المخصصة وDNS الخاص بها، وليس صناديق البريد.
• mailbox_operator - يدير صناديق البريد داخل النطاقات المخصصة، وليس النطاقات نفسها.
• read_only - يمكنه فحص واجهة الحساب المسموح بها دون تغييرها.
• custom - يتلقى فقط الصلاحيات المدرجة في permissions.

تتطلب بعض الأدوار domain_ids صريحة؛ ويمكن لأدوار أخرى استخدام all_domains. يخبرك كتالوج الوصول بالقاعدة المطبقة. إذا حاول المستدعي منح دور أو صلاحية أو مجموعة نطاقات أوسع، يعيد TrekMail الرمز scope_blocked_by_membership بدلا من تضييق الدعوة بصمت.

دعوة عميل

curl -s -X POST "https://trekmail.net/api/v1/white-label/members" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invite-northwind-admin-20260904" \
  -d '{
    "email": "admin@northwind.example",
    "role": "client",
    "all_domains": false,
    "domain_ids": [123, 124],
    "note": "Northwind primary contact"
  }'

تتضمن الاستجابة العضو، وما إذا نجح تسليم البريد الإلكتروني، وعنوان URL للدعوة يستخدم مرة واحدة. لا تمحو مشكلة التسليم الدعوة، إذ يستطيع المالك نسخ عنوان URL أو إعادة إرسالها لاحقا.

للدور المخصص، اقرأ grantable_permissions من كتالوج الوصول وأرسل القيم المحددة في permissions. يلزم إذن واحد على الأقل.

متابعة حالة العضو

تتضمن كل استجابة عضو allowed_operations. استخدم هذه القائمة بدلا من التخمين:

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

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

لا يستطيع المستدعون إزالة أنفسهم أو تعليق أنفسهم. ولا يستطيع المستدعون المفوضون إدارة عضو يكون وصوله أوسع من وصولهم. تعيد الانتقالات غير الصالحة membership_state_conflict مع تلميح لإعادة قراءة العضو.

يؤدي تعليق شخص أو إزالته إلى إبطال مفاتيح API وصندوق البريد المنشأة ضمن تلك العضوية. لا يؤدي استئناف العضوية أو استعادتها إلى إعادة تلك المفاتيح القديمة؛ بل يجب على الشخص إعادة الاتصال أو إنشاء بيانات اعتماد جديدة.

حدود النشاط والخصوصية

يعيد GET /white-label/activity الدعوات وتغييرات الأدوار والنطاقات وعمليات التعليق والإزالة والاستعادة وإجراءات الأمان ذات الصلة. رشّح باستخدام action وmember_id وper_page.

يجمع GET /white-label/members/{id}/activity إجراءات حساب ذلك العضو مع عمليات الدخول الحديثة، بما فيها الوقت وعنوان IP والموقع التقريبي والمتصفح ونظام التشغيل ونوع الجهاز. يتطلب هذا المسار نطاقي القراءة كليهما عن قصد. لا يستطيع المستدعون المقيدون بالنطاقات طلب سوى الأعضاء الموجودين بالكامل داخل حدود نطاقاتهم؛ ويعاد العضو غير المتاح بالرمز 404، لذلك لا تكشف نقطة النهاية عن وجود مستأجر أو عميل آخر.

حدود تخزين العملاء

يمنح حدّ تخزين العميل نطاقات العميل مساحة واحدة بوحدة MB لصناديق البريد وDrive فيها. لمعرفة طريقة عمله في لوحة التحكم، راجع حدّ تخزين خاص لكل عميل من عملائك. الحدّ الذي لا يملك أحد في الفريق نطاقاته، مثل حدّ أُنشئ هنا قبل دعوة العميل، يظهر في صفحة الفريق والعملاء تحت حدود تخزين بلا عميل.

• القراءة تتطلب members:read. المستدعي المقيد ببعض النطاقات لا يرى إلا الحدود التي تكون كل نطاقاتها من نطاقاته. أما حدّ عميل آخر، أو حدّ يشمل أيضا نطاقا خارج صلاحياته، فلا يظهر في القائمة ويعيد 404 كمعرّف غير موجود.
• التغيير يتطلب members:write ومستدعيا يصل إلى كل نطاقات الحساب. يتلقى العضو المقيد ببعض النطاقات 403 scope_blocked_by_membership، ويتلقى المفتاح المقيد ببعض النطاقات 403 token_resource_constrained.
• POST يعمل مثل صفحة الفريق والعملاء: النطاقات التي ليس لها حدّ تحصل على حدّ جديد (201)؛ وإذا كانت النطاقات تتشارك حدّا بالفعل، يتغير ذلك الحدّ وتنضم إليه النطاقات المحددة التي ليس لها حدّ (200).
• PATCH يقبل storage_limit_mb أو domain_ids أو كليهما. يستبدل domain_ids المجموعة كاملة، وتعود النطاقات غير المذكورة إلى تخزين الحساب.
• كل حدّ يعيد storage_limit_mb وdomain_ids وallocated_mb (الأحجام الثابتة لصناديق البريد) وpending_invites_mb (الأحجام الثابتة للدعوات المفتوحة) وpool_mb (ما تتشاركه صناديق البريد ذات التخزين المشترك) وused_bytes وmember_ids.

يحمل كل سجل عضو الحقل client_limit: الحدّ الواحد الذي تقع تحته كل نطاقات العضو، بالحقول id وstorage_limit_mb وallocated_mb وused_bytes، أو null. وبالنسبة إلى المستدعي المقيد ببعض النطاقات، تكون قيمته null أيضا عندما يشمل ذلك الحدّ نطاقا خارج صلاحياته.

يُضبط الحجم الخاص لصندوق البريد عبر PATCH /mailboxes/{id}/storage (mailboxes:write) أو الأداة set_mailbox_storage، كما يشرح دليل REST API.

أدوات MCP

تتطلب أدوات الدعوة TREKMAIL_ALLOW_SENDING=true على MCP المستضاف ذاتيا عبر stdio. وتتطلب أدوات تغيير الوصول وأدوات حدود تخزين العملاء TREKMAIL_ALLOW_DESTRUCTIVE=true؛ كما تتطلب إزالة عضو أو حدّ confirm_remove=true. والأداة set_mailbox_storage، وهي ليست من مجموعة White Label، لها الشرط نفسه. هذه المفاتيح عناصر تحكم محلية في الأمان وليست صلاحيات API إضافية. يطبق MCP المستضاف سياسة الأمان المعتمدة الخاصة به.

تنشئ الأدوات مفاتيح تكرار حتمية عندما لا تقدم مفتاحا. يفيد تقديم idempotency_key خاص بك عندما يمكن إعادة تشغيل سير العمل في عملية مختلفة.

سير عمل آمن للأتمتة

1. استدع get_white_label. توقف عند scope_blocked_by_entitlement؛ وفي استجابة grace الناجحة، تابع عمليات القراءة فقط.
2. استدع get_white_label_access_catalog مباشرة قبل منح الوصول.
3. اعرض العضو المستهدف أو اقرأه قبل تغييره.
4. تحقق من allowed_operations والدور المقصود والصلاحيات ومعرفات النطاقات.
5. استخدم مفتاح تكرار ثابتا للكتابة.
6. اقرأ العضو مرة أخرى وأبلغ عن الحالة الناتجة والصلاحيات الفعلية.
7. تحقق من نشاط White Label عندما تحتاج إلى سجل تدقيق للتغيير.

أخطاء توضح ما يجب فعله