API-Token erstellen und verwalten

Öffne TrekMail in Claude, wähle Connect, melde dich an und erlaube den Zugriff. Du musst keinen API-Token erstellen. Prüfe Berechtigungen oder trenne die App unter KI-Agenten und API → Tokens → Verbundene Apps.

Deine eigene White-Label-Marke: verwende die MCP-Adresse aus deinem gebrandeten Dashboard und den Namen deiner Marke. Füge sie als custom connector hinzu; der öffentliche TrekMail-Eintrag meldet dich bei TrekMail an und ersetzt nicht die Verbindung deiner Marke.

API-Token steuern, was eine Anwendung oder ein Agent in Ihrem Konto tun kann. Jedes Token hat einen Namen, Berechtigungsumfänge, optionale Domain-Beschränkungen und ein Ablaufdatum.

Sie verbinden einen MCP-Client? Wenn er die Browser-Autorisierung unterstützt, fügen Sie https://trekmail.net/mcp als entfernten MCP-Server hinzu und genehmigen Sie den Zugriff im Browser. Normalerweise müssen Sie kein Token erstellen oder einfügen. Manuelle tm_live_-Token sind für Skripte, CI-Aufträge, selbst gehostete MCP-Server und Clients bestimmt, die diesen Ablauf nicht unterstützen. Siehe KI-Agenten verbinden (MCP).

E-Mails mit einem Schlüssel lesen

Wähle bei Pro und Agency beim Erstellen eines API-Schlüssels E-Mails lesen. Das ausdrückliche Recht lautet mailboxes:messages:read; mailboxes:read zeigt nur Adressen und Verbindungsdaten. Alle Postfächer schließt aktuelle und zukünftige Postfächer ein; alternativ kannst du bestimmte Domains und Postfächer auswählen. Bestehende Schlüssel erhalten keine neuen Rechte automatisch.

Verwende den Kontoschlüssel mit den GET-Routen unten. Senden, Löschen und andere Änderungen benötigen weiterhin separate Nachrichtenzugangsdaten und Rechte. Gehostetes MCP akzeptiert OAuth, keine tm_live_- oder tm_msg_-Schlüssel. Der Fehler zum Token-Typ nennt dem Agenten den passenden Endpunkt oder die Autorisierung.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

App-Rechte auswählen und bearbeiten

Öffne die Details eines API-Schlüssels oder einer verbundenen App, wähle Zugriff bearbeiten, prüfe die Änderungen und bestätige sie. Der geheime Schlüssel bleibt gleich. Weniger Rechte, Ressourcen oder Laufzeit beschränken auch vorhandene Postfach-Token und stoppen noch nicht begonnene Sendungen. Neue OAuth-Verbindungen lassen sich sofort einschränken; mehr Zugriff verlangt eine neue Freigabe. Eine alte Verbindung wird beim Bearbeiten getrennt, die Auswahl bleibt für die erneute Verbindung gespeichert. Nachrichten-Token können nur Rechte verlieren oder früher ablaufen.

Vorbereitungen

• Alle Tarife, einschließlich Nano, können API-Token erstellen. Nano-Tarife sind auf Berechtigungsumfänge für Email Verifier (verify:read, verify:write) beschränkt.
• Starter-Tarife erlauben schreibgeschützte Infrastruktur-Berechtigungen sowie vollständige Berechtigungen für Drive und Email Verifier. Starter kann Weiterleitungen auch im Dashboard verwalten, doch der API-Schreibzugriff für Weiterleitungen (mailboxes:forwarding:write) erfordert Pro oder Agency. Pro und Agency schalten alle Berechtigungen frei.
• Der Inhaber kann alle Zugangsdaten des Kontos verwalten. Ein delegiertes Mitglied mit der Berechtigung für API-Token kann nur selbst erstellte Zugangsdaten verwalten und nur Berechtigungen und Domains gewähren, die bereits in seiner Mitgliedschaft enthalten sind.
• Tipp: Klicken Sie auf der Seite KI-Agenten und API auf Tour starten, um einen kurzen Rundgang durch Verbindungsoptionen, Token, verbundene Apps und das Audit-Protokoll zu erhalten.

Ein Drive-Automatisierungs-Token erstellen

Die Drive-API und MCP-Tools verwenden Betriebs-Token (tm_live_...). Wählen Sie nur die Drive-Berechtigungen aus, die der Arbeitsablauf benötigt:

• Schreibgeschützte Berichte: drive:account:read, drive:mailbox:read oder drive:addon:read.
• Upload-Automatisierung: Fügen Sie drive:account:write oder drive:mailbox:write hinzu.
• Öffentliche Bereitstellungslinks: Fügen Sie drive:account:share oder drive:mailbox:share hinzu.
• Endgültige Bereinigung: Verwenden Sie drive:account:purge oder drive:mailbox:purge nur in einem separaten, streng kontrollierten Token.

Kauf, Größenänderung und Kündigung des Drive-Add-ons sind nicht über API-Token möglich. Agenten können den Add-on-Status und die Preise mit drive:addon:read auslesen, Abonnementänderungen bleiben jedoch im Dashboard.

Ein White-Label-Automatisierungs-Token erstellen

White Label verwendet fünf Berechtigungsumfänge für Betriebs-Token: branding:read, branding:write, members:read, members:write und activity:read. Sie werden nur angezeigt, solange das Konto Zugriff auf White Label hat. members:write ist als gefährlich gekennzeichnet, da es Zugriffe entfernen und die Schlüssel einer anderen Person widerrufen kann.

Wählen Sie für eine schreibgeschützte Status- und Audit-Integration branding:read, members:read und activity:read. Fügen Sie branding:write nur für die Marken- und DNS-Einrichtung hinzu. Fügen Sie members:write nur hinzu, wenn die Automatisierung Personen einladen oder ändern muss.

Während der Kündigungsfrist behält der Inhaber die drei Leseberechtigungen für die Wiederherstellung, während Schreibvorgänge und delegierte White-Label-Zugangsdaten nicht mehr funktionieren. Durch die Reaktivierung werden widerrufene Zugangsdaten nicht wieder gültig; erstellen oder autorisieren Sie neue.

Ein Token erstellen

1. Öffnen Sie KI-Agenten und API → Token.
2. Klicken Sie auf Token erstellen.
3. Füllen Sie das Formular aus:
   • Name: Eine Bezeichnung zur Identifizierung des Tokens (zum Beispiel „Claude-Agent“, „CI/CD-Pipeline“).
   • Ablauf: Wählen Sie 7 Tage, 30 Tage, 90 Tage, ein benutzerdefiniertes Datum oder nie.
   • Berechtigungen: Wählen Sie aus, welche Vorgänge das Token ausführen darf. Alle zulässigen Berechtigungen sind standardmäßig ausgewählt.
   • Domain-Beschränkung: Wählen Sie „Alle Domains (aktuelle und zukünftige)“, „Nur ausgewählte Domains“ oder „Alle Domains (aktuelle und zukünftige) außer …“, um einzelne Domains auszuschließen.
4. Klicken Sie auf Token erstellen.

Nach der Erstellung wird das Klartext-Token einmal angezeigt. Kopieren Sie es sofort oder speichern Sie es über die Schaltfläche Herunterladen als .txt-Datei.

Das Token kann nicht erneut angezeigt werden. Speichern Sie es sicher, bevor Sie die Bestätigung schließen.

Ein Nachrichten-Token erstellen

Nachrichten-Token ermöglichen Agenten, E-Mails aus einem bestimmten Postfach zu lesen und zu senden. Sie sind von Betriebs-Token getrennt und werden programmgesteuert über die API mit Ihrem Betriebs-Token erstellt.

Zum Erstellen eines Nachrichten-Tokens ruft Ihr Agent Folgendes auf:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

Wählen Sie die kleinsten Berechtigungen aus, die der Arbeitsablauf benötigt:

Das Klartext-Token (tm_msg_...) wird einmal zurückgegeben. Fügen Sie es Ihrer MCP-Konfiguration als TREKMAIL_MESSAGE_TOKEN hinzu.

Nachrichten-Token sind in den Tarifen Pro und Agency verfügbar. Das Betriebs-Token muss den Berechtigungsumfang mailboxes:message-tokens:manage besitzen.

Verwenden Sie für ein verbundenes Gmail- oder anderes externes Postfach external_account_id. Damit Empfänger stattdessen eine autorisierte Geschäftsadresse sehen, verwenden Sie zusätzlich eine vom Identitäten-Endpoint zurückgegebene identity_id. Siehe Senden-als-Adressen über API und MCP.

Token-Format

TrekMail verwendet zwei Token-Präfixe, um die Token-Arten zu unterscheiden:

Die ersten 8 Zeichen nach dem Präfix werden zur einfachen Identifizierung als sichtbares Präfix im Dashboard gespeichert.

Berechtigungsumfänge

Berechtigungsumfänge steuern, was das Token tun kann. Die verfügbaren Optionen hängen von Ihrem Tarif ab:

• Nano: Nur Email Verifier (verify:read, verify:write). Durch das Hinzufügen von Drive Storage erhält das Konto auch die Drive-API- und MCP-Funktionen, zu deren Nutzung es berechtigt ist.
• Starter: Vollständiger Zugriff auf Drive und Email Verifier sowie schreibgeschützter Zugriff auf alles andere (Domains, Postfächer, Weiterleitung, E-Mail-Filter, automatische Antworten, Migrationen, Tickets, SMTP, Cloudflare). Verwenden Sie das Dashboard für Schreibaktionen, die Starter nicht über die API bereitstellt, etwa zum Erstellen von Migrationen, Beantworten von Tickets oder Ändern automatischer Antworten.
• Pro und Agency: Vollständiger Zugriff. Lesen, Schreiben, Erstellen und Löschen in allen Familien sowie Nachrichten-Token für das Lesen und Senden von E-Mails über die API.

White-Label-Berechtigungen sind eine Add-on-Berechtigung und keine Abkürzung durch die Tarifübersicht. Sie werden nur angeboten, wenn White Label aktiv ist. Der Inhaber behält während der Kündigungsfrist einen schreibgeschützten Wiederherstellungszugriff.

Die einzelnen Berechtigungen finden Sie unter API-Berechtigungen und Tarifrechte.

Domain-Beschränkungen

Standardmäßig können Token auf alle Domains Ihres Kontos zugreifen, auch auf später hinzugefügte. Zwei Optionen schränken das ein:

• Nur ausgewählte Domains: Das Token erreicht die markierten Domains und sonst nichts. Eine später hinzugefügte Domain bleibt außen vor, bis Sie das Token bearbeiten und sie markieren.
• Alle Domains (aktuelle und zukünftige) außer …: Das Token erreicht alle Domains außer den markierten, auch später hinzugefügte. So halten Sie Ihre Agenten von den E-Mails eines Kunden fern, ohne das Token bei jeder neuen Domain anzupassen.

Ein beschränktes Token erhält beim Zugriff auf Ressourcen anderer Domains 404-Antworten; die API verhält sich so, als würden diese Domains nicht existieren. In beiden Fällen kann das Token auch keine kontoweiten Einstellungen ändern, die Domains außerhalb seiner Reichweite betreffen würden, etwa die Vorgabe für neue Postfächer.

Für ein Teammitglied, das auf einige Domains beschränkt ist, bedeutet „außer …“ die eigenen Domains ohne die markierten; später zum Konto hinzugefügte Domains gehören nicht dazu. Wenn Sie eine ausgeschlossene Domain löschen und erneut hinzufügen, gilt sie als neue Domain: Schließen Sie sie wieder aus.

Ein Token neu generieren

Generieren Sie ein Token neu, wenn Sie sein Secret erneut brauchen oder das Secret in falsche Hände geraten sein könnte. Das Token behält Namen, Berechtigungen, Domains, Postfächer, Ablaufdatum und Audit-Verlauf. Nur das Secret ändert sich.

1. Öffnen Sie KI-Agenten und API → Token und dort die Details des Tokens.
2. Klicken Sie auf Neu generieren.
3. Wählen Sie, wann das alte Secret ungültig wird: Sofort, In 1 Stunde, In 24 Stunden, In 3 Tagen oder In 7 Tagen. Das alte Secret gilt nie länger als das Token selbst.
4. Klicken Sie auf Neu generieren und kopieren Sie das neue Secret. Wie bei einem neuen Token wird es nur einmal angezeigt.

Solange das alte Secret noch gilt, zeigen die Details des Tokens, wann es ungültig wird, und bieten Jetzt deaktivieren an. Ersetzen Sie das Secret bis dahin in jeder App: Anfragen mit dem alten Secret erhalten danach 401 Unauthorized.

Nachrichten-Token (tm_msg_...), die mit dem alten Secret erstellt wurden, werden zur gleichen Zeit ungültig. Eine App, die ihre Nachrichten-Token selbst erstellt, kann mit dem neuen Secret neue erstellen. Wenn das Secret in falsche Hände geraten sein könnte, wählen Sie Sofort.

Ein Token widerrufen

1. Öffnen Sie KI-Agenten und API → Token.
2. Suchen Sie das Token in der Liste.
3. Klicken Sie auf Widerrufen.
4. Bestätigen Sie den Widerruf.

Widerrufene Token funktionieren sofort nicht mehr. Jede API-Anfrage mit einem widerrufenen Token erhält 401 Unauthorized.

Der Widerruf ist endgültig und kann nicht rückgängig gemacht werden. Erstellen Sie ein neues Token, wenn Sie den Zugriff wiederherstellen müssen.

Token-Status

Token haben drei Zustände:

Verwenden Sie auf der Token-Seite den Statusfilter, um Token nach ihrem Zustand anzuzeigen.

Audit-Protokoll

Jede Erstellung, Neugenerierung und jeder Widerruf eines Tokens wird auf der Registerkarte Audit-Protokoll angezeigt. Die Ereignisse enthalten Token-Name, Aktion und Zeitpunkt.

Schnelle Lösungen

• „Berechtigungen in Ihrem Tarif nicht verfügbar“: Ihr Tarif enthält diese Berechtigungen nicht. Nano bleibt auf verify:read und verify:write beschränkt (fügen Sie ein Drive-Storage-Add-on hinzu, um außerdem die drive:*-Berechtigungen zu erhalten). Starter bietet Lesezugriff auf alle Infrastrukturfamilien sowie vollständigen Zugriff auf Drive und Email Verifier. Pro und Agency schalten Schreibzugriff überall frei.
• Klartext-Token verloren: Das Token kann nicht wiederhergestellt werden, aber Sie können es neu generieren: Öffnen Sie die Details, klicken Sie auf Neu generieren und kopieren Sie das neue Secret. Die Einstellungen des Tokens bleiben erhalten.
• Das Token funktioniert, gibt aber für einige Domains 404 zurück: Wahrscheinlich besitzt das Token eine Domain-Beschränkung. Öffnen Sie beim Token Details, wählen Sie Zugriff bearbeiten und fügen Sie die fehlenden Domains hinzu, oder wechseln Sie zu „Alle Domains (aktuelle und zukünftige)“ oder „Alle Domains (aktuelle und zukünftige) außer …“.
• White-Label-Berechtigung gibt scope_blocked_by_entitlement zurück: Reaktivieren Sie White Label und erstellen oder autorisieren Sie anschließend Zugangsdaten mit der erforderlichen Berechtigung.
• Ein delegiertes Token funktioniert nach einer Rollenänderung nicht mehr: Eingeschränkter, gesperrter oder entfernter Mitgliedszugriff widerruft betroffene Zugangsdaten sofort. Erstellen Sie ein neues Token, nachdem der Inhaber den richtigen Zugriff wiederhergestellt hat.