Comptes connectés avec API et MCP

Les comptes connectés permettent à une boîte de messagerie web de lire et d’envoyer des messages depuis des boîtes externes, Gmail, Yahoo, iCloud, Outlook.com/Microsoft 365 ou n’importe quel serveur IMAP. L’API de messages et les outils MCP proposent la même fonctionnalité par programmation : vous pouvez répertorier, ajouter, tester, modifier et supprimer des comptes connectés, mais aussi diriger les appels de messagerie ordinaires (liste, lecture, envoi, indicateurs, déplacement, suppression et dossiers) vers un compte connecté plutôt que vers la propre boîte du jeton.

En clair : mailbox_id sélectionne la boîte TrekMail pour laquelle l’agent peut agir, tandis que external_account_id sélectionne Gmail ou une autre boîte connectée qu’elle contient. Ils ne sont pas interchangeables.

Forfaits, limites et taille du catalogue

La gestion des comptes connectés fournit sept outils de messagerie. Un jeton à portée limitée ne voit que les outils qu’il peut réellement utiliser, et non l’intégralité du catalogue du produit.

Avant de commencer

• Les comptes connectés sont une fonctionnalité de messagerie web et utilisent l’interface du jeton de messages (/api/v1/messages/...), autorisée par un jeton de messages doté des portées ci-dessous, et non par un jeton d’API du tableau de bord.
• Les limites de forfait s’appliquent par boîte : Starter 5, Pro 10, Agency 30. Le forfait Nano n’inclut pas les comptes connectés.
• Chaque endpoint est limité à la propre boîte du jeton. Un jeton ne peut voir et gérer que ses propres comptes connectés, jamais ceux d’une autre boîte.
• Les identifiants et les jetons OAuth sont toujours masqués dans les réponses. Vous pouvez saisir un mot de passe ou un mot de passe d’application, mais vous ne pouvez jamais le relire.
• Les comptes Outlook.com et Microsoft 365 se connectent par la connexion Microsoft (OAuth) dans l’interface de messagerie web. L’API peut les gérer et les utiliser une fois connectés, mais elle n’effectue pas l’étape interactive de consentement Microsoft.

Portées

Cibler un compte connecté dans un appel de messagerie exige la même portée que celle déjà requise par cet appel (par exemple, la liste de ses messages exige messages:read, tandis que l’envoi exige messages:send).

Gestion des comptes connectés

Chemin de base : /api/v1/messages/external-accounts

Ajouter un compte

POST /api/v1/messages/external-accounts
Scope: messages:write

Corps de la requête :

Appelez d’abord POST /external-accounts/detect pour renseigner automatiquement provider et les paramètres du serveur. L’appel de stockage exécute un test IMAP + SMTP réel avant l’enregistrement. Un 422 accompagné d’une catégorie d’erreur (auth, tls, network, transient_throttle) signifie que les identifiants n’ont pas fonctionné et que rien n’a été stocké.

Ciblage d’un compte connecté dans les appels de messagerie

Chaque endpoint de messagerie qui agit sur une boîte accepte un external_account_id facultatif. Fournissez-le pour exécuter l’appel sur ce compte connecté plutôt que sur la propre boîte du jeton, ou omettez-le pour utiliser la boîte elle-même. Cela s’applique à la liste, la lecture, l’envoi, la réponse, les indicateurs, le déplacement, la suppression et la liste des dossiers.

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

Un envoi avec le seul external_account_id passe par le propre serveur SMTP de ce compte (avec le SPF/DKIM de son fournisseur). Fournir à la place un identity_id lié à la source utilise le domaine ou la route du profil enregistré de cette identité d’expéditeur, tout en conservant la copie Envoyés dans la boîte connectée. Le compte doit être opérationnel (status: active). Un compte déconnecté renvoie une erreur vous demandant de le reconnecter. Consultez Adresses d’expéditeur avec API et MCP.

Outils MCP

La même fonctionnalité est proposée aux agents d’IA par MCP (sur le serveur stdio privé comme sur le serveur MCP public) :

Les outils de messagerie, list_messages, read_message, send_message, list_folders, update_message_flags, move_message, delete_message, prepare_reply, prepare_reply_all et prepare_forward, acceptent l’argument facultatif external_account_id. L’envoi, la création de brouillons et la programmation acceptent aussi un identity_id lié à la source et renvoyé par list_identities.

Comme les outils de gestion ouvrent des connexions sortantes vers des serveurs de messagerie arbitraires avec des identifiants fournis par l’utilisateur, ils appliquent les mêmes mesures de sécurité que le reste de la fonctionnalité des comptes connectés : liste d’hôtes autorisés, blocage des plages privées, liste de ports autorisés et plafonds de connexions par hôte.

Articles associés

• Lisez tous vos comptes e-mail dans une seule boîte de réception
• Ajoutez votre compte Outlook.com à TrekMail
• Présentation de l’API REST TrekMail pour les développeurs
• Envoyez depuis une adresse professionnelle avec Gmail