App-Passwörter für Postfächer per API und MCP

Die REST-API und MCP können App-Passwörter eines regulären Postfachs auflisten, erstellen, ersetzen und widerrufen, seinen Anmeldemodus für Mail-Apps ändern und die Kontovorgabe für künftige Postfächer setzen. Diese Seite ist die Referenz für Integrationen. Anleitungen für Dashboard und Webmail finden Sie unter App-Passwörter für Ihre Mail-Geräte.

Ein App-Passwort ermöglicht den Zugriff über IMAP, SMTP auf den Ports 465 und 587, ManageSieve und CalDAV/CardDAV. Es öffnet niemals das neue Webmail oder das Dashboard. Klassisches Webmail meldet sich über IMAP an und akzeptiert App-Passwörter. Die Postfach-2FA schützt nur die Anmeldung im neuen Webmail; Mail-Apps und klassisches Webmail fragen nie nach ihrem Code.

Für diese Funktion gibt es keine zusätzliche Tarifbeschränkung für Postfächer. Die bestehenden API- und MCP-Tarifberechtigungen gelten weiterhin; siehe API-Berechtigungen und Tarife.

Authentifizierung, Berechtigungsbereiche und Mitgliedsrechte

Verwenden Sie bei REST-Anfragen unter /api/v1 ein Bearer-Token. JSON-Schreibanfragen verwenden Content-Type: application/json und den Header Idempotency-Key.

Die Berechtigung zum Setzen von Passwörtern wird zusätzlich zum API-Berechtigungsbereich des Tokens anhand der Rolle des Mitglieds geprüft. Dies gilt für Mitglieds-Token und von Mitgliedern autorisierte Konnektoren. Ein Token des Kontoinhabers benötigt keinen zusätzlichen Berechtigungsbereich zum Setzen von Passwörtern. Fehlt einem Mitglied die Berechtigung, wird 403 scope_blocked_by_membership zurückgegeben.

Gehostete OAuth-Konnektoren können die entsprechenden REST-Funktionsberechtigungen verwenden. Bei den älteren Bündeln liefert mail:read die Bereiche mailboxes:read und account:read; mail:write liefert zusätzlich mailboxes:write. Die Erweiterung der Berechtigungsbereiche hebt weder Mitgliedsrechte noch Regeln auf, die Aktionen auf den Kontoinhaber beschränken.

Die Tokenbeschränkungen domain_ids und mailbox_ids gelten auch für Sammelauswahlen. Die App-Passwort-Endpunkte und beide Modus-Endpunkte geben nach Authentifizierung und Middleware-Prüfungen 404 not_found zurück, solange die Funktion deaktiviert ist. Ein nicht zugängliches oder fehlendes Postfach liefert ebenfalls 404; deuten Sie daher nicht jede 404-Antwort als Hinweis auf den Funktionsstatus.

Endpunkte im Überblick

Die folgenden Pfade enthalten das Präfix /api/v1. {mailbox} ist die ID des regulären Postfachs; {id} ist die ID eines zugehörigen App-Passwort-Eintrags.

Alle Schreibanfragen dieser Tabelle erfordern Idempotency-Key. Der Passwort-Endpunkt ist ein bestehender administrativer Reset-Vorgang und vom Ersetzen eines App-Passworts getrennt.

App-Passwörter auflisten und Eintragsfelder verstehen

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

Die Antwort enthält auf oberster Ebene mailbox_id, client_auth_mode, limit, active_count und data, ein Array von Einträgen. limit beträgt 25 aktive Passwörter pro Postfach. Aktive Einträge erscheinen zuerst, die neuesten zuerst; widerrufene Einträge bleiben 90 Tage sichtbar. Keine Listenantwort enthält ein Passwort.

Jeder Eintrag enthält:

Öffentliche Widerrufsgründe sind revoked, rotated, mailbox_password_reset, mailbox_password_changed, login_suspended, converted_to_shared und mailbox_trashed. Die Liste schließt intern von der Plattform erzeugte Zugangsdaten aus.

Ein App-Passwort erstellen

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

name ist erforderlich: 1 bis 64 druckbare Zeichen. Folgen von Leerraumzeichen werden zu einem Leerzeichen zusammengefasst. Das Postfach muss regulär und aktiv sein, seine Anmeldung darf nicht gesperrt sein, und es muss weniger als 25 aktive App-Passwörter haben.

Die Antwort 201 enthält den vollständigen Eintrag unter data, ergänzt data.password und enthält message. Beispielsweise sind dies die Zugangsdatenfelder dieser Antwort:

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

Dieses Beispiel lässt die übrigen oben beschriebenen Eintragsfelder aus. Das Beispielpasswort dient nur der Veranschaulichung. Ein echtes Passwort besteht aus 16 erzeugten Kleinbuchstaben und wird ohne Leerzeichen zurückgegeben. Apps akzeptieren auch Leerzeichen und Großbuchstaben; zeigen Sie es in vier Gruppen zu je vier Zeichen an, wenn Sie es einem Benutzer präsentieren.

Das Passwort wird nur einmal zurückgegeben. Halten Sie es aus Anwendungsprotokollen heraus. Der Benutzer gibt es direkt in der Mail-App ein und verwendet seine vollständige Postfachadresse als Benutzernamen. Erstellung und Ersetzen senden eine Benachrichtigung mit dem Namen des App-Passworts an das Postfach und, falls eingerichtet, dessen Wiederherstellungsadresse, ohne das Passwort selbst. Die Ausnahme ist das erste App-Passwort, das mit einem neuen Postfach ausgegeben wird (siehe unten).

Verwenden Sie die API zur Mailclient-Einrichtung für die Verbindungseinstellungen. Ein heruntergeladenes Apple-Profil enthält kein Passwort; der Benutzer gibt das App-Passwort ein, wenn macOS oder iOS während der Installation danach fragt.

Das erste App-Passwort mit einem neuen Postfach erhalten

POST /api/v1/mailboxes und POST /api/v1/mailboxes:bulk akzeptieren den optionalen booleschen Wert create_app_password. Mit true erhält jedes erstellte Postfach zusätzlich sein erstes App-Passwort, das einmalig als app_password zurückgegeben wird: die oben beschriebenen Eintragsfelder plus password. Es heißt Created with the mailbox, und dafür wird keine Benachrichtigungs-E-Mail gesendet, weil das Postfach neu ist und der Aufrufer gerade sein Passwort erhalten hat. Ohne das Feld (Standard false) bleibt die Antwort unverändert. Solange App-Passwörter nicht aktiviert sind, wird es ignoriert.

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

Die Antwort 201 enthält dann one_time_password, das Postfachpasswort für Webmail, und app_password.password für Mail-Apps. In einer Sammelantwort hat jede erstellte Zeile ihr eigenes app_password. Konnte es nicht ausgegeben werden, ist app_password gleich null (die Einzelerstellung ergänzt außerdem _app_password_warning); das Postfach wird trotzdem erstellt, und Sie können mit dem oben beschriebenen Endpunkt eines erstellen. Eine exakte Wiederholung einer Einzelerstellung mit demselben Idempotency-Key liefert dieselbe Antwort einschließlich beider Passwörter, ohne ein zweites App-Passwort auszugeben. Eine wiederholte Sammelanfrage lässt die Passwörter weg, wie bei one_time_password.

Ein Passwort ersetzen oder widerrufen

Ersetzen erfordert keinen JSON-Anfragekörper:

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

Die Antwort 200 enthält den neuen vollständigen Eintrag unter data, sein einmal zurückgegebenes data.password, auf oberster Ebene replaced_id für den alten Eintrag und message. Der Ersatz hat eine neue data.id und denselben Namen. Der alte Eintrag wird mit revoked_reason: "rotated" widerrufen, sein Passwort funktioniert sofort nicht mehr, und Apps, die es verwenden, werden abgemeldet. Aktualisieren Sie das Gerät mit dem Ersatz.

So widerrufen Sie ein Passwort, ohne einen Ersatz auszustellen:

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

Ein Anfragekörper ist nicht erforderlich. Die Antwort 200 enthält status: "revoked" und den vollständigen widerrufenen Eintrag unter data. Die App verliert ihren Zugriff; andere Geräte mit gültigen App-Passwörtern verbinden sich selbst wieder. Ein Widerruf kann nicht rückgängig gemacht werden. Der Versuch, einen bereits widerrufenen Eintrag mit einer neuen Anfrage zu ersetzen oder zu widerrufen, liefert 409 conflict.

Den Anmeldemodus eines Postfachs für Mail-Apps ändern

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

mode ist erforderlich und akzeptiert:

• app_password_only: Mail-Apps benötigen ein App-Passwort. Verbindungen mit dem Postfachpasswort werden abgemeldet; Apps mit einem gültigen App-Passwort verbinden sich selbst wieder.
• password_or_app_password: Mail-Apps akzeptieren das Postfachpasswort oder ein App-Passwort.

Die Antwort 200 enthält mailbox_id, client_auth_mode und message. Erneutes Setzen des aktuellen Modus liefert 200 und ändert nichts. Eine Modusänderung widerruft keine bestehenden App-Passwörter.

Erstellen Sie Passwörter für die Geräte, bevor Sie sie verpflichtend machen. Eine abgewiesene Anmeldung mit dem Postfachpasswort kann Folgendes anzeigen: "Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords." (Anmeldung fehlgeschlagen. Dieses Postfach akzeptiert nur App-Passwörter: Erstellen Sie eines im Webmail unter Einstellungen > App-Passwörter.) Manche Apps zeigen nur einen allgemeinen Passwortfehler.

Freigegebene Postfächer haben keine direkte Anmeldung und liefern an diesem Endpunkt 422 mailbox_not_eligible. Systempostfächer der Plattform können nicht auf app_password_only umgestellt werden; dies liefert 422 system_mailbox_protected.

Keiner der Modi ändert die Anmeldung im neuen Webmail, Alle Posteingänge, Message-API-Token, Migrationen in das Postfach, Mailregeln oder Weiterleitungen. Mitglieder freigegebener Postfächer verwenden die Zugangsdaten und den Modus ihres eigenen regulären Postfachs.

Modi gesammelt ändern

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

Übergeben Sie mode und genau einen Selektor:

Konto- und Tokenbeschränkungen grenzen jede Auswahl ein. Eine ausdrückliche ID außerhalb des Zugriffs oder eine unbekannte ID liefert 404, statt eine Teilauswahl anzuwenden. Eine unbekannte Domain oder eine Domain eines anderen Kontos liefert 422 validation_error. Kein Selektor oder mehrere Selektoren liefern 422 invalid_selection.

Höchstens 1000 Postfächer dürfen der Auswahl entsprechen. Eine größere Auswahl liefert vor jeder Änderung 422 selection_too_large. Grenzen Sie die Domainauswahl ein oder senden Sie ausdrückliche Teilmengen.

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

matched zählt ausgewählte Postfächer; updated zählt tatsächliche Modusänderungen; skipped zählt freigegebene, in den Papierkorb verschobene oder gerade zu löschende Postfächer sowie Systempostfächer der Plattform beim Verlangen von App-Passwörtern. Der Modus pausierter oder anmeldegesperrter Postfächer kann für die spätere Rückkehr des Zugriffs aktualisiert werden. Bereits passende Postfächer zählen als gefunden, aber weder als aktualisiert noch als übersprungen; der Vorgang kann daher sicher wiederholt werden. Gesperrte Konten werden mit 403 abgewiesen.

Postfachstatus lesen und die Kontovorgabe setzen

Solange App-Passwörter aktiviert sind, enthalten GET /api/v1/mailboxes und GET /api/v1/mailboxes/{mailbox} diese Felder auf Postfachressourcen:

• client_auth_mode: app_password_only oder password_or_app_password.
• app_passwords_count: ganzzahlige Anzahl aktiver sichtbarer App-Passwörter, ohne plattforminterne Zugangsdaten.

Bei deaktivierter Funktion werden beide Felder ausgelassen. Freigegebene Postfächer haben keinen nutzbaren direkten Anmeldemodus und keine App-Passwörter; fordern Sie stattdessen Zugangsdaten für ein reguläres Mitgliedspostfach an.

GET /api/v1/account erfordert account:read. Die normalen Felder auf oberster Ebene bleiben verfügbar: id, name, email, plan, effective_plan_slug, subscription_status, limits, features, usage, safety_limits und created_at. new_mailbox_client_auth_mode wird nur ergänzt, wenn App-Passwörter aktiviert sind und die Plattform die Kontovorgabe auf neue Postfächer anwendet. Andernfalls bleibt GET verfügbar und lässt dieses Feld aus.

Nur der Kontoinhaber kann die Vorgabe ändern:

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

Das erforderliche Feld akzeptiert dieselben zwei Modi. Dies ist hier das einzige beschreibbare Kontofeld. Die Antwort enthält auf oberster Ebene id, new_mailbox_client_auth_mode und message. PATCH liefert 404, sofern nicht beide Bedingungen für das Anzeigen des Felds erfüllt sind, und 403 scope_blocked_by_membership für jedes Mitglieds-Token oder jeden von einem Mitglied autorisierten Konnektor.

Ein Inhaber-Token, das durch domain_ids oder mailbox_ids eingeschränkt ist, liefert 403 token_resource_constrained. Verwenden Sie ein Inhaber-Token ohne Ressourcenbeschränkungen oder ändern Sie die Vorgabe in den Kontoeinstellungen.

Die Vorgabe betrifft künftige Postfächer aus Dashboard-Erstellung, Massenerstellung, Einladungen, API und Agenten. Sie ändert nie bestehende Postfächer. Bei der Erstellung eines einzelnen Postfachs per API kann POST /api/v1/mailboxes ausdrücklich client_auth_mode enthalten; ohne Angabe gilt die Kontovorgabe. Bestehende Postfächer behalten bei der Einführung password_or_app_password. Die Vorgabe für neue Postfächer ist app_password_only, sofern der Kontoinhaber sie nicht ändert.

Ein Postfachpasswort-Reset widerruft App-Passwörter automatisch

POST /api/v1/mailboxes/{mailbox}/password erfordert mailboxes:write, dieselbe Mitgliedsberechtigung zum Setzen von Passwörtern und Idempotency-Key. Sein Anfragekörper erfordert password, das neue Postfachpasswort, das der Postfach-Passwortrichtlinie entsprechen muss. Dies ist kein Endpunkt zum Erstellen von App-Passwörtern.

Jeder erfolgreiche administrative Reset über diesen Endpunkt, einschließlich der Passwortänderung durch einen MCP-Agenten, widerruft alle App-Passwörter mit dem Grund mailbox_password_reset. Dies lässt sich nicht abwählen. Solange die Funktion aktiviert ist, enthält die Antwort app_passwords_revoked, eine ganzzahlige Anzahl, neben status, sync_pending und message:

• 200, status: "updated", sync_pending: false, wenn die Mailserversynchronisierung abgeschlossen ist.
• 202, status: "update_pending", sync_pending: true, wenn das Passwort gespeichert ist und die Synchronisierung aussteht. App-Passwörter sind zu diesem Zeitpunkt bereits widerrufen.

Der Reset widerruft auch bestehende Nachrichten-Token des Postfachs. Dies ist eine Folge des Zurücksetzens des Postfachpassworts, nicht des Ersetzens eines einzelnen App-Passworts oder des Änderns des Mail-App-Modus.

Eigene Passwortänderungen im Webmail widerrufen App-Passwörter nur, wenn der Benutzer Zusätzlich alle App-Passwörter widerrufen auswählt. Passwortwiederherstellung, Anmeldesperre, Umwandlung in ein freigegebenes Postfach und Verschieben nach Kürzlich gelöscht widerrufen alle. Das Wiederherstellen des Zugriffs oder des Postfachs stellt widerrufene Passwörter nicht wieder her. Siehe Postfach-Anmeldung per API sperren.

Idempotenz und einmal zurückgegebene Passwörter

Verwenden Sie für jede beabsichtigte Schreibaktion einen neuen Idempotency-Key und verwenden Sie ihn nur bei einem Transport-Wiederholungsversuch mit derselben Methode, demselben Pfad und demselben Anfragekörper erneut. Schlüssel sind erforderlich und dürfen höchstens 255 Zeichen haben. Erfolgreiche Antworten werden für das standardmäßige Zeitfenster von 24 Stunden zwischengespeichert; die Wiederverwendung eines Schlüssels für eine andere Anfrage liefert 409 idempotency_mismatch.

Eine Wiederholung der Erstellung oder des Ersetzens eines App-Passworts liefert dieselben sicheren IDs, lässt aber data.password aus. Sie enthält _idempotency_replay_warning und den Antwortheader X-Idempotency-Replayed: true. Eine Wiederholung kann ein verlorenes Passwort nicht zurückholen. Verwenden Sie die zurückgegebene data.id, um den aktiven Eintrag mit einem neuen Schlüssel zu ersetzen und ein nutzbares Ersatzpasswort zu erhalten. Halten Sie nach dem Ersetzen die neue ID fest.

Das Wiederholen eines erfolgreichen Widerrufs mit demselben Schlüssel liefert das gespeicherte Ergebnis. Eine neue Widerrufsanfrage gegen diesen widerrufenen Eintrag liefert 409 conflict. Modusänderungen sind von sich aus wiederholbar; geben Sie dennoch jeder beabsichtigten Änderung einen neuen Schlüssel: Die Wiederverwendung eines früheren Schlüssels nach einem Moduswechsel kann eine alte Antwort wiedergeben, statt Ihre neue Absicht anzuwenden.

Ratenlimits und Fehler

Die Erstellung ist auf 60 pro Stunde und Konto begrenzt, das Ersetzen auf 30 pro Stunde und Konto. Diese Kontolimits werden von API- und MCP-Aufrufern geteilt und sind keine getrennten Kontingente pro Token. Modusänderungen als Sammelaktion haben zusätzlich ein Limit von 10 Anfragen pro Minute. Auch das normale API-Limit gilt für diese Routen; seine Vorgabe beträgt 60 Anfragen pro Minute und Zugangsdaten. Eine begrenzte Anfrage liefert 429 rate_limited; beachten Sie den Header Retry-After vor einem erneuten Versuch.

Fehler verwenden das standardmäßige error-Objekt mit code, message, hint, request_id und retryable. Verarbeiten Sie den maschinenlesbaren Code, statt den Meldungstext abzugleichen.

MCP-Tools und Freigabe destruktiver Aktionen

MCP verwendet dieselbe REST-Autorisierung und dieselben Antwortfelder. Direkte Tools sind:

Die Tools zur Postfacherstellung create_mailbox_generated_password und bulk_create_mailboxes akzeptieren dieselbe optionale Eingabe create_app_password wie REST.

Schreib-Tools akzeptieren außerdem das optionale idempotency_key. REST verwendet bei Modusänderungen das Anfragekörperfeld mode; das MCP-Tool nennt diese Eingabe client_auth_mode. Seine Sammelselektoren haben dieselben Zugriffsregeln und dieselbe Grenze von 1000 Postfächern wie REST.

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

Im selbst gehosteten Server erfordert jede obige Schreibaktion TREKMAIL_ALLOW_DESTRUCTIVE=true. Auch das Erstellen von Zugangsdaten erfordert diese Freigabe, weil es Postfachzugriff gewährt. Auflisten und Lesen der Kontodaten benötigen diesen Schalter nicht. Bitten Sie den Benutzer vor einer Schreibaktion um Zustimmung zur beabsichtigten Änderung von Zugangsdaten oder Zugriff. Direkte Tools, die Passwörter zurückgeben, weisen den Agenten an, das Passwort einmal anzuzeigen, den Benutzer es in die App einfügen zu lassen und es nie in Dateien oder im Gedächtnis zu speichern oder in späteren Nachrichten oder Tool-Aufrufen zu wiederholen.

ChatGPT/OpenAI- und Claude-Verzeichnisprofile

Diese Profile liefern für Erstellung und Ersetzen einen sicheren Dashboard-Einrichtungslink, statt ein Passwort im Chat zu erzeugen. Auch die Postfacherstellung ist dort ein Dashboard-Link, daher kommt das erste App-Passwort von der Karte Postfach erstellt im Dashboard, nicht von create_app_password. Das Ziel ist /app/mailboxes/{mailbox_id}/security#app-passwords; der Benutzer meldet sich dort an und schließt die Aktion ab.

Das OpenAI-Profil bietet get_mailbox_app_password_setup_link und get_mailbox_app_password_replacement_setup_link. Das Claude-Profil behält die Namen create_mailbox_app_password und rotate_mailbox_app_password, liefert aber den sicheren Einrichtungslink statt data.password. Versprechen Sie bei diesen Verzeichnis-Tools kein Passwort und bitten Sie den Benutzer nicht, eines in die Unterhaltung einzufügen.

Verwenden Sie get_mail_client_setup für die Verbindungsdaten. Die allgemeine Konnektoreinrichtung erklärt KI-Agenten verbinden. White Label-Postfächer verwenden dieselbe API-Funktion sowie gebrandete Webmail- und Mailhosts; nennen Sie die Zugangsdaten in Benutzeranleitungen App-Passwort.