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

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

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

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

يتضمن كتالوج MCP الكامل الآن 261 أداة عبر stdio وما يصل إلى 260 أداة عبر HTTP المستضاف. تساهم White Label بعدد 20 أداة: سبع للعلامة التجارية و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، لذلك لا تكشف نقطة النهاية عن وجود مستأجر أو عميل آخر.

أدوات MCP

تتطلب أدوات الدعوة TREKMAIL_ALLOW_SENDING=true على MCP المستضاف ذاتيا عبر stdio. وتتطلب أدوات تغيير الوصول TREKMAIL_ALLOW_DESTRUCTIVE=true؛ كما تتطلب الإزالة confirm_remove=true. هذه المفاتيح عناصر تحكم محلية في الأمان وليست صلاحيات 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 عندما تحتاج إلى سجل تدقيق للتغيير.

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