Configurare un client email tramite API e MCP

TrekMail espone tramite REST e MCP gli stessi dati di connessione di App e dispositivi usati dal pannello. Entrambe le interfacce sono di sola lettura e richiedono l’accesso in lettura alla casella.

Non restituiscono mai la password della casella o le credenziali di un provider SMTP personalizzato. L’utente inserisce la password direttamente nell’app email. Anche quando un dominio instrada i messaggi in uscita tramite un provider personalizzato, le app esterne inviano all’endpoint SMTP pubblico di TrekMail; TrekMail applica internamente la rotta privata del dominio.

Ottenere le impostazioni di connessione

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

Ambito interno richiesto: mailboxes:read. Vengono applicati i vincoli facoltativi domain_ids e mailbox_ids del token.

La risposta contiene:

• host IMAP in entrata, porta SSL, nome utente e stato di disponibilità;
• host SMTP in uscita, porta SSL, nome utente e stato di disponibilità;
• URL del server DAV per calendari e contatti, disponibilità della connessione e indicazione se l’indirizzo restituito include il marchio;
• le stesse guide localizzate in tre passaggi per Gmail, Outlook, Apple Mail, Thunderbird e IMAP generico mostrate in App e dispositivi;
• sending.mode: platform, profile o not_configured;
• sending.reason: un motivo stabile e leggibile dalla macchina quando l’invio non è pronto;
• apple_mail_profile.available, che è true solo quando ricezione e invio sono pronti;
• shared_mailboxes.native_access_enabled, lo spazio dei nomi configurato e una voce items[] per ogni casella condivisa delegata a questa casella normale;
• password_included: false come garanzia di sicurezza esplicita.

Ogni elemento delegato contiene valori durevoli native_access_status/native_access_ready, percorsi standard esatti in folders, operations imposte dal server e valori effettivi send_as_ready/send_as_reason. can_send resta il permesso Può rispondere assegnato dall’amministratore; può essere true mentre SMTP non è disponibile, quindi l’automazione deve controllare entrambi i campi di disponibilità. Se la casella membro è inattiva, l’accesso è sospeso o l’accesso diretto è disabilitato, la casella condivisa resta visibile ma restituisce mailbox_unavailable, mailbox_login_suspended o direct_login_unavailable come motivo di Invio come. Il campo precedente folder conserva il percorso esatto della Posta in arrivo. Attendi native_access_ready=true prima di guidare l’utente.

SMTP trasporta una risposta o un inoltro, ma non ne salva la copia in Inviati. Pertanto sent_copy.smtp_saves_copy è false; configura il client per aggiungere la copia a sent_copy.folder (lo stesso valore di folders.sent) affinché tutto il team possa vederla. folders.archive e folders.junk sono destinazioni esatte quando il client non associa automaticamente Archivio o Spam. Lo spostamento in Posta indesiderata non garantisce da solo l’addestramento del classificatore antispam del server.

Richiedi sempre questo endpoint con l’ID della casella membro normale e autentica il client con l’indirizzo e la password propri di quel membro. Non creare un secondo account e non tentare l’autenticazione diretta con l’indirizzo condiviso.

Quando l’accesso nativo è disabilitato, shared_mailboxes.native_access_enabled è false e items è vuoto. Quando è abilitato ma items è vuoto, la casella normale non ha attualmente appartenenze attive a caselle condivise. In entrambi i casi non viene inclusa alcuna password.

Il parametro facoltativo lang accetta le stesse 13 lingue dell’endpoint del profilo Apple. Se omesso, TrekMail usa Accept-Language e poi la lingua predefinita. Ogni guida ha un id stabile, tre steps localizzati e una action: use_server_settings o download_apple_profile.

connection_status=receiving_only non indica una configurazione completa riuscita. Configura o ripristina la rotta in uscita del dominio prima di indicare all’utente di connettere un client che convalida entrambi i server.

connection_status=unavailable indica che il ciclo di vita della casella è cambiato e non può più autenticarsi direttamente. Non usare le coordinate restituite né offrire un profilo Apple Mail; aggiorna invece lo stato della casella.

Scaricare un profilo Apple Mail

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

La risposta è un allegato .mobileconfig. I valori lang supportati sono en, es, fr, de, pt, it, nl, ru, zh, ja, ko, ar e he. Se lang viene omesso, TrekMail usa Accept-Language e poi la lingua predefinita.

Il profilo contiene le impostazioni IMAP e SMTP, ma nessun campo password. Apple chiede all’utente la password durante l’installazione. TrekMail restituisce 409 mail_client_setup_not_ready invece di generare un profilo ingannevole quando l’invio non è disponibile.

Strumenti MCP

Gli strumenti usano gli stessi endpoint REST e le stesse regole di autorizzazione:

I trasporti MCP restituiscono contenuti strutturati dello strumento anziché un download del browser. Decodifica content_base64 come byte e salvalo usando file_name; non reinterpretarlo come JSON o UTF-8 prima della decodifica.

Entrambi richiedono l’ambito OAuth ospitato mail:read, che si espande nell’ambito interno mailboxes:read. Sono di sola lettura e non dipendono da variabili di ambiente per operazioni distruttive nel server stdio self-hosted.

Errori

L’endpoint può restituire questi valori sending.reason: 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 o smtp_route_invalid.