Alias de domaine via API et MCP

Un alias de domaine permet à un domaine de suivre les adresses de réception d’un autre. Si hello@company.example peut recevoir des e-mails, hello@brand.example peut les acheminer au même endroit sans créer ni gérer une deuxième boîte ou un deuxième alias.

Cette fonction sert uniquement à la réception. Elle ne crée pas d’adresse d’expédition, ne modifie pas SMTP et ne permet à personne d’envoyer au nom du domaine connecté.

Quand cette fonction est utile

Les alias de domaine conviennent aux entreprises qui possèdent plusieurs domaines de marque, un ancien domaine recevant encore les messages des clients ou des domaines nationaux distincts devant partager les mêmes noms de boîtes.

Par exemple :

hello@brand.example   → hello@company.example
billing@brand.example → billing@company.example

La partie avant @ reste strictement identique. Si l’adresse correspondante n’existe pas sur le domaine principal, TrekMail ne l’invente pas.

Forfaits et limites

Un domaine connecté ne peut suivre qu’un seul domaine principal à la fois. Un domaine principal peut desservir plusieurs domaines connectés, dans la limite ordinaire de domaines du compte. Un domaine ne peut pas être simultanément connecté et principal, ce qui simplifie le routage et évite les boucles.

Les deux domaines doivent appartenir au même compte, utiliser TrekMail pour le courrier entrant, être actifs et disposer d’enregistrements MX fonctionnels. Si le forfait, le compte ou l’état DNS change ensuite, TrekMail conserve la connexion enregistrée, mais suspend la livraison jusqu’au rétablissement des conditions requises.

Ce qui reste prioritaire

L’alias de domaine intervient seulement après la vérification par TrekMail des adresses exactes déjà configurées sur le domaine connecté. Les boîtes, alias, adresses de transfert, transferts de boîte et réglages catch-all existants conservent leur priorité documentée.

Ainsi, une règle volontaire pour sales@brand.example n’est pas remplacée discrètement par sales@company.example.

API REST

Les trois endpoints utilisent l’ID du domaine connecté :

L’endpoint conserve le chemin d’origine /matching-addresses afin de ne pas perturber les intégrations existantes. Le tableau de bord et la documentation emploient le terme plus clair du secteur alias de domaine.

PUT et DELETE exigent un en-tête Idempotency-Key. Vous pouvez répéter sans risque une même requête réussie avec la même clé.

Connecter un domaine

PUT /api/v1/domains/42/matching-addresses
Authorization: Bearer tm_live_...
Idempotency-Key: matching-brand-company-v1
Content-Type: application/json

{
  "primary_domain_id": 7
}

Lire le résultat

{
  "configured": true,
  "enabled": true,
  "delivering": true,
  "status": "delivering",
  "paused_reason": null,
  "alias_domain": {
    "id": 42,
    "domain": "brand.example"
  },
  "primary_domain": {
    "id": 7,
    "domain": "company.example"
  },
  "primary_domain_restricted": false
}

configured indique si la connexion est enregistrée. delivering indique si elle fonctionne actuellement. Vérifiez les deux au lieu de considérer une ligne enregistrée comme preuve que le courrier circule.

Lorsqu’un jeton peut accéder au domaine connecté, mais pas au domaine principal, la réponse définit primary_domain_restricted sur true et masque l’identité du domaine principal. Elle ne révèle jamais un domaine absent de la liste d’autorisation du jeton.

États de livraison

Outils MCP

Le même processus est disponible avec trois outils de domaine :

• get_domain_alias : consulter la connexion enregistrée et l’état de livraison en direct ;
• set_domain_alias : connecter ou modifier le domaine principal ;
• remove_domain_alias : le déconnecter après confirm_remove: true.

Le MCP hébergé applique les autorisations approuvées pendant OAuth. L’administrateur d’un MCP hébergé localement peut exiger une approbation explicite pour les écritures. Les deux méthodes appliquent le forfait du compte, les champs d’application du jeton, la liste d’autorisation des domaines et la validation côté serveur.

Les noms des outils et les titres destinés aux clients emploient alias de domaine. L’endpoint REST conserve son chemin d’origine pour assurer la compatibilité.

Suppression sûre et rétrogradations

Supprimer une connexion ne supprime ni domaine ni boîte. Les boîtes exactes, alias, adresses de transfert et règles catch-all restent inchangés. Les adresses sans correspondance qui dépendaient uniquement de cette fonction peuvent commencer à rejeter les messages ; examinez donc le domaine avant de confirmer la suppression.

La suppression d’un domaine connecté retire automatiquement sa connexion. TrekMail refuse de supprimer un domaine principal tant que des domaines connectés en dépendent ; déconnectez-les d’abord.

Après une rétrogradation vers Nano, la connexion reste enregistrée, mais cesse de livrer. Le retour à Starter ou à une offre supérieure la rétablit sans nouvelle saisie du domaine principal.

Journal d’audit

Chaque modification par API ou MCP figure sous Agents IA et API → Journal d’audit. Les événements de connexion et de modification enregistrent les deux ID de domaine, l’ancien domaine principal le cas échéant, le jeton intervenant, l’ID de requête et l’heure. La suppression consigne la connexion retirée. Aucun contenu d’e-mail ni identifiant n’est enregistré dans ces événements.

Liste de dépannage

1. Confirmez que les deux domaines sont Actifs et utilisent TrekMail pour le courrier entrant.
2. Vérifiez la validité des enregistrements MX des deux domaines.
3. Confirmez que le compte utilise Starter, Pro ou Agency.
4. Examinez ensemble configured, delivering, status et paused_reason.
5. Vérifiez si une boîte exacte, un alias, une adresse de transfert ou une règle catch-all contrôle déjà l’adresse.
6. Consultez dans le journal d’audit la dernière connexion, modification ou suppression.

Articles connexes

• Présentation des forfaits TrekMail
• Champs d’application de l’API et autorisations des forfaits
• Présentation de l’API REST TrekMail
• Connecter des agents IA à TrekMail via MCP
• Acheminer le courrier entrant d’un domaine
• Présentation des alias de messagerie