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, Speicherlimits für Kunden 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 284 Tools über stdio und bis zu 283 Tools über gehostetes HTTP. White Label steuert 23 Tools bei: sieben für Branding, 13 für die Verwaltung von Konten, Mitgliedern und Aktivitäten und drei für Speicherlimits für Kunden.

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.

Speicherlimits für Kunden

Ein Speicherlimit für Kunden gibt den Domains eines Kunden eine gemeinsame Speichermenge in MB für ihre Postfächer und Drive. Wie das im Dashboard funktioniert, steht in Ein eigenes Speicherlimit für jeden Kunden. Ein Limit, dessen Domains niemand im Team hat, etwa eines, das hier vor der Einladung des Kunden angelegt wurde, erscheint auf der Seite Team & Kunden unter Speicherlimits ohne Kunden.

• Lesen erfordert members:read. Ein Aufrufer, der auf bestimmte Domains beschränkt ist, sieht nur die Limits, deren Domains ausnahmslos seine eigenen sind. Das Limit eines anderen Kunden oder ein Limit, das auch eine Domain umfasst, auf die er keinen Zugriff hat, erscheint nicht in der Liste, und ein Abruf liefert 404, als gäbe es die ID nicht.
• Ändern erfordert members:write und einen Aufrufer, der alle Domains des Kontos erreicht. Ein auf bestimmte Domains beschränktes Mitglied erhält 403 scope_blocked_by_membership, ein auf bestimmte Domains beschränkter Schlüssel erhält 403 token_resource_constrained.
• POST verhält sich wie die Seite Team & Kunden: Domains ohne Limit erhalten ein neues (201). Teilen die Domains bereits ein Limit, wird dieses geändert, und die angegebenen Domains ohne Limit kommen hinzu (200).
• PATCH nimmt storage_limit_mb, domain_ids oder beides. domain_ids ersetzt die gesamte Domainliste, und weggelassene Domains nutzen wieder den Speicher des Kontos.
• Jedes Limit liefert storage_limit_mb, domain_ids, allocated_mb (feste Postfachgrößen), pending_invites_mb (feste Größen offener Einladungen), pool_mb (was sich die Postfächer mit gemeinsamem Speicher teilen), used_bytes und member_ids.

Jeder Mitgliedsdatensatz enthält client_limit: das eine Limit, unter dem alle Domains des Mitglieds liegen, mit id, storage_limit_mb, allocated_mb und used_bytes, oder null. Für einen auf bestimmte Domains beschränkten Aufrufer ist es auch dann null, wenn dieses Limit eine Domain umfasst, auf die er keinen Zugriff hat.

Die eigene Größe eines Postfachs legen Sie mit PATCH /mailboxes/{id}/storage (mailboxes:write) oder dem Tool set_mailbox_storage fest; beides beschreibt die API-Übersicht.

MCP-Tools

Einladungs-Tools erfordern TREKMAIL_ALLOW_SENDING=true bei selbst gehostetem stdio-MCP. Tools, die Zugriffe ändern, und die Tools für Speicherlimits für Kunden erfordern TREKMAIL_ALLOW_DESTRUCTIVE=true. Für das Entfernen eines Mitglieds oder eines Limits ist außerdem confirm_remove=true erforderlich. set_mailbox_storage gehört nicht zum White-Label-Toolset, hat aber dieselbe Sperre. 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