API-Token erstellen und verwalten

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).

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“ oder bestimmte Domains aus, um den Zugriff des Tokens einzuschränken.
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. So beschränken Sie ein Token auf bestimmte Domains:

1. Wählen Sie im Bereich für Domain-Beschränkungen Ausgewählte Domains aus.
2. Markieren Sie die Domains, auf die das Token zugreifen soll.

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.

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 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. Widerrufen Sie es und erstellen Sie ein neues.
• Das Token funktioniert, gibt aber für einige Domains 404 zurück: Wahrscheinlich besitzt das Token eine Domain-Beschränkung. Widerrufen Sie es und erstellen Sie es mit „Alle Domains“ neu oder fügen Sie die fehlenden Domains zur Beschränkung hinzu.
• 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.