Mailclient-Einrichtung über API und MCP

TrekMail stellt über REST und MCP dieselben Verbindungsdaten aus Apps & Geräte bereit, die das Dashboard nutzt. Beide Schnittstellen sind schreibgeschützt und erfordern Lesezugriff auf das Postfach.

Sie geben niemals das Postfachkennwort, ein App-Passwort oder Zugangsdaten eines benutzerdefinierten SMTP-Anbieters zurück. Der Benutzer gibt ein App-Passwort direkt in seiner Mail-App ein, oder das Postfachkennwort, falls das Postfach es noch akzeptiert. Auch wenn ausgehende Nachrichten einer Domain über einen eigenen Anbieter laufen, senden externe Mail-Apps an den öffentlichen SMTP-Endpunkt von TrekMail; TrekMail wendet dahinter die private Domainroute an.

Verbindungseinstellungen abrufen

GET /api/v1/mailboxes/{mailbox_id}/client-setup?lang=en
Authorization: Bearer tm_live_...

Erforderlicher interner Bereich: mailboxes:read. Optionale domain_ids- und mailbox_ids-Einschränkungen des Tokens werden durchgesetzt.

Die Antwort enthält:

• eingehenden IMAP-Host, SSL-Port, Benutzername und Bereitschaft;
• ausgehenden SMTP-Host, SSL-Port, Benutzername und Bereitschaft;
• DAV-Server-URL für Kalender und Kontakte, Verbindungsbereitschaft und Angabe, ob die Adresse gebrandet ist;
• dieselben lokalisierten dreistufigen Anleitungen für Gmail, Outlook, Apple Mail, Thunderbird und allgemeines IMAP wie unter Apps & Geräte;
• sending.mode: platform, profile oder not_configured;
• sending.reason: einen stabilen maschinenlesbaren Grund, wenn der Versand nicht bereit ist;
• apple_mail_profile.available, das nur bei Empfangs- und Sendebereitschaft true ist;
• shared_mailboxes.native_access_enabled, namespace, items[];
• authentication.client_auth_mode: app_password_only oder password_or_app_password;
• authentication.accepted_passwords: entsprechend ["app_password"] oder ["mailbox_password", "app_password"];
• authentication.app_passwords_endpoint: den Endpunkt zur Verwaltung der App-Passwörter des Postfachs;
• password_included: false als ausdrückliche Sicherheitsgarantie.

shared_mailboxes.items[] enthält nur Mitgliedschaften mit der Berechtigung Lesen, wenn nativer Ordnerzugriff aktiviert ist. delegated_send_addresses ist eine separate Liste verfügbarer Team-Absenderadressen mit id, email und display_name; sie kann leer sein. Sie gewährt keinen Ordnerzugriff und prüft keine Sendebereitschaft. Diese Adressen sind keine Message-API-Identitäten. Verwenden Sie die zurückgegebenen Server, auch bei White Label, statt einen Plattform-Hostnamen zu kopieren.

Jeder delegierte Eintrag enthält beständige Werte native_access_status/native_access_ready, exakte Standardpfade unter folders, serverseitig erzwungene operations sowie effektive Werte send_as_ready/send_as_reason. can_send bleibt die vom Administrator zugewiesene Berechtigung Senden als; sie kann bei nicht verfügbarem SMTP true sein, daher muss die Automatisierung beide Bereitschaftsfelder prüfen. Ist das Mitgliedspostfach inaktiv, die Anmeldung gesperrt oder die direkte Anmeldung deaktiviert, bleibt das freigegebene Postfach sichtbar, gibt aber mailbox_unavailable, mailbox_login_suspended oder direct_login_unavailable als Senden-als-Grund zurück. Das alte Feld folder bleibt der exakte Posteingangspfad. Warten Sie auf native_access_ready=true, bevor Sie durch die Einrichtung führen.

SMTP transportiert eine Antwort oder Weiterleitung, speichert aber keine Kopie unter Gesendet. Daher ist sent_copy.smtp_saves_copy gleich false; konfigurieren Sie den Client so, dass er die Kopie an sent_copy.folder anhängt (derselbe Wert wie folders.sent), damit das gesamte Team sie sieht. folders.archive und folders.junk sind exakte Verschiebeziele, wenn der Client Archiv oder Spam nicht automatisch zuordnet. Das Verschieben nach Junk verspricht allein kein Training des serverseitigen Spamfilters.

Fordern Sie diesen Endpunkt immer mit der ID des regulären Mitgliedspostfachs an und authentifizieren Sie den Mailclient mit der eigenen Adresse dieses Mitglieds und dessen App-Passwort, oder dem Postfachkennwort, falls es akzeptiert wird. Erstellen Sie kein zweites Konto und versuchen Sie keine direkte Anmeldung mit der freigegebenen Adresse.

Die Ordnerliste shared_mailboxes beschreibt nativen Zugriff für Personen mit Leserecht. Ist items leer, prüfen Sie den nativen Zugriff und Lesen. Eine leere Liste bedeutet nicht, dass alle Rechte für gemeinsame Adressen entzogen wurden. Es wird kein Passwort ausgegeben.

Der optionale Parameter lang akzeptiert dieselben 13 Sprachen wie der Apple-Profil-Endpunkt. Ohne ihn verwendet TrekMail Accept-Language und dann das Standardgebietsschema. Jede Anleitung hat eine stabile id, drei lokalisierte steps und eine action: use_server_settings oder download_apple_profile.

connection_status=receiving_only bedeutet keine erfolgreiche vollständige Einrichtung. Konfigurieren oder reparieren Sie die ausgehende Domainroute, bevor Sie einen Client verbinden lassen, der beide Server prüft.

connection_status=unavailable bedeutet, dass sich der Postfachlebenszyklus geändert hat und direkte Anmeldung nicht mehr möglich ist. Verwenden Sie die zurückgegebenen Serverdaten nicht und bieten Sie kein Apple-Mail-Profil an; aktualisieren Sie stattdessen den Postfachstatus.

Apple-Mail-Profil herunterladen

GET /api/v1/mailboxes/{mailbox_id}/apple-mail-profile?lang=en
Authorization: Bearer tm_live_...
Accept: application/x-apple-aspen-config

Die Antwort ist ein .mobileconfig-Anhang. Unterstützte lang-Werte sind en, es, fr, de, pt, it, nl, ru, zh, ja, ko, ar und he. Fehlt lang, verwendet TrekMail Accept-Language und danach das Standardgebietsschema.

Das Profil enthält IMAP- und SMTP-Einstellungen, aber keine Kennwortfelder. Apple fragt während der Installation nach einem Passwort: Verwenden Sie ein App-Passwort bei app_password_only oder eines der akzeptierten Passwörter bei password_or_app_password. TrekMail gibt 409 mail_client_setup_not_ready zurück, statt bei nicht verfügbarem Versand ein irreführendes Profil zu erzeugen.

Erstellen Sie ein App-Passwort im Webmail unter Einstellungen, App-Passwörter oder im Dashboard unter Postfächer, (Postfach), Sicherheit, App-Passwörter. Der schreibgeschützte Einrichtungsendpunkt erstellt keines. REST-Endpunkte und MCP-Tools zur Verwaltung dieser Passwörter und des Anmeldemodus finden Sie unter App-Passwörter über API und MCP.

MCP-Werkzeuge

Die Werkzeuge nutzen dieselben REST-Endpunkte und Autorisierungsregeln:

MCP-Transporte geben strukturierte Werkzeuginhalte statt eines Browserdownloads zurück. Decodieren Sie content_base64 als Bytes und speichern Sie es unter file_name; interpretieren Sie es vor der Decodierung nicht als JSON oder UTF-8.

Beide Werkzeuge benötigen den gehosteten OAuth-Bereich mail:read, der zum internen Bereich mailboxes:read erweitert wird. Sie sind schreibgeschützt und hängen im selbst gehosteten stdio-Server nicht von einer Umgebungsvariable für destruktive Operationen ab.

Fehler

Der Einrichtungsendpunkt kann folgende sending.reason-Werte zurückgeben: mailbox_unavailable, direct_login_unavailable, domain_unavailable, domain_deprovisioning, account_suspended, email_verification_required, mailbox_sending_disabled, smtp_not_configured, managed_smtp_not_in_plan, managed_smtp_entitlement_inactive, smtp_profile_unavailable oder smtp_route_invalid.