API-Bereiche und Tarifberechtigungen

Bereiche steuern genau, was ein API-Token tun kann. Jedes Token enthält mehrere Bereiche, die von der API bei jeder Anfrage geprüft werden.

Funktionsweise von Bereichen

Beim Erstellen eines Tokens wählen Sie die enthaltenen Bereiche aus. Die API wendet bei jeder Anfrage drei Obergrenzen an:

1. Kontoberechtigung: Der aktuelle Tarif und aktive Add-ons bestimmen, welche Funktionen derzeit verfügbar sind.
2. Mitgliedschaft: Eine bevollmächtigte Person kann nicht mehr gewähren oder nutzen, als ihre aktuelle Rolle und ihr Domainzugriff erlauben.
3. Anmeldedatenfreigabe: Das Token oder die OAuth-Zustimmung muss den für den Endpunkt erforderlichen Bereich enthalten.

Der Fehler bezeichnet die überschrittene Grenze. insufficient_scope bedeutet, dass der Bereich den Anmeldedaten nie gewährt wurde, scope_blocked_by_membership bedeutet, dass die Rolle der Person enger gefasst ist, und scope_blocked_by_entitlement bedeutet, dass die erforderliche White Label-Berechtigung nicht aktiv ist.

Zwei Bereichsebenen: OAuth und API-Bereiche

OAuth unterstützt sechs ältere Komfortpakete, jeden detaillierten API-Bereich und die rein für die Sichtbarkeit bestimmten tools:*-Selektoren. Die älteren Pakete sind:

Jedes ältere OAuth-Paket wird in detaillierte API-Bereiche wie domains:read und drive:account:write erweitert. Neue Integrationen können diese granularen Bereiche direkt anfordern. White Label-Bereiche fehlen bewusst in den älteren mail:*-Paketen, damit ein vorhandener Connector nach einem Upgrade niemals automatisch die Reseller-Verwaltung erhält. Er muss die erforderlichen White Label-Bereiche ausdrücklich anfordern. Ein tools:white_label-Selektor begrenzt die MCP-Sichtbarkeit, gewährt allein aber keine API-Berechtigung.

Drei Verbindungsarten und ihre Berechtigungen

Ein Agent oder eine Integration kann TrekMail auf drei Arten erreichen, und der Kontrollmechanismus ist jeweils unterschiedlich. Das ist wichtig, weil die MCP-"Funktionsschalter" (TREKMAIL_ALLOW_DESTRUCTIVE, TREKMAIL_ALLOW_SENDING, TREKMAIL_ALLOW_MIGRATION) nur in einer davon vorkommen.

Kurz gesagt: Gehostetes HTTP-MCP filtert seine angebotenen Tools anhand der OAuth-Anmeldedaten; stdio-MCP bildet die Schnittmenge aus Tokenbereichen, Toolsets, Nur-Lese-Modus und lokalen Sicherheitsregeln; die REST-API wird direkt durch die granularen Bereiche des Tokens kontrolliert. Die API-Autorisierung zur Laufzeit bleibt in jedem Modus maßgeblich.

Bereichsreferenz

Konto und Abrechnung

billing:autopay ist der einzige Bereich, der Geld bewegt, daher lohnt es sich, ihn zweimal zu lesen.

Er ist bewusst von billing:read getrennt: Eine Verbindung, die Ihre Rechnung sehen darf, darf sie nicht erhöhen können, und ein Nur-Lese-Zugriff auf die Abrechnung ist keine Zustimmung zu Ausgaben. Er wird niemals automatisch eingeschlossen. Ein Token oder eine Verbindung besitzt ihn nur, wenn Sie ihn ausdrücklich gewährt haben, und er fehlt in jedem der älteren groben Bereichspakete. Eine Verbindung, die vor seiner Einführung autorisiert wurde, kann daher nichts ausgeben.

Er erlaubt den Kauf von E-Mail-Verifizierungsguthaben und den Start eines Abonnements. Er erlaubt keinesfalls die Kündigung, Herabstufung oder Änderung eines bestehenden Abonnements. Dafür gibt es keinen Endpunkt. Ausgaben werden für das gesamte Konto außerdem pro Kauf, Tag und Monat begrenzt, unabhängig davon, wie viele Verbindungen diesen Bereich besitzen.

Er ist in jedem Tarif verfügbar, weil Verifizierungsguthaben in allen Tarifen einschließlich Nano verkauft werden.

Domains

Die Zustellung über Domainaliase beginnt bereits bei Starter. Starter-Tokens können den gespeicherten und aktuellen Status lesen. Das Verbinden, Ändern oder Entfernen per API/MCP erfordert die Pro/Agency-Funktion domains:write. Änderungen im Dashboard bleiben bei Starter verfügbar. Siehe Domainaliase über API und MCP.

White Label

Diese Bereiche für Betriebsteile sind nur verfügbar, solange ein White Label-Testzeitraum oder ein kostenpflichtiges Add-on aktiv ist. Während der Kündigungsfrist behält der Inhaber die Lesebereiche. Bevollmächtigte Mitglieder und alle Schreibbereiche werden entfernt.

Die aktuelle Mitgliedschaft setzt eine weitere Grenze. Ein Kunde oder Teammitglied kann die eigene Rolle, den Domainzugriff oder benutzerdefinierte Berechtigungen niemals durch ein umfassenderes Token erweitern. Siehe White Label-Teams mit API und MCP verwalten.

Postfächer

Nachrichten (Nachrichtentoken)

Nachrichtenbereiche werden von Nachrichtentokens (Präfix tm_msg_) getragen, nicht von Betriebselementen (Präfix tm_live_). Nachrichtentokens werden über die API mit einem Betriebselement erstellt, das den Bereich mailboxes:message-tokens:manage besitzt. Zusätzlich zu den normalen Limits der Senderoute gelten API-spezifische Schutzmaßnahmen: Standardmäßig sind beim Lesen 30 Anfragen pro Minute und 5,000 erfolgreiche Lesevorgänge pro Tag und Token erlaubt. Beim Senden sind es 60 Anfragen pro Minute und Token sowie 100 API-Sendungen pro Tag im gesamten Postfach. Ein zweiter Sicherheitszähler ist standardmäßig auf 500 Sendungen pro Tag eingestellt, sodass normalerweise das niedrigere Postfachlimit gilt.

Alle neuen Webmail-API-Endpunkte (Kontakte, Kalender, Identitäten, Vorlagen, blockierte Absender, Entwürfe, geplanter Versand, Ordner, Anhänge) werden den bestehenden drei Nachrichtenbereichen zugeordnet. Es wurden keine neuen Bereiche hinzugefügt. Vorhandene Tokens funktionieren unverändert weiter.

messages:read gewährt keinen Schreibzugriff. Bei gehostetem OAuth stellt die Genehmigung der umfassenderen Funktion messages:send Lese-, Schreib- und Sendezugriff gemeinsam bereit. Ein manuell erstelltes tm_msg_-Token behält genau die bei der Erstellung ausgewählten Bereiche.

Support-Tickets

Starter: Nur-Lese-Zugriff über API. Öffnen und beantworten Sie Tickets im Dashboard.

SMTP-Konfiguration

SMTP wird pro Domain (/api/v1/domains/{id}/smtp) konfiguriert. Ein einziger kontoweiter Standard (/api/v1/smtp/default) bestimmt die Ausgangskonfiguration neuer Domains. Die vollständige Endpunktliste finden Sie in der API-Übersicht. Die älteren Endpunkte auf Kontoebene unter /api/v1/smtp antworten aus Kompatibilitätsgründen weiterhin, steuern das Routing aber nicht mehr.

Migrationen

Migrationsbereiche werden von Betriebselementen (Präfix tm_live_) getragen. Starter kann Migrationen über die API anzeigen und im Dashboard ausführen. Pro und Agency können Migrationen außerdem über API und MCP starten, abbrechen, wiederholen und löschen.

Cloudflare

Drive

Drive-Bereiche sind Bereiche für Betriebselemente. Ein Token kann auf ausgewählte Postfächer begrenzt werden, und Drive verbirgt andere Postfachbereiche vor diesem Token. Kauf, Größenänderung und Kündigung des Drive-Add-ons sind keine API/MCP-Schreibvorgänge. Abrechnungsänderungen bleiben im Dashboard.

Nano + Drive-Add-on: Mit einem aktiven Drive Storage-Add-on erhält Nano den vollständigen Satz von Drive-Bereichen. Nichts anderes wird freigeschaltet, nur Drive und die bereits vorhandenen Email Verifier-Bereiche. Wenn Sie das Add-on kündigen, bleiben Lesebereiche während der 7-tägigen Frist aktiv, damit Sie Downloads oder den Umstieg abschließen können. Schreiben, Freigeben und Bereinigen werden sofort abgeschaltet.

Email Verifier

Email Verifier-Bereiche sind in allen Tarifen einschließlich Nano verfügbar. Die einzige Begrenzung ist Ihr Guthaben. Die vollständige Endpunktreferenz finden Sie unter Email Verifier-API.

Zugriffsstufen der Tarife

White Label-Bereiche werden zusätzlich gewährt und sind nicht Teil des Pro- oder Agency-Basistarifs. Sie erscheinen für diese Konten nur, solange ihre White Label-Berechtigung aktiv ist.

Folgen einer Herabstufung

Wenn Sie von Pro auf Starter herabstufen, werden vorhandene Tokens mit Schreibbereichen nicht gelöscht. Stattdessen blockiert die API zur Laufzeit Anfragen mit nicht erlaubten Bereichen.

Beispielsweise erhält ein Token mit mailboxes:create im Starter-Tarif beim Erstellen eines Postfachs 403 mit dem Code token_scope_blocked_by_plan. Die Lesebereiche desselben Tokens funktionieren weiterhin.

Widerrufen Sie zur Behebung das alte Token und erstellen Sie ein neues, das nur die im aktuellen Tarif erlaubten Bereiche enthält.

Gefährliche Bereiche

Die Bereiche mailboxes:delete, domains:delete, migrations:write und cloudflare:delete sind im Dashboard als gefährlich gekennzeichnet. Tokens mit diesen Bereichen können das Löschen von Postfächern oder Domains einleiten, Cloudflare-Tokens entfernen oder andere unumkehrbare Aktionen ausführen. Prüfen Sie, ob Ihr Anwendungsfall sie wirklich benötigt.

Bei einem lokal gehosteten MCP-Server kann der Administrator TREKMAIL_ALLOW_DESTRUCTIVE=true verlangen, bevor Löschtools verfügbar werden. Gehostetes MCP verwendet die während OAuth genehmigten Bereiche.

Der Bereich messages:send erlaubt den Versand echter E-Mails aus dem Postfach. Bei einem lokal gehosteten MCP-Server kann das Senden zusätzlich TREKMAIL_ALLOW_SENDING=true und confirm_send=true bei jedem Aufruf erfordern. Einzelheiten finden Sie unter Sicherheitsregeln und Löschabsichten.

Der Bereich migrations:write erlaubt das Starten von E-Mail-Migrationen, die sich mit gespeicherten Anmeldedaten zu externen IMAP-Servern verbinden. Bei einem lokal gehosteten MCP-Server können Migrationsschreibvorgänge außerdem TREKMAIL_ALLOW_MIGRATION=true und Bestätigungsparameter pro Aufruf (confirm_start, confirm_cancel, confirm_retry) erfordern.

Domainbeschränkungen

Bereiche steuern, was ein Token tun kann. Domainbeschränkungen steuern, wo es dies tun kann.

Ein auf bestimmte Domains beschränktes Token sieht und ändert nur Ressourcen innerhalb dieser Domains. So können Sie einem Auftragnehmer oder Agenten Zugriff auf eine einzelne Kundendomain geben, ohne andere offenzulegen.

Bereichsprüfungen finden vor Prüfungen der Domainbeschränkung statt. Fehlt einem Token der erforderliche Bereich, schlägt die Anfrage unabhängig von Domainbeschränkungen mit 403 fehl.

Schnelle Lösungen

• 403 "insufficient_scope": Ihr Token besitzt nicht den für diesen Endpunkt erforderlichen Bereich. Erstellen Sie ein neues Token mit den richtigen Bereichen.
• 403 "token_scope_blocked_by_plan": Ihr Tarif erlaubt einen oder mehrere Tokenbereiche nicht mehr. Wechseln Sie den Tarif oder widerrufen Sie das Token und erstellen Sie ein neues mit erlaubten Bereichen.
• 403 "scope_blocked_by_entitlement": White Label ist inaktiv oder während der Kündigungsfrist wurde ein Schreibvorgang versucht. Reaktivieren Sie es, bevor Sie die Verbindung erneut autorisieren.
• 403 "scope_blocked_by_membership": Die aktuelle Mitgliedsrolle oder benutzerdefinierte Berechtigung erlaubt die Aktion nicht. Bitten Sie den Kontoinhaber, die Mitgliedschaft zu ändern.
• Einige Bereiche sind im Erstellungsformular ausgeblendet: Ihr Tarif unterstützt diese Bereiche nicht. Nur erlaubte Bereiche werden angezeigt.