מדריך API ו-MCP למיתוג White Label

אפשר להגדיר מיתוג White Label לכל דומיין מתחילתו ועד סופו דרך API ו-MCP, ללא צורך בלוח הבקרה. סוכן יכול להגדיר את שם המותג והצבעים של דומיין, להעלות לוגואים, להפעיל מארחים ממותגים ללוח הבקרה ולדואר האינטרנט, לקרוא את רשומות ה-DNS שעליו ליצור ולבקש אימות DNS. זהו אותו מיתוג שנכתב בכרטיסייה Branding בלוח הבקרה; ה-API פשוט מאפשר לסוכן או לסקריפט לבצע זאת עבורכם.

המיתוג מוגדר לכל דומיין (הדומיין הוא id מספרי). דומיין יכול להשתמש במותג משלו (custom), לרשת את ברירת המחדל של החשבון (inherit) או להיות כבוי. ה-API מחזיר את שמות המארחים הממותגים ואת רשומות ה-CNAME של הדומיין. העתיקו תמיד את הרשומות שהוחזרו במדויק. אל תבנו שם מארח או יעד CNAME מדוגמה במדריך זה.

שער התוסף

כל תוכנית דואר כוללת תקופת ניסיון ותצוגה מקדימה של White Label למשך 30 ימים. השתמשו בתקופה זו כדי להגדיר את המותג ולבדוק את החוויה לפני שתאפשרו ללקוחות להשתמש במארחים הממותגים.

ה-API מחיל את אותה זכאות כמו לוח הבקרה של White Label:

תקופת ניסיון פעילה או תוסף בתשלום: טווחי קריאה וכתיבה זמינים. מארחים מופעלים עוברים מ-pending_dns ל-active לאחר שה-CNAME שלהם נפתר ומונפק עבורם SSL.
תקופת חסד לאחר ביטול: בעל החשבון שומר על גישת קריאה בלבד עד למועד hard_delete_at המוצג. פעולות כתיבה נחסמות, וחיבורים מואצלים מאבדים מיד את הגישה ל-White Label.
אין זכאות פעילה: טווחי White Label מוסרים מההרשאות בפועל של פרטי האימות, וכלי ה-MCP שלהם אינם נטענים.

אם אסימון שמור החזיק בעבר טווח White Label אך הזכאות כבר אינה פעילה, ה-API מחזיר 403 scope_blocked_by_entitlement עם הצעד הבא לביצוע. יצירת אסימון רחב יותר אינה עוקפת את הזכאות.

טווחים נדרשים

למיתוג יש טווחים משלו. כך אוטומציה שמנהלת דומיינים רגילים לא תראה או תשנה בטעות את זהות המשווק.

טווח	מכסה
`branding:read`	קריאת המותג, הנכסים, המארחים הממותגים, מצב אזור הדואר ורשומות ה-DNS הנדרשות של דומיין
`branding:write`	שינוי המיתוג, העלאה או הסרה של נכסים, בקשת תצוגה מקדימה, אימות DNS או ניקוי המיתוג

נקודות קצה של REST

כל נקודות הקצה נמצאות תחת https://trekmail.net/api/v1. הערך {id} הוא id הדומיין המספרי.

נקודת קצה	שיטה	טווח	פעולה
`/api/v1/domains/{id}/branding`	GET	`branding:read`	קריאת מצב המיתוג המלא: מצב, סטטוס התוסף, שדות המותג, מצב אזור הדואר, מארחים, רשומות CNAME ליצירה ויעד CNAME
`/api/v1/domains/{id}/branding`	PATCH	`branding:write`	עדכון המותג במיזוג חלקי: מצב, שם, צבעים, מתגים של מארחים ואזור דואר, שולח/תמיכה וטווח
`/api/v1/domains/{id}/branding/logo/{slot}`	PUT	`branding:write`	העלאת לוגו (`slot` = `light`, `dark` או `favicon`) מ-base64
`/api/v1/domains/{id}/branding/logo/{slot}`	DELETE	`branding:write`	הסרת משבצת לוגו
`/api/v1/domains/{id}/branding/verify-dns`	POST	`branding:write`	הוספת אימות DNS למארחים הממותגים המופעלים לתור
`/api/v1/domains/{id}/branding/preview`	POST	`branding:write`	יצירת כתובת URL לתצוגה מקדימה של החוויה הממותגת למשך 72 שעות
`/api/v1/domains/{id}/branding?scope=domain\|all`	DELETE	`branding:write`	ניקוי המיתוג של דומיין זה או של החשבון כולו

כל נקודת קצה מלבד verify-dns ו-preview מחזירה את אותו מטען מיתוג שמחזירה GET, כך שבקשה אחת מציגה את המצב החדש.

מטען המיתוג

{
  "data": {
    "mode": "custom",
    "white_label_addon_active": true,
    "brand": {
      "id": 42,
      "name": "Northwind Mail",
      "primary_color": "#2563eb",
      "accent_color": "#10b981",
      "logo_url": "https://trekmail.net/storage/branding/42/light.png",
      "logo_dark_url": "https://trekmail.net/storage/branding/42/dark.png",
      "favicon_url": "https://trekmail.net/storage/branding/42/favicon.png",
      "support_email": "support@northwind.com",
      "support_url": "https://help.northwind.com",
      "sender_email": "noreply@northwind.com"
    },
    "mail_zone": {
      "enabled": true,
      "domain": "northwind.com",
      "dns_status": "pending_dns",
      "client_hosts_status": "pending_dns",
      "records": [
        { "type": "TXT", "name": "spf.northwind.com", "value": "v=spf1 include:spf.trekmail.net -all" },
        { "type": "CNAME", "name": "imap.northwind.com", "value": "imap.trekmail.net" },
        { "type": "CNAME", "name": "dav.northwind.com", "value": "trekmail.net" }
      ],
      "dav_url": "https://trekmail.net/dav/files/account/",
      "dav_ready": false,
      "cert_expires_at": null,
      "checked_at": "2026-08-29T06:20:11+00:00"
    },
    "hosts": [
      { "kind": "dashboard", "hostname": "dashboard.northwind.com", "subdomain_label": "dashboard", "enabled": true, "status": "pending_dns" },
      { "kind": "webmail", "hostname": "mail.northwind.com", "subdomain_label": "mail", "enabled": true, "status": "pending_dns" }
    ],
    "dns_records": [
      { "type": "CNAME", "name": "<returned dashboard host>", "value": "<returned CNAME target>", "proxied": false },
      { "type": "CNAME", "name": "<returned webmail host>", "value": "<returned CNAME target>", "proxied": false }
    ],
    "cname_target": "<returned CNAME target>"
  }
}

הערכים brand ו-mail_zone הם null כאשר mode הוא off. הערך mail_zone.enabled הוא הכוונה השמורה; השתמשו בשני שדות הסטטוס כדי להבדיל בין מצבי המתנה, פעילות, כשל וניקוי. ה-status של המארח מציין אם DNS ו-SSL עדיין ממתינים או שהמארח פעיל. ערכי מצייני המיקום בדוגמה מכוונים: dns_records ו-cname_target המוחזרים הם הערכים היחידים שיש לפרסם.

mail_zone מתאר את שמות מארחי הדואר של המותג עצמו (ראו להלן). dns_status מכסה את מצב ה-DNS של הדואר ו-client_hosts_status מכסה את מצב מארחי הלקוחות והאישורים; שניהם יכולים להיות off, pending_dns, active או failed. הערך records מפרט את רשומות ה-DNS שהספק שלכם צריך לפרסם. תמיד בטוח להשתמש ב-dav_url: הוא נשאר ב-TrekMail עד שאישור ה-DAV הממותג ונתיב האינטרנט המוגבל מוכנים. עברו רק כאשר dav_ready הופך ל-true; לאחר מכן cert_expires_at מציג את מועד התפוגה המוקדם ביותר של אישורי מארחי יישומי הדואר הממותגים.

קריאת המיתוג הנוכחי

curl -s "https://trekmail.net/api/v1/domains/123/branding" \
  -H "Authorization: Bearer tm_live_your_token"

הגדרת המותג (מיזוג חלקי)

PATCH הוא מיזוג חלקי. כל שדה שתשמיטו נשמר, לכן שלחו רק את מה שברצונכם לשנות.

curl -s -X PATCH "https://trekmail.net/api/v1/domains/123/branding" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-123-initial" \
  -d '{
    "mode": "custom",
    "name": "Northwind Mail",
    "primary_color": "#2563eb",
    "accent_color": "#10b981",
    "dashboard_enabled": true,
    "dashboard_label": "dashboard",
    "webmail_enabled": true,
    "webmail_label": "mail",
    "mail_zone_enabled": true,
    "support_email": "support@northwind.com",
    "support_url": "https://help.northwind.com",
    "sender_email": "noreply@northwind.com"
  }'

שדות גוף הבקשה:

שדה	הערות
`mode`	`off`,‏ `inherit` (שימוש בברירת המחדל של החשבון) או `custom` (מותג ייחודי לדומיין). אם המיתוג כבוי כעת, חובה להעביר `mode` כדי להפעיל אותו מחדש.
`name`	שם המותג המוצג בסרגל הצד, במסך הכניסה, בכותרות הדפים ובחתימות הדואר.
`primary_color` / `accent_color`	קודים הקסדצימליים (`#2563eb`).
`dashboard_enabled` / `dashboard_label`	מתג ותווית תת-דומיין למארח לוח הבקרה.
`webmail_enabled` / `webmail_label`	מתג ותווית תת-דומיין למארח דואר האינטרנט.
`mail_zone_enabled`	מספק יישומי דואר וסנכרון DAV תחת הדומיין של המותג, כך שלקוחות רואים שמות כמו `imap.northwind.com` ו-`dav.northwind.com` במקום השמות שלנו. האזור שייך למותג ולא לדומיין יחיד, ולכן נדרש `mode=custom` או `scope=account_default`; שליחתו לדומיין `inherit` מחזירה `422 inherited_brand`. קראו את `mail_zone.dns_status`,‏ `mail_zone.client_hosts_status`,‏ `mail_zone.dav_ready` ו-`mail_zone.records` כדי לעקוב אחר ההקצאה ולפרסם את הרשומות שנותרו.
`support_email`	כתובת Reply-To/תמיכה בהודעות עסקה ממותגות.
`support_url`	כתובת URL של מרכז העזרה. מוסיפה קישור "זקוקים לעזרה?" לכותרת התחתונה של הודעות דואר ממותגות.
`sender_email`	כתובת From הגלויה בהודעות עסקה ממותגות. היא חייבת להיות בדומיין עם מפתח DKIM מאומת בחשבון, אחרת העדכון יידחה.
`scope`	`domain` (דומיין זה בלבד; ברירת המחדל), `account_default` (גם הגדרתו כברירת המחדל של החשבון לדומיינים חדשים) או `all` (גם החלתו על כל הדומיינים הקיימים).

העלאת לוגו

לוגואים נשלחים כ-base64. הערך slot הוא light,‏ dark או favicon. מתקבלים PNG ו-JPG לכל משבצת, וכן ICO עבור favicon. הגודל המרבי הוא 1 MB. SVG נדחה מסיבות אבטחה. ברירת המחדל scope=domain משנה רק דומיין במצב custom; היא לעולם אינה עוקבת אחר פרופיל שעבר בירושה. כדי לשנות במכוון את הפרופיל המשותף דרך דומיין inherit, העבירו scope=account_default והשתמשו באסימון branding:write ללא הגבלה. אסימונים המוגבלים לדומיין אינם יכולים לשנות את ברירת המחדל של החשבון.

curl -s -X PUT "https://trekmail.net/api/v1/domains/123/branding/logo/light" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-123-logo-light" \
  -d "{\"content_base64\":\"$(base64 -w0 logo-light.png)\"}"

הסירו משבצת באמצעות DELETE:

curl -s -X DELETE "https://trekmail.net/api/v1/domains/123/branding/logo/dark" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-logo-dark-remove"

שתי הפעולות מחזירות את מטען המיתוג עם logo_url / logo_dark_url / favicon_url המעודכנים. PUT מקבל את scope בגוף JSON; DELETE מקבל אותו כפרמטר שאילתה. שינוי מרומז בטווח דומיין בפרופיל שעבר בירושה מחזיר 422 inherited_brand.

אימות DNS

לאחר יצירת רשומות ה-CNAME (ראו את התהליך להלן), הוסיפו את האימות לתור:

curl -s -X POST "https://trekmail.net/api/v1/domains/123/branding/verify-dns" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-verify"

{ "data": { "status": "queued", "hosts": 2 } }

הפעולה רצה ברקע. קראו שוב את GET /branding ועקבו אחר מעבר ה-status של המארח ל-active. אם White Label פג, הבקשה מחזירה 403 scope_blocked_by_entitlement עם הנחיה להפעלה מחדש.

הפעולה גם בודקת מחדש את אזור הדואר של המותג, אם קיים, כך ש-mail_zone.dns_status ו-mail_zone.client_hosts_status מתעדכנים באותה קריאה. אין צורך לקרוא לה עבור האזור: אנו בודקים מחדש אזורים ממתינים לפי לוח זמנים ומפעילים אותם בתוך דקות מרגע שהרשומות נפתרות. verify-dns רק מבקש לבצע זאת כעת במקום בסריקה הבאה.

דואר בדומיין של המותג

mail_zone_enabled מציג את שם המשווק ביישומי הדואר ובלקוחות סנכרון DAV של הלקוחות. הפעילו אותו, ולאחר מכן פרסמו כל רשומה שמוחזרת ב-mail_zone.records. הן כוללות רשומת TXT של SPF וכן רשומות CNAME של IMAP ו-DAV. השמות והיעדים המדויקים בתגובה הם המקור המוסמך.

השתמשו ב-CNAME במקום ברשומת A כאשר הרשומה המוחזרת דורשת זאת, והשאירו את הענן של Cloudflare אפור. לקוחות דואר ו-DAV חייבים להתחבר ישירות; פרוקסי DNS עלול לשבש בדיקות אישורים ופרוטוקולים שאינם בדפדפן. התגובה מציגה כל רשומה שיש לפרסם, לכן אל תוסיפו רשומות דואר משוערות.

לאחר שהרשומות נפתרות, TrekMail מנפיקה את האישורים ומפעילה את שמות המארחים. עקבו אחר mail_zone.client_hosts_status עד שיהפוך ל-active ואחר mail_zone.dav_ready עד שיהפוך ל-true. המשיכו להשתמש ב-dav_url המוחזר; הוא משתנה מכתובת הפלטפורמה לכתובת הממותגת רק לאחר שבטוח לספק DAV. אם מצב המארח הוא failed, הריצו שוב אימות DNS ופתחו פניית תמיכה אם הכשל נמשך.

יצירת תצוגה מקדימה חיה

POST /branding/preview יוצר כתובת URL למשך 72 שעות, כדי שתוכלו לראות את החוויה הממותגת לפני הפעלת DNS:

curl -s -X POST "https://trekmail.net/api/v1/domains/123/branding/preview" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-preview"

התגובה כוללת כתובת URL לתצוגה מקדימה שתוקפה פג לאחר 72 שעות. היא מחזירה 422 no_brand כאשר אין מותג לתצוגה מקדימה משום שהמיתוג כבוי או טרם הוגדר.

מחיקת המיתוג

curl -s -X DELETE "https://trekmail.net/api/v1/domains/123/branding?scope=domain" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-remove"

scope=domain מנקה רק דומיין זה; scope=all מנקה את המיתוג בכל החשבון. הפעולה מחזירה את מטען המיתוג.

כלי MCP

שבעה כלים מטפלים במיתוג בתוך ערכת white_label הכוללת 20 כלים. הם נרשמים רק כאשר לחיבור יש טווח מיתוג בפועל ו-White Label זמין. כלי הקריאה דורש branding:read; ששת הכלים האחרים דורשים branding:write. שרת MCP באירוח מקומי עשוי גם לדרוש שמנהל המערכת יאשר פעולות כתיבה.

כלי	תיאור
`get_domain_branding`	קריאת מצב המיתוג המלא של דומיין: מצב, סטטוס התוסף, שדות המותג, מארחים, `dns_records` ליצירה ו-`mail_zone`
`set_domain_branding`	הגדרת המותג (מיזוג חלקי): מצב, שם, צבעים, מתגים ותוויות של לוח הבקרה/דואר האינטרנט/אזור הדואר, תמיכה/שולח וטווח
`set_domain_brand_logo`	העלאת לוגו מ-base64 למשבצת `light`,‏ `dark` או `favicon`
`verify_domain_branding_dns`	הוספת אימות DNS למארחים הממותגים המופעלים לתור
`create_branding_preview`	יצירת כתובת URL לתצוגה מקדימה של החוויה הממותגת
`remove_domain_brand_logo`	הסרת משבצת לוגו
`remove_domain_branding`	ניקוי המיתוג של הדומיין או החשבון כולו

get_domain_branding הוא לקריאה בלבד. במהלך תקופת החסד לאחר ביטול על ידי הבעלים הוא נשאר זמין, בעוד כל ששת כלי הכתיבה נעלמים. ללא זכאות ל-White Label, אף אחד מהכלים האלה אינו מפורסם ב-tools/list.

התהליך העצמאי מקצה לקצה

אם ה-DNS של הדומיין נמצא ב-Cloudflare, סוכן יכול להעביר דומיין ממצב ללא מיתוג למארח ממותג פעיל ללא שום שלב אנושי, מכיוון שכלי ה-DNS הקיימים של Cloudflare (apply_cloudflare_dns) יכולים לכתוב את רשומות ה-CNAME שמחזיר get_domain_branding.

הגדירו את המותג. set_domain_branding(mode=custom, name, primary_color, accent_color, dashboard_enabled=true, webmail_enabled=true).
העלו לוגואים (אופציונלי). set_domain_brand_logo(slot="light", content_base64=…), וחזרו על הפעולה עבור dark ו-favicon.
קראו את רשומות ה-DNS. get_domain_branding → העתיקו את מערך dns_records המוחזר. אל תנחשו או תיצרו ערכים.
כתבו את רשומות ה-CNAME. פרסמו אותן כשהפרוקסי כבוי. ב-Cloudflare המשמעות היא ענן אפור, כדי שאימות DNS ו-SSL יפעל.
אמתו. verify_domain_branding_dns.
בצעו תשאול. קראו שוב ל-get_domain_branding עד שה-status של כל מארח יהיה active.
הציגו תצוגה מקדימה (אופציונלי). השתמשו ב-create_branding_preview לקבלת כתובת URL להדגמה חיה לפני שתפנו לקוחות לדומיין הממותג.

דוגמה מלאה (MCP)

set_domain_branding(
  domain_id=123,
  mode="custom",
  name="Northwind Mail",
  primary_color="#2563eb",
  accent_color="#10b981",
  dashboard_enabled=true,
  webmail_enabled=true,
  support_email="support@northwind.com",
  sender_email="noreply@northwind.com"
)

set_domain_brand_logo(domain_id=123, slot="light", content_base64="iVBORw0KGgo…")
set_domain_brand_logo(domain_id=123, slot="dark", content_base64="iVBORw0KGgo…")

get_domain_branding(domain_id=123)
# → Copy the returned dns_records exactly. Do not substitute an example host or target.

apply_cloudflare_dns(domain_ids=[123])   # writes the CNAMEs, proxy off

verify_domain_branding_dns(domain_id=123)

# poll until active
get_domain_branding(domain_id=123)
# → hosts[].status: "active"

create_branding_preview(domain_id=123)   # optional live demo

בקשו מהסוכן לדווח על שמות המארחים הממותגים ועל המצבים הסופיים שלהם, כדי שתדעו שהם אכן פעילים ולא רק נמצאים ב-pending_dns.

נקודות חשובות

הזכאות שולטת בגישה ל-API ול-MCP. נדרשת תקופת ניסיון פעילה או תוסף בתשלום לפעולות כתיבה. לאחר ביטול, הבעלים מקבל חלון שחזור לקריאה בלבד; כל האחרים מאבדים מיד את הכלים האלה.
PATCH הוא מיזוג חלקי. שדות שהושמטו נשמרים. כדי לשנות רק את צבע ההדגשה, שלחו {"accent_color":"#10b981"}. אין צורך לשלוח מחדש את השם, הלוגואים או המתגים.
הפעלה מחדש ממצב כבוי דורשת mode. אם המיתוג נמצא כעת במצב off, בקשת PATCH שמשמיטה את mode לא תפעיל אותו מחדש. העבירו mode=custom (או inherit) כדי להפעיל מחדש.
sender_email דורש דומיין DKIM מאומת. כתובת From שתגדירו חייבת להיות בדומיין שכבר הוקצה לו מפתח DKIM בחשבון, אחרת העדכון יידחה. אמתו את ה-DKIM של הדומיין (retry_domain_dkim / get_dns_check) לפני הגדרת שולח מותאם אישית.
לוגואים הם base64, עד ≤1 MB, ללא SVG. שלחו PNG או JPG (גם ICO מותר עבור favicon) בתור content_base64. SVG נדחה. דחסו תחילה קובצי מקור גדולים.
השאירו את רשומות ה-CNAME המוחזרות ללא פרוקסי. ענן כתום של Cloudflare או פרוקסי CDN אחר מונעים אימות DNS ו-SSL. פרסמו את dns_records כפי שהוחזרו, עם proxied:false.
פעולות כתיבה דורשות גישה מתאימה. כל כלי מלבד get_domain_branding משנה נתונים, לכן השתמשו בטווח הכתיבה הנדרש ואפשרו כתיבה אם מנהל שרת ה-MCP המקומי בחר להגן עליה.

מדריך API ו-MCP למיתוג White Label

שער התוסף

טווחים נדרשים

נקודות קצה של REST

מטען המיתוג

קריאת המיתוג הנוכחי

הגדרת המותג (מיזוג חלקי)

העלאת לוגו

אימות DNS

דואר בדומיין של המותג

יצירת תצוגה מקדימה חיה

מחיקת המיתוג

כלי MCP

התהליך העצמאי מקצה לקצה

דוגמה מלאה (MCP)

נקודות חשובות

מאמרים קשורים

הגדרת White Label Lite בדומיין משלך

מהו White Label Lite ולמי הוא מתאים

שיטות מומלצות לנכסי מותג White Label

סקירת TrekMail REST API למפתחים

חיבור סוכני AI ל-TrekMail באמצעות MCP

המשיכו לקרוא

קטגוריות

התחברות ל-TrekMail

דוא״ל האיפוס נשלח