دليل 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 مع خطوة تالية مباشرة. لا يؤدي إنشاء رمز أوسع إلى تجاوز الاستحقاق.

النطاقات المطلوبة

للعلامة التجارية نطاقاتها الخاصة. يمنع ذلك الأتمتة التي تدير النطاقات العادية من رؤية هوية الموزع أو تغييرها عن طريق الخطأ.

نقاط نهاية REST

تقع جميع نقاط النهاية ضمن https://trekmail.net/api/v1. يمثل {id} id النطاق الرقمي.

تعيد كل نقطة نهاية باستثناء 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"
  }'

حقول النص:

تحميل شعار

تُرسل الشعارات بصيغة 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 مخصصة للقراءة فقط. أثناء فترة السماح بعد إلغاء المالك تظل متاحة، بينما تختفي أدوات الكتابة الست كلها. من دون استحقاق White Label، لا يُعلن عن أي من هذه الأدوات في tools/list.

التدفق المستقل من البداية إلى النهاية

إذا كان DNS لنطاقك على Cloudflare، يستطيع وكيل نقل النطاق من دون علامة إلى مضيف ذي علامة يعمل من دون أي خطوات بشرية، لأن أدوات DNS الحالية في Cloudflare (apply_cloudflare_dns) تستطيع كتابة سجلات CNAME التي يعيدها get_domain_branding.

1. عيّن العلامة. set_domain_branding(mode=custom, name, primary_color, accent_color, dashboard_enabled=true, webmail_enabled=true).
2. حمّل الشعارات (اختياري). set_domain_brand_logo(slot="light", content_base64=…)، وكرر ذلك لـdark وfavicon.
3. اقرأ سجلات DNS. get_domain_branding → انسخ مصفوفة dns_records المعادة. لا تخمّن القيم أو تنشئها.
4. اكتب سجلات CNAME. انشر هذه السجلات مع إيقاف الوكيل. يعني ذلك في Cloudflare استخدام سحابة رمادية حتى يعمل التحقق من DNS وSSL.
5. تحقق. verify_domain_branding_dns.
6. استطلع. أعد استدعاء get_domain_branding حتى تصبح status لكل مضيف هي active.
7. عاين (اختياري). استخدم 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 المستضاف محليًا حمايتها.