ניהול צוותי 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 כשנדרשת רשומת ביקורת של השינוי.

שגיאות שמסבירות מה לעשות