White-Label-Teams mit API und MCP verwalten

White-Label-Konten können verwaltet werden, ohne zum Dashboard zurückzukehren. Die REST-API und der MCP-Server decken den Einrichtungsstatus des Kontos, Kunden und Teammitglieder, Rollen, Domainzugriffe, Einladungen, Sperrungen, Entfernungen, Wiederherstellungen und den Aktivitätsverlauf ab. Das Branding gehört zum selben White-Label-Werkzeugsatz und wird in einem eigenen Branding-Leitfaden beschrieben.

Die wichtige Grenze ist einfach: Eine Verbindung kann niemals mehr Zugriff vergeben, als die dahinterstehende Person bereits besitzt. Ein auf bestimmte Domains beschränkter Manager kann niemanden zu anderen Domains einladen, und eine benutzerdefinierte Rolle kann keine Berechtigungen erteilen, die der Aufrufer nicht selbst hat.

Verfügbare Funktionen

Der vollständige MCP-Katalog enthält jetzt 261 Tools über stdio und bis zu 260 Tools über gehostetes HTTP. White Label steuert 20 Tools bei: sieben für Branding und 13 für die Verwaltung von Konten, Mitgliedern und Aktivitäten.

Diese Tools werden nicht für alle geladen. TrekMail prüft die aktuelle White-Label-Berechtigung des Kontos, die derzeitige Mitgliedschaft der Person, das Token oder die OAuth-Genehmigung, mögliche Domainbeschränkungen, die ausgewählten Toolsets und lokale Sicherheitseinstellungen, bevor tools/list erstellt wird. Eine Verbindung ohne White-Label-Zugriff erhält die Schemas überhaupt nicht.

Berechtigungsstatus

Rufen Sie mit White-Label-Lesezugriff GET /api/v1/white-label oder das Tool get_white_label auf, um active vom schreibgeschützten Status grace zu unterscheiden und den Einrichtungsfortschritt sowie das Ende der Kulanzfrist anzuzeigen. Ein nicht verfügbares Konto kann diesen Endpoint nicht aufrufen: Wenn gespeicherte Anmeldedaten weiterhin einen White-Label-Scope enthalten, den das Konto nicht mehr verwenden darf, gibt die API scope_blocked_by_entitlement zurück und erläutert, wo er reaktiviert werden kann.

Scopes

Der Endpoint für Mitgliederaktivitäten benötigt sowohl activity:read als auch members:read, da seine Antwort neben Aktivitäten auch einen Mitgliedsdatensatz enthält. Die gehostete OAuth-Verbindung verwendet den Selektor tools:white_label, um diese Toolfamilie anzufordern. Die effektiven REST-Scopes bleiben dennoch durch das Konto und die Mitgliedschaft begrenzt.

Fügen Sie bei einem selbst gehosteten MCP-Server white_label zu TREKMAIL_TOOLSETS hinzu, wenn Sie eine Positivliste für Toolsets verwenden. Schreib-Tools beachten außerdem die unten beschriebenen lokalen Sicherheitskontrollen.

REST-Endpoints

Alle Pfade befinden sich unter https://trekmail.net/api/v1.

Jeder Schreibvorgang in dieser Tabelle erfordert einen Idempotency-Key-Header. Wird dieselbe Anfrage mit demselben Schlüssel wiederholt, wird das ursprüngliche sichere Ergebnis zurückgegeben. Einmalige Geheimnisse in einer Wiederholung, etwa ein Einladungstoken, werden unkenntlich gemacht. Wird ein Schlüssel mit einem anderen Body wiederverwendet, lautet die Antwort idempotency_mismatch.

Zuerst den Zugriffskatalog lesen

Codieren Sie Rollenberechtigungen nicht fest in eine Integration. Rufen Sie vor einer Einladung oder Zugriffsänderung den Zugriffskatalog ab. Seine grantable-Flags spiegeln die aktuelle Mitgliedschaft des Aufrufers wider und können sich ändern, wenn der Inhaber diese Mitgliedschaft anpasst.

Für neue Einladungen werden derzeit folgende Rollen angeboten:

• client - verwaltet die zugewiesenen Domains und Postfächer, ohne die private Geschäftsbeziehung des Resellers mit TrekMail zu sehen.
• webmail_only - erscheint in der Teamliste, erhält jedoch keine Dashboard-Berechtigungen.
• domain_admin - verwaltet zugewiesene Domains und deren DNS, aber keine Postfächer.
• mailbox_operator - verwaltet Postfächer innerhalb zugewiesener Domains, aber nicht die Domains selbst.
• read_only - kann den erlaubten Kontobereich einsehen, ohne ihn zu ändern.
• custom - erhält nur die in permissions aufgeführten Berechtigungen.

Einige Rollen erfordern ausdrückliche domain_ids, andere können all_domains verwenden. Der Zugriffskatalog zeigt, welche Regel gilt. Versucht der Aufrufer, eine umfangreichere Rolle, Berechtigung oder Domainauswahl zu vergeben, gibt TrekMail scope_blocked_by_membership zurück, statt die Einladung unbemerkt einzuschränken.

Einen Kunden einladen

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

Die Antwort enthält das Mitglied, den Erfolg der E-Mail-Zustellung und eine einmalig verwendbare Einladungs-URL. Ein Zustellungsproblem löscht die Einladung nicht: Der Inhaber kann die URL kopieren oder die Einladung später erneut versenden.

Lesen Sie für eine benutzerdefinierte Rolle grantable_permissions aus dem Zugriffskatalog und senden Sie die ausgewählten Werte in permissions. Mindestens eine Berechtigung ist erforderlich.

Mitgliedsstatus verfolgen

Jede Antwort zu einem Mitglied enthält allowed_operations. Verwenden Sie diese Liste, statt zu raten:

• Eine ausstehende Einladung kann aktualisiert, gesperrt, erneut versendet oder entfernt werden.
• Ein aktives Mitglied kann aktualisiert, gesperrt oder entfernt werden.
• Ein gesperrtes Mitglied kann aktualisiert, fortgesetzt oder entfernt werden.
• Ein entferntes Mitglied kann wiederhergestellt werden.
• Die Zeile des Inhabers wird zur Einordnung angezeigt, kann aber über diese Endpoints nicht geändert werden.

Die Liste wird außerdem für den aktuellen Aufrufer gefiltert. Sie ist bei einer schreibgeschützten Verbindung, bei der eigenen Mitgliedschaft des Aufrufers und bei Mitgliedern leer, deren Berechtigungen über den Verwaltungsrahmen des Aufrufers hinausgehen.

Aufrufer können sich nicht selbst entfernen oder sperren. Delegierte Aufrufer können außerdem kein Mitglied verwalten, dessen Zugriff umfangreicher als ihr eigener ist. Ungültige Übergänge geben membership_state_conflict mit dem Hinweis zurück, das Mitglied erneut zu lesen.

Wenn eine Person gesperrt oder entfernt wird, werden die unter dieser Mitgliedschaft erstellten API- und Postfachschlüssel widerrufen. Beim Fortsetzen oder Wiederherstellen der Mitgliedschaft werden diese alten Schlüssel niemals reaktiviert. Die Person muss die Verbindung neu herstellen oder neue Anmeldedaten erstellen.

Grenzen für Aktivitäten und Datenschutz

GET /white-label/activity gibt Einladungen, Rollen- und Domainänderungen, Sperrungen, Entfernungen, Wiederherstellungen und zugehörige Sicherheitsaktionen zurück. Filtern Sie mit action, member_id und per_page.

GET /white-label/members/{id}/activity kombiniert die Kontoaktionen dieses Mitglieds mit kürzlichen Anmeldungen, einschließlich Uhrzeit, IP-Adresse, ungefährer Position, Browser, Betriebssystem und Gerätetyp. Diese Route erfordert absichtlich beide Lese-Scopes. Auf Domainbereiche beschränkte Aufrufer können nur Mitglieder anfordern, die vollständig innerhalb ihrer Domainbegrenzung liegen. Ein nicht zugängliches Mitglied wird als 404 zurückgegeben, sodass der Endpoint die Existenz eines anderen Mandanten oder Kunden nicht offenlegt.

MCP-Tools

Einladungs-Tools erfordern TREKMAIL_ALLOW_SENDING=true bei selbst gehostetem stdio-MCP. Tools, die Zugriffe ändern, erfordern TREKMAIL_ALLOW_DESTRUCTIVE=true. Für die Entfernung ist außerdem confirm_remove=true erforderlich. Diese Schalter sind lokale Sicherheitskontrollen und keine zusätzlichen API-Berechtigungen. Gehostetes MCP wendet seine eigene genehmigte Sicherheitsrichtlinie an.

Die Tools erstellen deterministische Idempotenzschlüssel, wenn Sie keinen angeben. Ein eigener idempotency_key ist nützlich, wenn ein Workflow in einem anderen Prozess neu gestartet werden könnte.

Ein sicherer Automatisierungsablauf

1. Rufen Sie get_white_label auf. Stoppen Sie bei scope_blocked_by_entitlement; fahren Sie bei einer erfolgreichen grace-Antwort nur mit Lesevorgängen fort.
2. Rufen Sie get_white_label_access_catalog unmittelbar vor der Zugriffsvergabe auf.
3. Listen oder lesen Sie das Zielmitglied, bevor Sie es ändern.
4. Prüfen Sie allowed_operations, die vorgesehene Rolle, Berechtigungen und Domain-IDs.
5. Verwenden Sie einen stabilen Idempotenzschlüssel für den Schreibvorgang.
6. Lesen Sie das Mitglied erneut und melden Sie den daraus resultierenden Status sowie die effektiven Berechtigungen.
7. Prüfen Sie die White-Label-Aktivitäten, wenn Sie einen Auditdatensatz der Änderung benötigen.

Fehler mit konkreten Handlungshinweisen