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, opslaglimieten van klanten 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 284 tools via stdio en maximaal 283 tools via gehoste HTTP. White Label levert 23 tools: zeven voor branding, 13 voor account-, leden- en activiteitenbeheer en drie voor opslaglimieten van klanten.

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.

Opslaglimieten van klanten

Een opslaglimiet voor een klant geeft de domeinen van die klant één hoeveelheid ruimte, in MB, voor hun mailboxen en Drive. Hoe dit in het dashboard werkt, lees je in Een eigen opslaglimiet voor elke klant. Een limiet waarvan niemand in het team de domeinen heeft, bijvoorbeeld een die hier is gemaakt voordat de klant is uitgenodigd, staat op de pagina Team en klanten onder Opslaglimieten zonder klant.

• Lezen vraagt members:read. Een aanroeper die beperkt is tot bepaalde domeinen, ziet alleen de limieten die uitsluitend voor zijn eigen domeinen gelden. De limiet van een andere klant, of een limiet die ook geldt voor een domein dat hij niet bereikt, staat niet in de lijst en geeft 404 terug, net als een ID die niet bestaat.
• Wijzigen vraagt members:write en een aanroeper die alle domeinen van het account bereikt. Een lid dat beperkt is tot bepaalde domeinen, krijgt 403 scope_blocked_by_membership; een sleutel die beperkt is tot bepaalde domeinen, krijgt 403 token_resource_constrained.
• POST werkt zoals de pagina Team en klanten: domeinen zonder limiet krijgen een nieuwe (201); delen de domeinen al een limiet, dan verandert die limiet en sluiten de opgegeven domeinen zonder limiet zich erbij aan (200).
• PATCH accepteert storage_limit_mb, domain_ids of beide. domain_ids vervangt de volledige set, en weggelaten domeinen gebruiken weer de opslag van het account.
• Elke limiet geeft storage_limit_mb, domain_ids, allocated_mb (vaste mailboxgroottes), pending_invites_mb (vaste groottes van openstaande uitnodigingen), pool_mb (wat mailboxen met gedeelde opslag samen delen), used_bytes en member_ids terug.

Elk ledenrecord bevat client_limit: de ene limiet waar alle domeinen van het lid onder vallen, met id, storage_limit_mb, allocated_mb en used_bytes, of null. Voor een aanroeper die beperkt is tot bepaalde domeinen, is het veld eveneens null als die limiet ook geldt voor een domein dat hij niet bereikt.

De eigen grootte van een mailbox stel je in met PATCH /mailboxes/{id}/storage (mailboxes:write) of de tool set_mailbox_storage, beschreven in het overzicht van de REST API.

MCP-tools

Uitnodigingstools vereisen TREKMAIL_ALLOW_SENDING=true op zelfgehoste stdio-MCP. Tools die toegang wijzigen en de tools voor opslaglimieten van klanten vereisen TREKMAIL_ALLOW_DESTRUCTIVE=true; een lid of een limiet verwijderen vereist ook confirm_remove=true. set_mailbox_storage hoort niet bij de White Label-toolset, maar heeft dezelfde vereiste. 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