Mailclient instellen via API en MCP

TrekMail biedt via REST en MCP dezelfde verbindingsgegevens uit Apps en apparaten als het dashboard. Beide interfaces zijn alleen-lezen en vereisen leestoegang tot het postvak.

Ze geven nooit het mailboxwachtwoord, een app-wachtwoord of referenties voor een aangepaste SMTP-provider terug. De gebruiker voert een app-wachtwoord rechtstreeks in de mail-app in, of het mailboxwachtwoord als de mailbox dat nog accepteert. Zelfs wanneer uitgaande berichten via een aangepaste provider lopen, sturen externe apps ze naar het openbare SMTP-endpoint van TrekMail; TrekMail past daarachter de privéroute van het domein toe.

Verbindingsinstellingen ophalen

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

Vereiste interne scope: mailboxes:read. Optionele beperkingen domain_ids en mailbox_ids van het token worden afgedwongen.

Het antwoord bevat:

• inkomende IMAP-host, SSL-poort, gebruikersnaam en gereedheid;
• uitgaande SMTP-host, SSL-poort, gebruikersnaam en gereedheid;
• DAV-server-URL voor agenda’s en contacten, verbindingsgereedheid en of het geretourneerde adres merkgebonden is;
• dezelfde gelokaliseerde driestappengidsen voor Gmail, Outlook, Apple Mail, Thunderbird en algemene IMAP als in Apps en apparaten;
• sending.mode: platform, profile of not_configured;
• sending.reason: een stabiele machineleesbare reden wanneer verzenden niet gereed is;
• apple_mail_profile.available, alleen true wanneer ontvangen en verzenden gereed zijn;
• shared_mailboxes.native_access_enabled, namespace, items[];
• authentication.client_auth_mode: app_password_only of password_or_app_password;
• authentication.accepted_passwords: respectievelijk ["app_password"] of ["mailbox_password", "app_password"];
• authentication.app_passwords_endpoint: het endpoint voor app-wachtwoordbeheer van de mailbox;
• password_included: false als expliciete veiligheidsgarantie.

shared_mailboxes.items[] bevat alleen leden met het recht Lezen wanneer native maptoegang is ingeschakeld. delegated_send_addresses is een aparte lijst beschikbare teamadressen in het veld Van met id, email en display_name; deze kan leeg zijn. De lijst geeft geen maptoegang en controleert niet of verzenden gereed is. Dit zijn geen Message API-identiteiten. Gebruik de teruggegeven servers, ook bij White Label, in plaats van een platformhostnaam te kopiëren.

Elk gedelegeerd item bevat duurzame native_access_status/native_access_ready, exacte standaardpaden onder folders, servermatig afgedwongen operations en effectieve send_as_ready/send_as_reason. can_send blijft de door de beheerder toegewezen machtiging Verzenden als; deze kan true zijn terwijl SMTP niet beschikbaar is, dus automatisering moet beide gereedheidsvelden controleren. Een inactief lidpostvak, opgeschorte aanmelding of uitgeschakelde directe aanmelding laat het gedeelde postvak zichtbaar, maar geeft mailbox_unavailable, mailbox_login_suspended of direct_login_unavailable als reden voor Verzenden als. Het oude veld folder blijft het exacte Postvak IN-pad. Wacht op native_access_ready=true voordat u een gebruiker door de instelling leidt.

SMTP vervoert een antwoord of doorsturing, maar bewaart geen kopie in Verzonden. Daarom is sent_copy.smtp_saves_copy gelijk aan false; stel de client in om de kopie toe te voegen aan sent_copy.folder (dezelfde waarde als folders.sent), zodat het hele team deze ziet. folders.archive en folders.junk zijn exacte doelen wanneer een client Archief of Spam niet automatisch koppelt. Verplaatsen naar Ongewenst garandeert op zichzelf geen training van het spamfilter op de server.

Vraag dit endpoint altijd aan met de ID van het gewone lidpostvak en verifieer de mailclient met het eigen adres en app-wachtwoord van dat lid, of het mailboxwachtwoord als dat wordt geaccepteerd. Maak geen tweede account en probeer geen directe aanmelding met het gedeelde adres.

De mappenlijst shared_mailboxes beschrijft native toegang voor mensen die de inbox kunnen lezen. Is items leeg, controleer dan native toegang en Lezen. Een lege lijst bewijst niet dat alle rechten op gedeelde adressen zijn ingetrokken. Er wordt geen wachtwoord teruggegeven.

De optionele parameter lang accepteert dezelfde 13 talen als het Apple-profiel-endpoint. Zonder deze parameter gebruikt TrekMail Accept-Language en vervolgens de standaardlocale. Elke gids heeft een stabiele id, drie gelokaliseerde steps en een action: use_server_settings of download_apple_profile.

connection_status=receiving_only is geen geslaagde volledige instelling. Configureer of herstel de uitgaande domeinroute voordat u een gebruiker een client laat verbinden die beide servers valideert.

connection_status=unavailable betekent dat de levenscyclus van het postvak is gewijzigd en directe verificatie niet meer mogelijk is. Gebruik de teruggegeven servergegevens niet en bied geen Apple Mail-profiel aan; vernieuw eerst de postvakstatus.

Een Apple Mail-profiel downloaden

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

Het antwoord is een .mobileconfig-bijlage. Ondersteunde lang-waarden zijn en, es, fr, de, pt, it, nl, ru, zh, ja, ko, ar en he. Zonder lang gebruikt TrekMail Accept-Language en daarna de standaardlocale.

Het profiel bevat IMAP- en SMTP-instellingen, maar geen wachtwoordvelden. Apple vraagt tijdens de installatie om een wachtwoord: gebruik een app-wachtwoord voor app_password_only, of een van beide geaccepteerde wachtwoorden voor password_or_app_password. TrekMail geeft 409 mail_client_setup_not_ready terug in plaats van een misleidend profiel te maken wanneer uitgaande mail niet beschikbaar is.

Maak een app-wachtwoord in webmail onder Instellingen, App-wachtwoorden of in het dashboard onder Mailboxen, (mailbox), Beveiliging, App-wachtwoorden. Het configuratie-endpoint is alleen-lezen en maakt er geen. Voor REST-endpoints en MCP-tools die deze wachtwoorden en de aanmeldingsmodus beheren, zie App-wachtwoorden via API en MCP.

MCP-hulpmiddelen

De hulpmiddelen gebruiken dezelfde REST-endpoints en autorisatieregels:

MCP-transporten geven gestructureerde hulpmiddelinhoud terug in plaats van een browserdownload. Decodeer content_base64 als bytes en sla deze op onder file_name; interpreteer het vóór decodering niet als JSON of UTF-8.

Beide hulpmiddelen vereisen de gehoste OAuth-scope mail:read, die wordt uitgebreid naar de interne scope mailboxes:read. Ze zijn alleen-lezen en hangen op de zelfgehoste stdio-server niet af van een omgevingsvlag voor destructieve bewerkingen.

Fouten

Het endpoint kan deze sending.reason-waarden teruggeven: 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 of smtp_route_invalid.