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, una password per le app o le credenziali di un provider SMTP personalizzato. L’utente inserisce una password per le app direttamente nell’app di posta, oppure la password della casella se ancora accettata. 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, namespace, items[];
• authentication.client_auth_mode: app_password_only o password_or_app_password;
• authentication.accepted_passwords: rispettivamente ["app_password"] o ["mailbox_password", "app_password"];
• authentication.app_passwords_endpoint: l’endpoint di gestione delle password per le app della casella;
• password_included: false come garanzia di sicurezza esplicita.

shared_mailboxes.items[] include solo membri con il permesso Leggi quando l’accesso nativo alle cartelle è abilitato. delegated_send_addresses è un elenco separato di indirizzi del team disponibili nel campo Da con id, email e display_name; può essere vuoto. Non dà accesso alle cartelle né verifica che l’invio sia pronto. Questi indirizzi non sono identità della Message API. Usa i server restituiti, anche con White Label, invece di copiare un server della piattaforma.

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 Invia come 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 una password per le app di quel membro, oppure la password della casella se accettata. Non creare un secondo account e non tentare l’autenticazione diretta con l’indirizzo condiviso.

L’elenco di cartelle shared_mailboxes descrive l’accesso nativo di chi può leggere la casella. Se items è vuoto, controlla l’accesso nativo e Leggi. Un elenco vuoto non prova che tutti i diritti sugli indirizzi condivisi siano stati tolti. Non viene restituita 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 una password durante l’installazione: usa una password per le app per app_password_only, oppure una delle password accettate per password_or_app_password. TrekMail restituisce 409 mail_client_setup_not_ready invece di generare un profilo ingannevole quando l’invio non è disponibile.

Crea una password per le app nella webmail in Impostazioni, Password per le app o nella dashboard in Caselle, (casella), Sicurezza, Password per le app. L’endpoint di configurazione in sola lettura non ne crea una. Per gli endpoint REST e gli strumenti MCP che gestiscono queste password e la modalità di accesso, consulta Password per le app di posta via API e MCP.

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.