API- und MCP-Leitfaden für White-Label-Branding

White-Label-Branding pro Domain lässt sich vollständig über die API und MCP konfigurieren, ohne das Dashboard zu verwenden. Ein Agent kann den Markennamen und die Farben einer Domain festlegen, Logos hochladen, gebrandete Dashboard- und Webmail-Hosts aktivieren, die zu erstellenden DNS-Einträge lesen und eine DNS-Prüfung anfordern. Dies ist dasselbe Branding, das die Dashboard-Registerkarte Branding schreibt; die API ermöglicht lediglich, dass ein Agent oder Skript diese Arbeit übernimmt.

Branding wird pro Domain konfiguriert (die Domain ist die numerische id). Eine Domain kann eine eigene Marke (custom) verwenden, den Kontostandard erben (inherit) oder deaktiviert sein. Die API gibt die gebrandeten Hostnamen und die CNAME-Einträge dieser Domain zurück. Kopieren Sie die zurückgegebenen Einträge immer exakt. Leiten Sie keinen Hostnamen oder CNAME-Zielwert aus einem Beispiel in diesem Leitfaden ab.

Add-on-Zugangsprüfung

Jeder E-Mail-Tarif enthält eine 30-tägige White-Label-Testversion mit Vorschau. Nutzen Sie diese Zeit, um die Marke einzurichten und das Erlebnis zu testen, bevor Sie Ihren Kunden die gebrandeten Hosts bereitstellen.

Die API verwendet dieselben Zugangsrechte wie das White-Label-Dashboard:

• Aktive Testversion oder bezahltes Add-on: Lese- und Schreibberechtigungen sind verfügbar. Aktivierte Hosts wechseln von pending_dns zu active, sobald ihr CNAME aufgelöst und das SSL-Zertifikat ausgestellt wurde.
• Kulanzfrist nach Kündigung: Der Kontoinhaber behält bis zum angezeigten Zeitpunkt hard_delete_at schreibgeschützten Zugriff. Schreibvorgänge werden blockiert und delegierte Verbindungen verlieren sofort ihren White-Label-Zugriff.
• Kein aktives Zugangsrecht: White-Label-Berechtigungen werden aus den effektiven Berechtigungen der Anmeldedaten entfernt und die zugehörigen MCP-Tools werden nicht geladen.

Wenn ein gespeichertes Token früher eine White-Label-Berechtigung besaß, das Zugangsrecht aber nicht mehr aktiv ist, gibt die API 403 scope_blocked_by_entitlement mit einem konkreten nächsten Schritt zurück. Ein breiteres Token umgeht das Zugangsrecht nicht.

Erforderliche Berechtigungen

Branding besitzt eigene Berechtigungen. Dadurch kann eine Automatisierung, die gewöhnliche Domains verwaltet, die Identität des Resellers nicht versehentlich sehen oder ändern.

REST-Endpunkte

Alle Endpunkte liegen unter https://trekmail.net/api/v1. {id} ist die numerische Domain-id.

Jeder Endpunkt außer verify-dns und preview gibt dieselben Branding-Daten wie GET zurück. Eine einzige Anfrage zeigt daher den neuen Status.

Branding-Daten

{
  "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 und mail_zone sind null, wenn mode den Wert off hat. mail_zone.enabled ist die gespeicherte Absicht; verwenden Sie die beiden Statusfelder, um ausstehende, aktive, fehlgeschlagene und Bereinigungszustände zu unterscheiden. Der Host-status zeigt, ob DNS und SSL noch ausstehen oder der Host aktiv ist. Die Platzhalterwerte im Beispiel sind beabsichtigt: Die zurückgegebenen Werte dns_records und cname_target sind die einzigen Werte, die veröffentlicht werden dürfen.

mail_zone beschreibt die eigenen Mail-Hostnamen der Marke (siehe unten). dns_status deckt den Mail-DNS-Status ab, client_hosts_status den Client-Host- und Zertifikatstatus; beide können off, pending_dns, active oder failed lauten. records listet die DNS-Einträge auf, die Ihr Anbieter veröffentlichen muss. dav_url kann immer sicher verwendet werden: Die URL bleibt bei TrekMail, bis das gebrandete DAV-Zertifikat und die eingeschränkte Webroute bereit sind. Wechseln Sie erst, wenn dav_ready den Wert true annimmt; cert_expires_at meldet dann den frühesten Zertifikatablauf der gebrandeten Mail-App-Hosts.

Aktuelles Branding lesen

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

Marke festlegen (teilweise Zusammenführung)

PATCH führt eine teilweise Zusammenführung aus. Ausgelassene Felder bleiben erhalten. Senden Sie daher nur die zu ändernden Felder.

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"
  }'

Felder im Body:

Logo hochladen

Logos werden als base64 übertragen. slot ist light, dark oder favicon. PNG und JPG werden für jeden Slot akzeptiert, ICO zusätzlich für favicon. Maximal 1 MB. SVG wird abgelehnt, um die Sicherheit zu gewährleisten. Der Standard scope=domain ändert nur eine Domain im Modus custom; ein geerbtes Profil wird nie automatisch geändert. Um das gemeinsame Profil bewusst über eine inherit-Domain zu ändern, übergeben Sie scope=account_default und verwenden ein unbeschränktes branding:write-Token. Domainbeschränkte Tokens können den Kontostandard nicht ändern.

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)\"}"

Entfernen Sie einen Slot mit 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"

Beide geben die Branding-Daten mit aktualisierten Werten für logo_url / logo_dark_url / favicon_url zurück. PUT akzeptiert scope im JSON-Body, DELETE als Abfrageparameter. Eine implizite domainbeschränkte Änderung an einem geerbten Profil gibt 422 inherited_brand zurück.

DNS prüfen

Nachdem Sie die CNAME-Einträge erstellt haben (siehe Ablauf unten), reihen Sie die Prüfung ein:

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 } }

Dies läuft im Hintergrund. Lesen Sie GET /branding erneut und beobachten Sie, wie der Host-status zu active wechselt. Wenn White Label abläuft, gibt die Anfrage 403 scope_blocked_by_entitlement mit einem Hinweis zur Reaktivierung zurück.

Auch die Mailzone der Marke wird erneut geprüft, sofern sie existiert. mail_zone.dns_status und mail_zone.client_hosts_status entwickeln sich daher mit demselben Aufruf weiter. Sie müssen den Aufruf für die Zone nicht ausführen: Wir prüfen wartende Zonen regelmäßig und aktivieren sie innerhalb weniger Minuten nach der Auflösung der Einträge. verify-dns fordert diese Prüfung lediglich sofort statt beim nächsten Durchlauf an.

E-Mail unter der eigenen Domain der Marke

mail_zone_enabled zeigt den Reseller-Namen in den Mail-Apps und DAV-Synchronisierungsclients seiner Kunden. Aktivieren Sie die Funktion und veröffentlichen Sie dann jeden in mail_zone.records zurückgegebenen Eintrag. Dazu gehören ein SPF-TXT-Eintrag sowie IMAP- und DAV-CNAME-Einträge. Die genauen Namen und Ziele Ihrer Antwort sind verbindlich.

Verwenden Sie einen CNAME statt eines A-Eintrags, wenn der zurückgegebene Eintrag dies verlangt, und lassen Sie die Cloudflare-Wolke grau. Mail- und DAV-Clients müssen sich direkt verbinden; ein DNS-Proxy kann Zertifikatsprüfungen und Nicht-Browser-Protokolle stören. Die Antwort nennt jeden zu veröffentlichenden Eintrag. Fügen Sie daher keine vermuteten Mail-Einträge hinzu.

Sobald die Einträge aufgelöst werden, stellt TrekMail die Zertifikate aus und aktiviert die Hostnamen. Beobachten Sie mail_zone.client_hosts_status, bis der Wert active lautet, und mail_zone.dav_ready, bis der Wert true lautet. Verwenden Sie weiterhin den zurückgegebenen dav_url; er wechselt erst dann von der Plattformadresse zur gebrandeten Adresse, wenn DAV sicher bereitgestellt werden kann. Wenn der Hoststatus failed meldet, führen Sie die DNS-Prüfung erneut aus und eröffnen Sie ein Support-Ticket, falls der Fehler bestehen bleibt.

Live-Vorschau erstellen

POST /branding/preview erstellt eine 72 Stunden gültige URL, mit der Sie das gebrandete Erlebnis vor der DNS-Aktivierung ansehen können:

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"

Die Antwort enthält eine Vorschau-URL, die nach 72 Stunden abläuft. 422 no_brand wird zurückgegeben, wenn keine Marke für die Vorschau vorhanden ist, weil Branding deaktiviert oder noch nicht eingerichtet wurde.

Branding löschen

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 löscht nur diese Domain; scope=all löscht das Branding im gesamten Konto. Die Branding-Daten werden zurückgegeben.

MCP-Tools

Sieben Tools decken Branding im 20 Tools umfassenden Toolset white_label ab. Sie werden nur registriert, wenn die Verbindung eine effektive Branding-Berechtigung besitzt und White Label verfügbar ist. Das Lesetool benötigt branding:read; die anderen sechs benötigen branding:write. Bei einem lokal gehosteten MCP-Server kann zusätzlich erforderlich sein, dass der Administrator Schreibaktionen erlaubt.

get_domain_branding ist schreibgeschützt. Während der Kündigungskulanz des Inhabers bleibt es verfügbar, während alle sechs Schreibtools verschwinden. Ohne White-Label-Zugangsrecht wird keines dieser Tools in tools/list angeboten.

Autonomer vollständiger Ablauf

Wenn das DNS Ihrer Domain bei Cloudflare liegt, kann ein Agent eine Domain ohne Branding ohne menschliche Schritte in einen aktiven gebrandeten Host verwandeln. Die vorhandenen Cloudflare-DNS-Tools (apply_cloudflare_dns) können die von get_domain_branding zurückgegebenen CNAMEs schreiben.

1. Marke festlegen. set_domain_branding(mode=custom, name, primary_color, accent_color, dashboard_enabled=true, webmail_enabled=true).
2. Logos hochladen (optional). set_domain_brand_logo(slot="light", content_base64=…), dann für dark und favicon wiederholen.
3. DNS-Einträge lesen. get_domain_branding → das zurückgegebene Array dns_records kopieren. Werte weder erraten noch generieren.
4. CNAMEs schreiben. Die Einträge mit deaktiviertem Proxy veröffentlichen. In Cloudflare bedeutet dies eine graue Wolke, damit DNS- und SSL-Prüfungen funktionieren.
5. Prüfen. verify_domain_branding_dns.
6. Abfragen. get_domain_branding erneut aufrufen, bis der status jedes Hosts active lautet.
7. Vorschau (optional). create_branding_preview für eine Live-Demo-URL verwenden, bevor Sie Kunden auf die gebrandete Domain verweisen.

Praxisbeispiel (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

Bitten Sie den Agenten, die gebrandeten Hostnamen und deren endgültigen Status zu melden, damit Sie wissen, dass sie tatsächlich aktiv sind und nicht nur pending_dns anzeigen.

Wichtige Hinweise

• Das Zugangsrecht steuert API- und MCP-Oberfläche. Für Schreibvorgänge ist eine aktive Testversion oder ein bezahltes Add-on erforderlich. Der Inhaber erhält nach der Kündigung ein schreibgeschütztes Wiederherstellungsfenster; alle anderen verlieren diese Tools sofort.
• PATCH ist eine teilweise Zusammenführung. Ausgelassene Felder bleiben erhalten. Um nur die Akzentfarbe zu ändern, senden Sie {"accent_color":"#10b981"}. Name, Logos und Schalter müssen nicht erneut gesendet werden.
• Die Reaktivierung aus dem deaktivierten Zustand erfordert mode. Wenn Branding derzeit off ist, aktiviert ein PATCH ohne mode es nicht erneut. Übergeben Sie mode=custom (oder inherit) zur Reaktivierung.
• sender_email benötigt eine Domain mit geprüftem DKIM. Die festgelegte From-Adresse muss zu einer Domain gehören, für die bereits ein DKIM-Schlüssel im Konto bereitgestellt wurde. Andernfalls wird die Aktualisierung abgelehnt. Prüfen Sie DKIM der Domain (retry_domain_dkim / get_dns_check), bevor Sie einen benutzerdefinierten Absender festlegen.
• Logos sind base64, ≤1 MB, kein SVG. Senden Sie PNG oder JPG (ICO ist für favicon ebenfalls zulässig) als content_base64. SVG wird abgelehnt. Komprimieren Sie große Quelldateien zuerst.
• Lassen Sie zurückgegebene CNAME-Einträge ohne Proxy. Eine orange Cloudflare-Wolke oder ein anderer CDN-Proxy verhindert DNS- und SSL-Prüfungen. Veröffentlichen Sie die dns_records wie zurückgegeben mit proxied:false.
• Schreibaktionen benötigen den richtigen Zugriff. Jedes Tool außer get_domain_branding ändert Daten. Verwenden Sie daher die erforderliche Schreibberechtigung und aktivieren Sie Schreibvorgänge, wenn der Administrator Ihres lokal gehosteten MCP sie abgesichert hat.