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 postvakwachtwoord of referenties voor een aangepaste SMTP-provider terug. De gebruiker voert het wachtwoord rechtstreeks in de mailapp in. 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, de geconfigureerde namespace en één items[]-item voor elk gedeeld postvak dat aan dit gewone postvak is gedelegeerd;
• password_included: false als expliciete veiligheidsgarantie.

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 Kan antwoorden; 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 Verzenden als-reden. 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 wachtwoord van dat lid. Maak geen tweede account en probeer geen directe aanmelding met het gedeelde adres.

Wanneer native toegang uitstaat, is shared_mailboxes.native_access_enabled false en items leeg. Staat deze aan maar is items leeg, dan heeft het gewone postvak momenteel geen actief lidmaatschap van een gedeeld postvak. In geen van beide gevallen wordt een wachtwoord opgenomen.

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 het postvakwachtwoord. TrekMail geeft 409 mail_client_setup_not_ready terug in plaats van een misleidend profiel te maken wanneer uitgaande mail niet beschikbaar is.

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.