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 oder Zugangsdaten eines benutzerdefinierten SMTP-Anbieters zurück. Der Benutzer gibt das Postfachkennwort direkt in seiner Mail-App ein. 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, den konfigurierten Namespace und einen items[]-Eintrag für jedes an dieses reguläre Postfach delegierte freigegebene Postfach;
• password_included: false als ausdrückliche Sicherheitsgarantie.

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 Darf antworten; 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 Adresse und Kennwort dieses Mitglieds. Erstellen Sie kein zweites Konto und versuchen Sie keine direkte Anmeldung mit der freigegebenen Adresse.

Bei deaktiviertem nativen Zugriff ist shared_mailboxes.native_access_enabled gleich false und items leer. Ist er aktiviert, aber items leer, hat das reguläre Postfach derzeit keine aktive Mitgliedschaft in einem freigegebenen Postfach. In beiden Fällen wird kein Kennwort einbezogen.

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 dem Postfachkennwort. TrekMail gibt 409 mail_client_setup_not_ready zurück, statt bei nicht verfügbarem Versand ein irreführendes Profil zu erzeugen.

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.