API-scopes en abonnementsmachtigingen

Scopes bepalen precies wat een API-token kan doen. Elk token bevat een set scopes en de API controleert ze bij elk verzoek.

Hoe scopes werken

Wanneer je een token maakt, selecteer je de scopes die je wilt opnemen. De API past bij elk verzoek drie bovengrenzen toe:

Accountrechten: het huidige abonnement en actieve add-ons bepalen welke mogelijkheden op dat moment bestaan.
Lidmaatschap: iemand met gedelegeerde toegang kan niet meer verlenen of gebruiken dan de huidige rol en domeintoegang toestaan.
Toekenning aan referentie: het token of de OAuth-toestemming moet de vereiste scope van het endpoint bevatten.

De fout geeft aan welke bovengrens niet is gehaald. insufficient_scope betekent dat de scope nooit aan de referentie is toegekend, scope_blocked_by_membership betekent dat de rol van de persoon beperkter is en scope_blocked_by_entitlement betekent dat het vereiste White Label-recht niet actief is.

Twee scopelagen: OAuth- en API-scopes

OAuth ondersteunt zes handige verouderde bundels, alle fijnmazige API-scopes en tools:*-selectoren die alleen de zichtbaarheid regelen. De verouderde bundels zijn:

OAuth-scope	Omvat
`mail:read`	Account, domeinen, mailboxen, doorsturen, mailregels, automatisch antwoord, SMTP, Cloudflare en tickets lezen, plus Drive-leestoegang.
`mail:write`	Alles van `mail:read`, plus maken, bijwerken en verwijderen van domeinen, mailboxen, aliassen, doorsturen, mailregels, automatisch antwoord, Cloudflare-DNS, tickets, Drive-uploads en deellinks.
`mail:admin`	Alles van `mail:write`, plus facturering, verwijderintenties, definitieve Drive-verwijderingen, schrijfbewerkingen voor migraties, verwijderen van Cloudflare-tokens en uitgifte van berichtentokens.
`messages:read`	Mailboxinhoud lezen (berichten, mappen, bijlagen, contacten, agenda, identiteiten en sjablonen).
`messages:write`	Concepten, mappen, vlaggen, contacten, agenda's, sjablonen en instellingen wijzigen zonder mail te verzenden.
`messages:send`	Mail lezen en verzenden, inclusief het opstellen en plannen van berichten.

Elke verouderde OAuth-bundel wordt uitgebreid naar fijnmazige API-scopes, zoals domains:read en drive:account:write. Nieuwe integraties kunnen deze gedetailleerde scopes rechtstreeks aanvragen. White Label-scopes ontbreken bewust in de oudere mail:*-bundels, zodat een bestaande connector na een upgrade nooit vanzelf resellerbeheer krijgt. De vereiste White Label-scopes moeten expliciet worden aangevraagd. Een tools:white_label-selector beperkt de zichtbaarheid in MCP, maar verleent zelf geen API-machtiging.

Drie verbindingsmethoden en hoe ze mogelijkheden verlenen

Een agent of integratie kan TrekMail op drie manieren bereiken en het controlemechanisme verschilt per methode. Dit is belangrijk omdat de MCP-"mogelijkheidsvlaggen" (TREKMAIL_ALLOW_DESTRUCTIVE, TREKMAIL_ALLOW_SENDING, TREKMAIL_ALLOW_MIGRATION) slechts in één methode bestaan.

Modus	Verificatie	Controlemechanisme	Mogelijkheidsvlaggen	Bereik van tools/endpoints
Gehoste HTTP MCP (`https://trekmail.net/mcp`, OAuth)	OAuth 2.1 met verouderde bundels of fijnmazige scopes	Huidige rechten, lidmaatschap, toegestane scopes, geselecteerde toolsets en transportondersteuning.	Gehost veiligheidsbeleid	De subset die door elke actieve bovengrens wordt toegestaan
Zelfgehoste stdio MCP (`@trekmail/mcp-server`, lokaal)	Een `tm_live_`-token en, waar nodig, een `tm_msg_`-token	Tokenscopes, geselecteerde toolsets, alleen-lezenmodus en veiligheidsinstellingen van de beheerder. Niet-toegestane tools worden niet geregistreerd.	Configuratie van de beheerder	De subset die het token en de lokale configuratie toestaan
REST API rechtstreeks	Een bearer-token van het type `tm_live_` of `tm_msg_`	Fijnmazige tokenscopes, zoals `smtp:read`, `smtp:write` en `domains:delete`	Niet van toepassing	De endpoints die door de tokenscopes worden toegestaan

Kort samengevat: gehoste HTTP MCP filtert de aangeboden tools op basis van de OAuth-referentie; stdio MCP combineert tokenscopes met toolsets, alleen-lezenmodus en lokale veiligheidscontroles; de REST API wordt rechtstreeks beperkt door de fijnmazige scopes op het token. De API-autorisatie tijdens uitvoering blijft in elke modus doorslaggevend.

Scopereferentie

Account en facturering

Scope	Wat deze doet	Abonnementen
`account:read`	Accountgegevens, abonnement, limieten en gebruik bekijken	Starter · Pro · Agency
`billing:read`	Factureringsstatus en factuurgeschiedenis bekijken	Starter · Pro · Agency
`billing:autopay`	Aankopen namens jou betalen zonder elke keer toestemming te vragen	Elk abonnement, inclusief Nano

billing:autopay is de enige scope waarmee geld wordt uitgegeven, dus het is verstandig deze twee keer te lezen.

Deze scope is bewust gescheiden van billing:read: een verbinding die je factuur mag bekijken, mag deze niet kunnen verhogen, en facturering alleen-lezen verlenen is geen toestemming om geld uit te geven. De scope wordt nooit automatisch opgenomen, een token of verbinding heeft deze alleen als je hem expliciet hebt verleend, en hij ontbreekt in alle oudere brede scopebundels. Een verbinding die vóór het bestaan ervan is geautoriseerd, kan dus niets uitgeven.

Wat de scope toestaat: credits voor e-mailverificatie kopen en een abonnement starten. Wat de scope absoluut niet toestaat: een bestaand abonnement annuleren, downgraden of wijzigen. Daarvoor bestaan geen endpoints. Uitgaven zijn bovendien per aankoop, per dag en per maand begrensd voor het hele account, ongeacht hoeveel verbindingen de scope bezitten.

De scope is voor elk abonnement beschikbaar omdat verificatiecredits voor elk abonnement worden verkocht, inclusief Nano.

Domeinen

Scope	Wat deze doet	Abonnementen
`domains:read`	Domeinen weergeven en details, spamstatistieken, doorstuuradressen en domeinaliasstatus lezen	Starter · Pro · Agency
`domains:create`	Nieuwe domeinen aan het account toevoegen	Pro · Agency
`domains:write`	Domeinaliassen, catch-all, DKIM, notities en doorstuuradressen bijwerken en bepalen of het domein inkomende mail host of alleen verzendt	Pro · Agency
`domains:delete`	Domeinen verwijderen (gevaarlijk)	Pro · Agency
`domains:dns:read`	DNS-vereisten en controleresultaten bekijken	Starter · Pro · Agency
`domains:dns:recheck`	Een nieuwe DNS-controle starten	Pro · Agency

Bezorging via domeinalias is beschikbaar vanaf Starter. Starter-tokens kunnen de opgeslagen en actuele status lezen; verbinden, wijzigen of verwijderen via API/MCP vereist de Pro/Agency-mogelijkheid domains:write. Wijzigingen via het dashboard blijven beschikbaar met Starter. Zie Domeinaliassen via API en MCP.

White Label

Deze scopes voor bewerkingstokens verschijnen alleen zolang een White Label-proefperiode of betaalde add-on actief is. Tijdens de respijtperiode na opzegging behoudt de eigenaar de leesscopes; gedelegeerde leden en alle schrijfscopes worden verwijderd.

Scope	Wat deze doet	Beschikbaarheid
`branding:read`	Merken, middelen, hosts, mailzonestatus en vereiste DNS-records lezen	Actief recht; eigenaar tijdens respijtperiode
`branding:write`	Huisstijl configureren, middelen uploaden of verwijderen, voorbeelden maken en DNS controleren	Actief recht
`members:read`	Toegangscatalogus en White Label-klanten of teamleden lezen	Actief recht; eigenaar tijdens respijtperiode
`members:write`	Leden uitnodigen, bijwerken, schorsen, hervatten, verwijderen of herstellen	Actief recht
`activity:read`	White Label-activiteit van het account en per lid lezen	Actief recht; eigenaar tijdens respijtperiode

Het actuele lidmaatschap vormt nog een bovengrens. Een klant of teamgenoot kan de eigen rol, domeintoegang of aangepaste machtigingen nooit verruimen door een breder token te maken. Zie White Label-teams beheren met API en MCP.

Mailboxen

Scope	Wat deze doet	Abonnementen
`mailboxes:read`	Mailboxen weergeven/bekijken en wachtwoordvrije configuratiegegevens voor mailclients ophalen	Starter · Pro · Agency
`mailboxes:create`	Nieuwe mailboxen maken	Pro · Agency
`mailboxes:delete`	Mailboxen verwijderen (via verwijderintenties)	Pro · Agency
`mailboxes:invites:create`	Uitnodigingen voor mailboxconfiguratie verzenden	Pro · Agency
`mailboxes:forwarding:read`	Doorstuurconfiguratie bekijken	Starter · Pro · Agency
`mailboxes:write`	Wachtwoord wijzigen, notities bijwerken, pauzeren/hervatten, aanmelden schorsen/herstellen, Drive-toegang instellen	Pro · Agency
`mailboxes:forwarding:write`	Doorstuurregels maken en wijzigen	Pro · Agency
`mailboxes:rules:read`	Mailfilters bekijken	Starter · Pro · Agency
`mailboxes:rules:write`	Mailfilters maken, bijwerken en verwijderen	Pro · Agency
`mailboxes:auto-reply:read`	Instellingen voor automatisch antwoord bekijken	Starter · Pro · Agency
`mailboxes:auto-reply:write`	Instellingen voor automatisch antwoord bijwerken	Pro · Agency
`mailboxes:message-tokens:manage`	Berichtentokens maken, weergeven en intrekken	Pro · Agency

Berichten (berichtentoken)

Scope	Wat deze doet	Abonnementen
`messages:read`	Leestoegang tot de volledige webmailomgeving: berichten en mappen weergeven/lezen, bijlagen downloaden, ruwe bron ophalen, geplande berichten en contacten weergeven, contacten exporteren, agenda-items weergeven, antwoord-/doorstuurgegevens ophalen, identiteiten en brongebonden Verzenden als-routes van gekoppelde inboxen weergeven, sjablonen en geblokkeerde afzenders weergeven	Pro · Agency
`messages:write`	Schrijftoegang: vlaggen bijwerken, berichten verwijderen/verplaatsen, spam/ham melden, bulkacties, mappen maken/hernoemen/verwijderen, Prullenbak/Ongewenst leegmaken, concepten opslaan/bijwerken, geplande berichten annuleren, contacten, agenda-items, groepen, groepsleden, identiteiten, antwoordafzenderbeleid, sjablonen en geblokkeerde afzenders beheren	Pro · Agency
`messages:send`	E-mail verzenden vanuit de mailbox of een geautoriseerde brongebonden Verzenden als-identiteit; omvat ook het plannen van nieuwe berichten en annuleren van geplande verzendingen	Pro · Agency

Berichtscopes staan op berichtentokens (voorvoegsel tm_msg_) en niet op bewerkingstokens (voorvoegsel tm_live_). Berichtentokens worden via de API gemaakt met een bewerkingstoken met de scope mailboxes:message-tokens:manage. Naast de normale limieten voor verzenden hebben ze API-specifieke beveiligingen: standaard zijn 30 leesverzoeken per minuut en 5,000 geslaagde leesacties per dag per token toegestaan; verzenden staat 60 verzoeken per minuut per token en 100 API-verzendingen per dag voor de hele mailbox toe. Een tweede veiligheidsteller voor het token staat standaard op 500 verzendingen per dag, waardoor normaal de lagere mailboxlimiet geldt.

Alle nieuwe webmail-API-endpoints (contacten, agenda, identiteiten, sjablonen, geblokkeerde afzenders, concepten, geplande verzendingen, mappen, bijlagen) zijn gekoppeld aan de bestaande drie berichtscopes; er zijn geen nieuwe scopes toegevoegd. Bestaande tokens blijven zonder wijzigingen werken.

messages:read verleent geen schrijftoegang. In gehoste OAuth levert goedkeuring van de bredere mogelijkheid messages:send lees-, schrijf- en verzendtoegang samen; een handmatig gemaakt tm_msg_-token behoudt exact de scopes die bij het maken zijn geselecteerd.

Ondersteuningstickets

Scope	Wat deze doet	Abonnementen
`tickets:read`	Ondersteuningstickets en berichten weergeven en bekijken	Starter · Pro · Agency
`tickets:write`	Tickets maken, beantwoorden en sluiten	Pro · Agency

Starter: alleen-lezen via API. Open en beantwoord tickets via het dashboard.

SMTP-configuratie

Scope	Wat deze doet	Abonnementen
`smtp:read`	De SMTP-route van een domein bekijken, opgeslagen profielen en hun exacte domein-/Verzenden als-gebruik weergeven, de accountbrede standaard lezen, testtaken opvragen	Starter · Pro · Agency
`smtp:write`	De route van een domein instellen, profielen maken/bijwerken/verwijderen, de accountbrede standaard instellen, verbindingstests uitvoeren	Pro · Agency

SMTP wordt per domein geconfigureerd (/api/v1/domains/{id}/smtp), waarbij één accountbrede standaard (/api/v1/smtp/default) bepaalt waarmee nieuwe domeinen beginnen. Zie Overzicht van de API voor de volledige lijst met endpoints. De verouderde accountbrede endpoints van /api/v1/smtp blijven reageren voor compatibiliteit, maar bepalen de routering niet meer.

Migraties

Scope	Wat deze doet	Abonnementen
`migrations:read`	Migraties en migratiegegevens weergeven	Starter · Pro · Agency
`migrations:write`	Migraties starten, annuleren, opnieuw proberen en verwijderen	Pro · Agency

Migratiescopes staan op bewerkingstokens (voorvoegsel tm_live_). Starter kan migraties via de API bekijken en via het dashboard uitvoeren. Pro en Agency kunnen migraties ook via API en MCP starten, annuleren, opnieuw proberen en verwijderen.

Cloudflare

Scope	Wat deze doet	Abonnementen
`cloudflare:read`	Tokens valideren, zones weergeven, DNS-wijzigingen vooraf bekijken	Starter · Pro · Agency
`cloudflare:write`	Domeinen verbinden en DNS-wijzigingen toepassen via Cloudflare	Pro · Agency
`cloudflare:delete`	Cloudflare-tokens verwijderen (gevaarlijk)	Pro · Agency

Drive

Scope	Wat deze doet	Abonnementen
`drive:account:read`	Account Drive doorzoeken, metadata van mappen/bestanden/prullenbak/deellinks bekijken, download-URL's aanvragen	Betaalde abonnementen of actieve Drive-add-on
`drive:account:write`	Uploaden, mappen maken, hernoemen, verplaatsen, naar prullenbak verplaatsen en items in Account Drive herstellen	Betaalde abonnementen of actieve Drive-add-on
`drive:account:share`	Openbare deellinks voor bestanden in Account Drive maken, weergeven en intrekken	Betaalde abonnementen of actieve Drive-add-on
`drive:account:purge`	Bestanden/mappen in de prullenbak van Account Drive definitief verwijderen en prullenbak legen	Betaalde abonnementen of actieve Drive-add-on; hoog risico
`drive:mailbox:read`	Toegestane Drive-ruimtes van mailboxen doorzoeken	Betaalde abonnementen of actieve Drive-add-on
`drive:mailbox:write`	Bestanden/mappen uploaden en wijzigen in toegestane Drive-ruimtes van mailboxen	Betaalde abonnementen of actieve Drive-add-on
`drive:mailbox:share`	Openbare links voor Drive-bestanden van toegestane mailboxen maken, weergeven en intrekken	Betaalde abonnementen of actieve Drive-add-on
`drive:mailbox:purge`	Items in de prullenbak van mailbox-Drive definitief verwijderen	Betaalde abonnementen of actieve Drive-add-on; hoog risico
`drive:addon:read`	Status, prijzen en annuleringsvoorbeeld van de Drive Storage-add-on lezen	Nano · Starter · Pro · Agency wanneer add-on-/Drive-context bestaat
`drive:devices:read`	Wachtwoorden van synchronisatieapparaten weergeven zonder hun leesbare waarden te tonen	Betaalde abonnementen of actieve Drive-add-on
`drive:devices:write`	Wachtwoorden van synchronisatieapparaten maken, roteren en intrekken	Betaalde abonnementen of actieve Drive-add-on

Drive-scopes zijn scopes voor bewerkingstokens. Een token kan tot geselecteerde mailboxen worden beperkt en Drive verbergt andere mailboxruimtes voor dat token. Drive-add-on kopen, aanpassen en opzeggen zijn geen API/MCP-schrijfbewerkingen; factureringswijzigingen blijven in het dashboard.

Nano + Drive-add-on: met een actieve Drive Storage-add-on krijgt Nano de volledige set Drive-scopes. Er wordt niets anders ontgrendeld: alleen Drive, plus de scopes van E-mailverificatie die Nano al heeft. Als je de add-on opzegt, blijven leesscopes tijdens de respijtperiode van 7 dagen actief zodat je downloads of migratie kunt afronden; schrijven, delen en definitief verwijderen worden direct uitgeschakeld.

E-mailverificatie

Scope	Wat deze doet	Abonnementen
`verify:read`	Credits controleren, taken weergeven, taakstatus en resultaten bekijken	Nano · Starter · Pro · Agency
`verify:write`	Verificaties indienen, taken annuleren en verwijderen (verleent ook leestoegang)	Nano · Starter · Pro · Agency

Scopes voor E-mailverificatie zijn beschikbaar bij alle abonnementen, inclusief Nano. Alleen je creditsaldo vormt een beperking. Zie API voor E-mailverificatie voor de volledige endpointreferentie.

Toegangsniveaus van abonnementen

Abonnement	API-toegang	Beschikbare scopes
Nano	E-mailverificatie. Voeg een Drive Storage-add-on toe voor de volledige Drive API + MCP.	`verify:read`, `verify:write`. Met Drive-add-on: elke `drive:*`-scope.
Starter	Volledige Drive, volledige E-mailverificatie en alleen-lezen voor de rest. Voer schrijfbewerkingen voor het dashboard via het dashboard uit.	`account:read`, `billing:read`, `domains:read`, `domains:dns:read`, `mailboxes:read`, `mailboxes:forwarding:read`, `mailboxes:rules:read`, `mailboxes:auto-reply:read`, `migrations:read`, `tickets:read`, `smtp:read`, `cloudflare:read`, `verify:read`, `verify:write`, alle `drive:*`-scopes.
Pro	Volledige toegang	Alle bewerkingsscopes + Drive-scopes + berichtscopes + migratiescopes + tickets + SMTP + Cloudflare + account + facturering + verificatie
Agency	Volledige toegang	Alle bewerkingsscopes + Drive-scopes + berichtscopes + migratiescopes + tickets + SMTP + Cloudflare + account + facturering + verificatie

White Label-scopes zijn aanvullend en maken geen deel uit van het standaard Pro- of Agency-abonnement. Ze verschijnen alleen voor deze accounts zolang het White Label-recht actief is.

Wat gebeurt er bij een downgrade?

Als je van Pro naar Starter downgradet, worden bestaande tokens met schrijfscopes niet verwijderd. De API blokkeert in plaats daarvan tijdens uitvoering verzoeken die niet-toegestane scopes gebruiken.

Een token met mailboxes:create bij een Starter-abonnement ontvangt bijvoorbeeld 403 met de code token_scope_blocked_by_plan wanneer het een mailbox probeert te maken. De leesscopes van hetzelfde token blijven werken.

Trek het oude token in en maak een nieuw token met alleen de scopes die je huidige abonnement toestaat om dit op te lossen.

Gevaarlijke scopes

De scopes mailboxes:delete, domains:delete, migrations:write en cloudflare:delete worden in het dashboard als gevaarlijk gemarkeerd. Tokens met deze scopes kunnen mailbox- of domeinverwijdering starten, Cloudflare-tokens verwijderen of andere onomkeerbare acties uitvoeren. Overweeg of je toepassing ze werkelijk nodig heeft.

Voor een lokaal gehoste MCP-server kan de beheerder TREKMAIL_ALLOW_DESTRUCTIVE=true vereisen voordat verwijdertools beschikbaar zijn. Gehoste MCP gebruikt de scopes die tijdens OAuth zijn goedgekeurd.

De scope messages:send staat het verzenden van echte e-mail vanuit de mailbox toe. Bij een lokaal gehoste MCP-server kan verzenden ook TREKMAIL_ALLOW_SENDING=true en confirm_send=true bij elke aanroep vereisen. Zie Beveiligingen en verwijderintenties voor meer informatie.

De scope migrations:write staat het starten van e-mailmigraties toe die met opgeslagen referenties verbinding maken met externe IMAP-servers. Bij een lokaal gehoste MCP-server kunnen schrijfbewerkingen voor migraties ook TREKMAIL_ALLOW_MIGRATION=true en bevestigingsparameters per aanroep (confirm_start, confirm_cancel, confirm_retry) vereisen.

Domeinbeperkingen

Scopes bepalen wat een token kan doen. Domeinbeperkingen bepalen waar het dit kan doen.

Een token dat tot specifieke domeinen is beperkt, kan alleen bronnen binnen deze domeinen zien en wijzigen. Dit is handig om een externe medewerker of agent toegang te geven tot één klantdomein zonder andere domeinen zichtbaar te maken.

Scopecontroles vinden plaats vóór controles van domeinbeperkingen. Als een token de vereiste scope mist, mislukt het verzoek met 403, ongeacht de domeinbeperkingen.

Snelle oplossingen

403 "insufficient_scope": je token heeft de voor dit endpoint vereiste scope niet. Maak een nieuw token met de juiste scopes.
403 "token_scope_blocked_by_plan": je abonnement staat een of meer scopes van het token niet meer toe. Upgrade je abonnement of trek het token in en maak een nieuw token met toegestane scopes.
403 "scope_blocked_by_entitlement": White Label is niet actief of er is tijdens de respijtperiode na opzegging een schrijfbewerking geprobeerd. Activeer het opnieuw voordat je de verbinding opnieuw autoriseert.
403 "scope_blocked_by_membership": de huidige ledenrol of aangepaste machtiging staat de actie niet toe. Vraag de accounteigenaar om het lidmaatschap te wijzigen.
Sommige scopes zijn verborgen in het aanmaakformulier: je abonnement ondersteunt deze scopes niet. Alleen toegestane scopes worden getoond.