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

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