Gérer les contacts via l’API et MCP

Le carnet d’adresses de votre boîte mail est entièrement programmable. L’API de messages et les outils MCP peuvent créer, modifier et supprimer des contacts, effectuer des importations et des exportations groupées (CSV ou vCard), rechercher dans un grand carnet d’adresses et organiser les personnes en groupes. Il s’agit des mêmes données que voient votre webmail et vos clients CardDAV. Ainsi, un contact ajouté par un agent d’IA apparaît sur votre téléphone, et un contact ajouté sur votre téléphone est visible par l’API.

Avant de commencer

• Les contacts utilisent l’interface du jeton de messages (/api/v1/messages/...) et ses portées, et non un jeton d’API du tableau de bord.
• Chaque appel est limité à la boîte mail propre au jeton. Un jeton peut uniquement voir et gérer ses propres contacts et groupes, jamais ceux d’une autre boîte mail.
• Les contacts sont identifiés par leur adresse e-mail au sein d’une boîte mail. Une importation met à jour un contact correspondant. La création d’un contact avec une adresse existante renvoie ce contact sans modification au lieu de créer un doublon.
• Les réponses de liste renvoient un ensemble de champs clair et lisible (nom, e-mail, société, poste, téléphone, adresse, date de naissance et notes). La carte CardDAV brute associée à un contact synchronisé n’est jamais renvoyée. Vous obtenez toujours la version épurée.
• L’importation accepte les fichiers CSV et vCard (.vcf) jusqu’à 10 MB et comprend les formats d’exportation de Google Contacts, Outlook, Apple et Roundcube, y compris les particularités UTF-8, UTF-16 et BOM.

Portées

Gérer les contacts

Chemin de base : /api/v1/messages/contacts

Répertorier et rechercher

GET /api/v1/messages/contacts?q=alice&per_page=50&page=1
Scope: messages:read

q recherche une correspondance dans le nom ou l’adresse e-mail. Les résultats sont paginés (per_page de 1 à 100, 50 par défaut) et accompagnés d’un bloc pagination (total, per_page, current_page, last_page). Vous pouvez ainsi parcourir un grand carnet d’adresses jusqu’au bout au lieu de vous arrêter à la première page.

Créer un contact

POST /api/v1/messages/contacts
Scope: messages:write
{
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "company": "Analytical Engines",
  "job_title": "Mathematician",
  "phone": "+1 555 0100",
  "address": "London",
  "birthday": "1815-12-10",
  "notes": "Met at the conference"
}

Seul email est obligatoire. Si un contact avec cette adresse existe déjà, le contact existant est renvoyé sans modification. La création ne produit jamais de doublon et n’écrase pas les informations enregistrées.

Importer en masse

POST /api/v1/messages/contacts/import
Scope: messages:write
{
  "content_base64": "<base64 of your .csv or .vcf file>",
  "format": "csv"
}

Envoyez le fichier encodé en base64 avec format défini sur csv ou vcf (10 MB maximum après décodage). La réponse indique le nombre de lignes appliquées et le nombre de lignes ignorées faute d’adresse e-mail utilisable :

{ "imported": 128, "skipped": 3 }

Les en-têtes de colonnes des exportations Google, Outlook, Apple et Roundcube sont reconnus automatiquement. La plupart des exportations peuvent donc être importées sans aucune modification.

Exporter

GET /api/v1/messages/contacts/export?format=vcard
Scope: messages:read

Renvoie l’intégralité du carnet d’adresses sous la forme d’un fichier unique encodé en base64 :

{ "format": "vcard", "content_base64": "..." }

Utilisez format=csv pour obtenir un fichier adapté aux feuilles de calcul ou format=vcard pour obtenir un fichier .vcf à charger dans un autre client de messagerie.

Groupes de contacts

Les groupes sont des listes de distribution dans le carnet d’adresses. Chemin de base : /api/v1/messages/contact-groups

Voir qui appartient à un groupe

GET /api/v1/messages/contact-groups/42/members?per_page=50&page=1
Scope: messages:read

Renvoie les contacts du groupe, avec les mêmes champs épurés que dans la liste des contacts, ainsi qu’un bloc pagination et le contact_count total du groupe. Vous pouvez ainsi lire la composition du groupe au lieu de la modifier à l’aveugle.

Ajouter ou retirer des membres

POST /api/v1/messages/contact-groups/42/members
Scope: messages:write
{ "contact_ids": [11, 12, 13] }

L’ajout est idempotent : un contact déjà présent dans le groupe reste inchangé. Seuls les contacts appartenant à la même boîte mail peuvent être ajoutés. Chaque requête d’ajout ou de retrait accepte entre 1 et 200 identifiants de contact. Les lots plus grands doivent être divisés en plusieurs requêtes.

Outils MCP

Le même carnet d’adresses est accessible aux agents d’IA par MCP, aussi bien sur le serveur stdio privé que sur le serveur MCP public :

Les outils d’écriture nécessitent toujours la portée d’écriture du jeton de messages. Un administrateur MCP en hébergement local peut également exiger une approbation explicite pour les actions d’écriture. Un agent peut ainsi consulter les contacts sans pouvoir les modifier.

Articles associés

• Contacts dans le webmail
• Présentation de l’API REST TrekMail pour les développeurs
• Création et gestion des jetons d’API
• Portées de l’API et autorisations des plans
• Connexion des agents d’IA à TrekMail via MCP