White Label-teams beheren met API en MCP

White Label-accounts kunnen worden beheerd zonder terug te gaan naar het dashboard. De REST API en MCP-server omvatten de configuratiestatus van het account, klanten en teamleden, rollen, domeintoegang, uitnodigingen, schorsingen, verwijderingen, herstelacties en de activiteitengeschiedenis. Branding valt onder dezelfde White Label-toolset en heeft een eigen brandinghandleiding.

De belangrijke grens is eenvoudig: een verbinding kan nooit meer toegang uitdelen dan de persoon erachter al heeft. Een beheerder die tot bepaalde domeinen is beperkt, kan niemand uitnodigen voor andere domeinen. Een aangepaste rol kan geen machtigingen verlenen die de aanroeper niet bezit.

Wat er beschikbaar is

De volledige MCP-catalogus bevat nu 261 tools via stdio en maximaal 260 tools via gehoste HTTP. White Label levert 20 tools: zeven voor branding en 13 voor account-, leden- en activiteitenbeheer.

Deze tools worden niet voor iedereen geladen. TrekMail beoordeelt het actuele White Label-recht van het account, het huidige lidmaatschap van de persoon, het token of de OAuth-toekenning, eventuele domeinbeperkingen, de geselecteerde toolsets en lokale veiligheidsinstellingen voordat tools/list wordt opgebouwd. Een verbinding zonder White Label-toegang ontvangt helemaal geen schema's.

Rechtstatussen

Roep met leestoegang tot White Label GET /api/v1/white-label of de tool get_white_label aan om active te onderscheiden van de alleen-lezen status grace, en om de configuratievoortgang en de deadline van de respijtperiode te bekijken. Een niet-beschikbaar account kan dit endpoint niet aanroepen: wanneer opgeslagen inloggegevens nog steeds een White Label-scope bevatten die het account niet meer kan gebruiken, retourneert de API scope_blocked_by_entitlement en wordt uitgelegd waar deze opnieuw kan worden geactiveerd.

Scopes

Het endpoint voor ledenactiviteit vereist zowel activity:read als members:read, omdat het antwoord naast activiteit ook een ledenrecord bevat. De gehoste OAuth-verbinding gebruikt de selector tools:white_label om deze toolfamilie aan te vragen; de effectieve REST-scopes blijven beperkt door het account en lidmaatschap.

Voeg voor een zelfgehoste MCP-server white_label toe aan TREKMAIL_TOOLSETS wanneer je een toestemmingslijst voor toolsets gebruikt. Schrijftools houden ook rekening met de hieronder beschreven lokale veiligheidscontroles.

REST-endpoints

Alle paden vallen onder https://trekmail.net/api/v1.

Elke schrijfactie in deze tabel vereist een Idempotency-Key-header. Als dezelfde aanvraag met dezelfde sleutel wordt herhaald, wordt het oorspronkelijke veilige resultaat geretourneerd. Eenmalige geheimen in een herhaling, zoals een uitnodigingstoken, worden verborgen. Hergebruik van een sleutel met een andere body retourneert idempotency_mismatch.

Lees eerst de toegangscatalogus

Codeer rolmachtigingen niet vast in een integratie. Roep de toegangscatalogus aan vóór een uitnodiging of toegangswijziging. De grantable-vlaggen weerspiegelen het huidige lidmaatschap van de aanroeper en kunnen veranderen wanneer de eigenaar dat lidmaatschap aanpast.

De rollen die momenteel voor nieuwe uitnodigingen worden aangeboden, zijn:

• client - beheert de toegewezen domeinen en mailboxen zonder de privérelatie van de reseller met TrekMail te zien.
• webmail_only - verschijnt in de teamlijst, maar ontvangt geen dashboardmachtigingen.
• domain_admin - beheert toegewezen domeinen en hun DNS, maar geen mailboxen.
• mailbox_operator - beheert mailboxen binnen toegewezen domeinen, maar niet de domeinen zelf.
• read_only - kan het toegestane accountgedeelte bekijken zonder het te wijzigen.
• custom - ontvangt alleen de machtigingen die in permissions staan.

Sommige rollen vereisen expliciete domain_ids; andere kunnen all_domains gebruiken. De toegangscatalogus vertelt welke regel van toepassing is. Als de aanroeper een ruimere rol, machtiging of domeinset probeert te verlenen, retourneert TrekMail scope_blocked_by_membership in plaats van de uitnodiging ongemerkt te beperken.

Een klant uitnodigen

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

Het antwoord bevat het lid, of de e-mailbezorging is geslaagd en een eenmalige uitnodigings-URL. Een bezorgprobleem verwijdert de uitnodiging niet: de eigenaar kan de URL kopiëren of de uitnodiging later opnieuw verzenden.

Lees voor een aangepaste rol grantable_permissions uit de toegangscatalogus en stuur de geselecteerde waarden in permissions. Er is minimaal één machtiging vereist.

De lidstatus volgen

Elk antwoord over een lid bevat allowed_operations. Gebruik die lijst in plaats van te gokken:

• Een openstaande uitnodiging kan worden bijgewerkt, geschorst, opnieuw verzonden of verwijderd.
• Een actief lid kan worden bijgewerkt, geschorst of verwijderd.
• Een geschorst lid kan worden bijgewerkt, hervat of verwijderd.
• Een verwijderd lid kan worden hersteld.
• De rij van de eigenaar is zichtbaar voor context, maar kan niet via deze endpoints worden gewijzigd.

De lijst wordt ook gefilterd voor de huidige aanroeper. Deze is leeg voor een alleen-lezen verbinding, voor het eigen lidmaatschap van de aanroeper en voor leden van wie de machtigingen ruimer zijn dan de aanroeper mag beheren.

Aanroepers kunnen zichzelf niet verwijderen of schorsen. Gedelegeerde aanroepers kunnen evenmin een lid beheren met ruimere toegang dan zijzelf. Ongeldige overgangen retourneren membership_state_conflict met een aanwijzing om het lid opnieuw te lezen.

Door iemand te schorsen of te verwijderen, worden de API- en mailboxsleutels ingetrokken die onder dat lidmaatschap zijn gemaakt. Het hervatten of herstellen van het lidmaatschap brengt die oude sleutels nooit terug; de persoon moet opnieuw verbinding maken of nieuwe inloggegevens aanmaken.

Grenzen voor activiteit en privacy

GET /white-label/activity retourneert uitnodigingen, rol- en domeinwijzigingen, schorsingen, verwijderingen, herstelacties en gerelateerde beveiligingsacties. Filter met action, member_id en per_page.

GET /white-label/members/{id}/activity combineert de accountacties van dat lid met recente aanmeldingen, waaronder tijdstip, IP-adres, globale locatie, browser, besturingssysteem en apparaattype. Deze route vereist bewust beide leesscopes. Aanroepers met domeinbeperkingen kunnen alleen leden opvragen die volledig binnen hun domeingrens vallen. Een ontoegankelijk lid wordt als 404 geretourneerd, zodat het endpoint niet onthult dat er een andere tenant of klant bestaat.

MCP-tools

Uitnodigingstools vereisen TREKMAIL_ALLOW_SENDING=true op zelfgehoste stdio-MCP. Tools die toegang wijzigen, vereisen TREKMAIL_ALLOW_DESTRUCTIVE=true; verwijdering vereist ook confirm_remove=true. Deze schakelaars zijn lokale veiligheidscontroles en geen extra API-machtigingen. Gehoste MCP past een eigen goedgekeurd veiligheidsbeleid toe.

De tools maken deterministische idempotentiesleutels wanneer je er geen opgeeft. Een eigen idempotency_key opgeven is nuttig wanneer een workflow mogelijk in een ander proces opnieuw wordt gestart.

Een veilige automatiseringsstroom

1. Roep get_white_label aan. Stop bij scope_blocked_by_entitlement; ga in een geslaagd grace-antwoord alleen door met leesacties.
2. Roep get_white_label_access_catalog onmiddellijk aan voordat je toegang verleent.
3. Geef het doellid weer of lees het voordat je het wijzigt.
4. Controleer allowed_operations, de beoogde rol, machtigingen en domein-ID's.
5. Gebruik een stabiele idempotentiesleutel voor de schrijfactie.
6. Lees het lid opnieuw en meld de resulterende status en effectieve machtigingen.
7. Controleer de White Label-activiteit wanneer je een auditrecord van de wijziging nodig hebt.

Fouten die aangeven wat je moet doen