Configurer un client de messagerie via API et MCP

TrekMail expose via REST et MCP les mêmes données de connexion Applications et appareils que le tableau de bord. Ces deux interfaces sont en lecture seule et exigent un accès en lecture à la boîte aux lettres.

Elles ne renvoient jamais le mot de passe de la boîte ni les identifiants d’un fournisseur SMTP personnalisé. L’utilisateur saisit directement le mot de passe dans son application de messagerie. Même si un domaine achemine les messages sortants par un fournisseur personnalisé, les applications externes les soumettent à l’endpoint SMTP public de TrekMail; TrekMail applique ensuite la route privée du domaine.

Obtenir les réglages de connexion

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

Droit interne requis : mailboxes:read. Les restrictions facultatives domain_ids et mailbox_ids du jeton sont appliquées.

La réponse contient :

• l’hôte IMAP entrant, le port SSL, le nom d’utilisateur et l’état de disponibilité;
• l’hôte SMTP sortant, le port SSL, le nom d’utilisateur et l’état de disponibilité;
• l’URL du serveur DAV pour les calendriers et contacts, son état de connexion et l’indication que l’adresse renvoyée porte ou non la marque;
• les mêmes guides localisés en trois étapes pour Gmail, Outlook, Apple Mail, Thunderbird et IMAP générique que dans Applications et appareils;
• sending.mode : platform, profile ou not_configured;
• sending.reason : une raison stable lisible par machine lorsque l’envoi n’est pas prêt;
• apple_mail_profile.available, qui vaut true uniquement lorsque la réception et l’envoi sont prêts;
• shared_mailboxes.native_access_enabled, l’espace de noms configuré et une entrée items[] pour chaque boîte partagée déléguée à cette boîte normale;
• password_included: false comme garantie de sécurité explicite.

Chaque élément de boîte partagée déléguée contient des valeurs durables native_access_status/native_access_ready, les chemins standard exacts dans folders, les operations imposées par le serveur et les valeurs effectives send_as_ready/send_as_reason. can_send reste l’autorisation Peut répondre attribuée par l’administrateur; elle peut valoir true alors que SMTP est indisponible, l’automatisation doit donc vérifier les deux champs de disponibilité. Si la boîte membre est inactive, si sa connexion est suspendue ou si la connexion directe est désactivée, la boîte partagée reste visible, mais renvoie mailbox_unavailable, mailbox_login_suspended ou direct_login_unavailable comme raison d’envoi en tant que. L’ancien champ folder conserve le chemin exact de la boîte de réception. Attendez native_access_ready=true avant de guider l’utilisateur.

SMTP transporte une réponse ou un transfert, mais n’enregistre pas sa copie dans Envoyés. sent_copy.smtp_saves_copy vaut donc false; configurez le client pour ajouter la copie à sent_copy.folder (la même valeur que folders.sent) afin que toute l’équipe puisse la voir. folders.archive et folders.junk sont les destinations exactes lorsqu’un client n’associe pas automatiquement Archive ou Indésirables. Le déplacement vers Indésirables ne garantit pas à lui seul l’apprentissage du classificateur antispam du serveur.

Appelez toujours cet endpoint avec l’ID de la boîte membre normale et authentifiez le client avec l’adresse et le mot de passe propres à ce membre. Ne créez pas de deuxième compte et ne tentez pas une authentification directe avec l’adresse partagée.

Lorsque l’accès natif est désactivé, shared_mailboxes.native_access_enabled vaut false et items est vide. Lorsqu’il est activé mais que items est vide, la boîte normale n’est actuellement membre actif d’aucune boîte partagée. Aucun mot de passe de boîte partagée ou membre n’est inclus dans les deux cas.

Le paramètre facultatif lang accepte les 13 mêmes langues que l’endpoint du profil Apple. S’il est omis, TrekMail utilise Accept-Language, puis la langue par défaut. Chaque guide possède un id stable, trois steps localisées et une action : use_server_settings ou download_apple_profile.

connection_status=receiving_only ne représente pas une configuration complète réussie. Configurez ou restaurez la route sortante du domaine avant d’indiquer à l’utilisateur de connecter un client qui valide les deux serveurs.

connection_status=unavailable signifie que le cycle de vie de la boîte a changé et qu’elle ne peut plus s’authentifier directement. N’utilisez pas les coordonnées de serveur renvoyées et ne proposez pas de profil Apple Mail; actualisez plutôt l’état de la boîte.

Télécharger un profil Apple Mail

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

La réponse est une pièce jointe .mobileconfig. Les valeurs lang prises en charge sont en, es, fr, de, pt, it, nl, ru, zh, ja, ko, ar et he. Si lang est omis, TrekMail utilise Accept-Language, puis la langue par défaut.

Le profil contient les réglages IMAP et SMTP, mais aucun champ de mot de passe. Apple demande le mot de passe de la boîte pendant l’installation. TrekMail renvoie 409 mail_client_setup_not_ready plutôt que de générer un profil trompeur lorsque l’envoi est indisponible.

Outils MCP

Les outils utilisent les mêmes endpoints REST et règles d’autorisation :

Les transports MCP renvoient un contenu d’outil structuré plutôt qu’un téléchargement de navigateur. Décodez content_base64 en octets et enregistrez-le sous file_name; ne le réinterprétez pas comme JSON ou UTF-8 avant le décodage.

Les deux outils exigent le droit OAuth hébergé mail:read, qui s’étend au droit interne mailboxes:read. Ils sont en lecture seule et ne dépendent d’aucun indicateur d’environnement d’opération destructive dans le serveur stdio auto-hébergé.

Erreurs

L’endpoint de configuration peut renvoyer ces valeurs 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 ou smtp_route_invalid.