Guide de l’API et de MCP pour la marque White Label

La marque White Label par domaine peut être configurée de bout en bout via l’API et MCP, sans utiliser le tableau de bord. Un agent peut définir le nom et les couleurs de la marque d’un domaine, importer des logos, activer des hôtes de tableau de bord et de webmail avec marque, lire les enregistrements DNS à créer et demander une vérification DNS. Il s’agit de la même configuration que celle écrite par l’onglet Marque du tableau de bord; l’API permet simplement à un agent ou un script de le faire pour vous.

La marque est configurée par domaine (le domaine est l’id numérique). Un domaine peut avoir sa propre marque (custom), hériter de la valeur par défaut du compte (inherit) ou être désactivé. L’API renvoie les noms d’hôte avec marque et les enregistrements CNAME du domaine. Copiez toujours exactement les enregistrements renvoyés. Ne construisez pas un nom d’hôte ou une cible CNAME à partir d’un exemple de ce guide.

Contrôle de l’add-on

Chaque offre de messagerie inclut un essai et un aperçu White Label de 30 jours. Profitez-en pour configurer la marque et tester l’expérience avant de proposer les hôtes avec marque à vos clients.

L’API applique les mêmes droits que le tableau de bord White Label :

• Essai actif ou add-on payant : les portées de lecture et d’écriture sont disponibles. Les hôtes activés passent de pending_dns à active après la résolution de leur CNAME et l’émission du certificat SSL.
• Délai de grâce après annulation : le propriétaire du compte conserve un accès en lecture seule jusqu’à l’heure hard_delete_at affichée. Les écritures sont bloquées et les connexions déléguées perdent immédiatement leur accès White Label.
• Aucun droit actif : les portées White Label sont retirées des autorisations effectives de la référence et ses outils MCP ne sont pas chargés.

Si un jeton enregistré possédait autrefois une portée White Label, mais que le droit n’est plus actif, l’API renvoie 403 scope_blocked_by_entitlement avec une prochaine étape directe. Créer un jeton plus large ne contourne pas ce droit.

Portées requises

La marque possède ses propres portées. Ainsi, une automatisation qui gère des domaines ordinaires ne peut pas voir ni modifier accidentellement l’identité du revendeur.

Endpoints REST

Tous les endpoints se trouvent sous https://trekmail.net/api/v1. {id} est l’id numérique du domaine.

Tous les endpoints sauf verify-dns et preview renvoient la même charge de marque que GET. Un seul aller-retour suffit donc à connaître le nouvel état.

Charge de marque

{
  "data": {
    "mode": "custom",
    "white_label_addon_active": true,
    "brand": {
      "id": 42,
      "name": "Northwind Mail",
      "primary_color": "#2563eb",
      "accent_color": "#10b981",
      "logo_url": "https://trekmail.net/storage/branding/42/light.png",
      "logo_dark_url": "https://trekmail.net/storage/branding/42/dark.png",
      "favicon_url": "https://trekmail.net/storage/branding/42/favicon.png",
      "support_email": "support@northwind.com",
      "support_url": "https://help.northwind.com",
      "sender_email": "noreply@northwind.com"
    },
    "mail_zone": {
      "enabled": true,
      "domain": "northwind.com",
      "dns_status": "pending_dns",
      "client_hosts_status": "pending_dns",
      "records": [
        { "type": "TXT", "name": "spf.northwind.com", "value": "v=spf1 include:spf.trekmail.net -all" },
        { "type": "CNAME", "name": "imap.northwind.com", "value": "imap.trekmail.net" },
        { "type": "CNAME", "name": "dav.northwind.com", "value": "trekmail.net" }
      ],
      "dav_url": "https://trekmail.net/dav/files/account/",
      "dav_ready": false,
      "cert_expires_at": null,
      "checked_at": "2026-08-29T06:20:11+00:00"
    },
    "hosts": [
      { "kind": "dashboard", "hostname": "dashboard.northwind.com", "subdomain_label": "dashboard", "enabled": true, "status": "pending_dns" },
      { "kind": "webmail", "hostname": "mail.northwind.com", "subdomain_label": "mail", "enabled": true, "status": "pending_dns" }
    ],
    "dns_records": [
      { "type": "CNAME", "name": "<returned dashboard host>", "value": "<returned CNAME target>", "proxied": false },
      { "type": "CNAME", "name": "<returned webmail host>", "value": "<returned CNAME target>", "proxied": false }
    ],
    "cname_target": "<returned CNAME target>"
  }
}

brand et mail_zone valent null lorsque mode est off. mail_zone.enabled est l’intention enregistrée; utilisez ses deux champs d’état pour distinguer les états en attente, actifs, en échec et de nettoyage. Le status de l’hôte indique si le DNS et SSL sont encore en attente ou si l’hôte est actif. Les valeurs de remplacement de l’exemple sont volontaires : les valeurs renvoyées dans dns_records et cname_target sont les seules à publier.

mail_zone décrit les noms d’hôte de messagerie propres à la marque (voir plus loin). dns_status couvre l’état DNS de la messagerie et client_hosts_status couvre l’état des hôtes clients et des certificats; les deux peuvent être off, pending_dns, active ou failed. records répertorie les enregistrements DNS que votre fournisseur doit publier. dav_url peut toujours être utilisé en toute sécurité : il reste sur TrekMail jusqu’à ce que le certificat DAV avec marque et la route web restreinte soient prêts. Ne changez que lorsque dav_ready devient true; cert_expires_at indique alors l’expiration de certificat la plus proche pour les hôtes d’applications de messagerie avec marque.

Lire la marque actuelle

curl -s "https://trekmail.net/api/v1/domains/123/branding" \
  -H "Authorization: Bearer tm_live_your_token"

Définir la marque (fusion partielle)

PATCH est une fusion partielle. Les champs omis sont conservés; envoyez donc uniquement ceux que vous modifiez.

curl -s -X PATCH "https://trekmail.net/api/v1/domains/123/branding" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-123-initial" \
  -d '{
    "mode": "custom",
    "name": "Northwind Mail",
    "primary_color": "#2563eb",
    "accent_color": "#10b981",
    "dashboard_enabled": true,
    "dashboard_label": "dashboard",
    "webmail_enabled": true,
    "webmail_label": "mail",
    "mail_zone_enabled": true,
    "support_email": "support@northwind.com",
    "support_url": "https://help.northwind.com",
    "sender_email": "noreply@northwind.com"
  }'

Champs du corps :

Importer un logo

Les logos sont envoyés en base64. slot peut être light, dark ou favicon. PNG et JPG sont acceptés pour tous les emplacements, ainsi que ICO pour favicon. Taille maximale : 1 MB. SVG est refusé pour des raisons de sécurité. La valeur par défaut scope=domain ne modifie qu’un domaine en mode custom; elle ne suit jamais un profil hérité. Pour modifier volontairement le profil partagé depuis un domaine inherit, transmettez scope=account_default et utilisez un jeton branding:write sans restriction. Les jetons limités par domaine ne peuvent pas modifier la valeur par défaut du compte.

curl -s -X PUT "https://trekmail.net/api/v1/domains/123/branding/logo/light" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-123-logo-light" \
  -d "{\"content_base64\":\"$(base64 -w0 logo-light.png)\"}"

Supprimez un emplacement avec DELETE :

curl -s -X DELETE "https://trekmail.net/api/v1/domains/123/branding/logo/dark" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-logo-dark-remove"

Les deux opérations renvoient la charge de marque avec les valeurs logo_url / logo_dark_url / favicon_url mises à jour. PUT accepte scope dans le corps JSON; DELETE l’accepte comme paramètre de requête. Une modification implicite limitée au domaine sur un profil hérité renvoie 422 inherited_brand.

Vérifier le DNS

Après avoir créé les enregistrements CNAME (voir le flux ci-dessous), mettez la vérification en file d’attente :

curl -s -X POST "https://trekmail.net/api/v1/domains/123/branding/verify-dns" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-verify"

{ "data": { "status": "queued", "hosts": 2 } }

Cette opération s’exécute en arrière-plan. Relisez GET /branding et observez le status de l’hôte passer à active. Si White Label expire, la requête renvoie 403 scope_blocked_by_entitlement avec une indication de réactivation.

Elle revérifie également la zone de messagerie de la marque lorsqu’elle existe. mail_zone.dns_status et mail_zone.client_hosts_status évoluent donc lors du même appel. Vous n’avez pas besoin de l’appeler pour la zone : nous vérifions régulièrement les zones en attente et les activons quelques minutes après la résolution des enregistrements. verify-dns demande simplement cette vérification immédiatement, sans attendre le passage suivant.

Messagerie sur le domaine propre à la marque

mail_zone_enabled affiche le nom du revendeur dans les applications de messagerie et les clients de synchronisation DAV de ses clients. Activez-le, puis publiez tous les enregistrements renvoyés dans mail_zone.records. Ils comprennent un enregistrement TXT SPF ainsi que des enregistrements CNAME IMAP et DAV. Les noms et cibles exacts de votre réponse font autorité.

Utilisez un CNAME plutôt qu’un enregistrement A lorsque l’enregistrement renvoyé le demande et laissez le nuage Cloudflare gris. Les clients de messagerie et DAV doivent se connecter directement; un proxy DNS peut perturber les vérifications de certificats et les protocoles hors navigateur. La réponse indique tous les enregistrements à publier, n’ajoutez donc pas d’enregistrements de messagerie supposés.

Une fois les enregistrements résolus, TrekMail émet les certificats et active les noms d’hôte. Surveillez mail_zone.client_hosts_status jusqu’à active et mail_zone.dav_ready jusqu’à true. Continuez d’utiliser le dav_url renvoyé; il ne passe de l’adresse de la plateforme à celle avec marque que lorsque DAV peut être servi en toute sécurité. Si l’état de l’hôte indique failed, relancez la vérification DNS et ouvrez un ticket d’assistance si l’échec persiste.

Créer un aperçu réel

POST /branding/preview crée une URL valable 72 heures pour afficher l’expérience avec marque avant que le DNS soit actif :

curl -s -X POST "https://trekmail.net/api/v1/domains/123/branding/preview" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-preview"

La réponse contient une URL d’aperçu qui expire après 72 heures. Elle renvoie 422 no_brand lorsqu’il n’existe aucune marque à prévisualiser, car elle est désactivée ou n’a pas encore été configurée.

Supprimer la marque

curl -s -X DELETE "https://trekmail.net/api/v1/domains/123/branding?scope=domain" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-remove"

scope=domain efface uniquement ce domaine; scope=all efface la marque dans tout le compte. L’opération renvoie la charge de marque.

Outils MCP

Sept outils couvrent la marque dans le jeu de 20 outils white_label. Ils ne sont enregistrés que si la connexion possède une portée de marque effective et si White Label est disponible. L’outil de lecture nécessite branding:read; les six autres exigent branding:write. Un serveur MCP hébergé localement peut également exiger que son administrateur autorise les écritures.

get_domain_branding est en lecture seule. Pendant le délai de grâce après annulation du propriétaire, il reste disponible tandis que les six outils d’écriture disparaissent. Sans droit White Label, aucun de ces outils n’est annoncé dans tools/list.

Flux autonome de bout en bout

Si le DNS de votre domaine est chez Cloudflare, un agent peut faire passer un domaine sans marque à un hôte avec marque actif sans intervention humaine, car les outils DNS Cloudflare existants (apply_cloudflare_dns) peuvent écrire les CNAME renvoyés par get_domain_branding.

1. Définissez la marque. set_domain_branding(mode=custom, name, primary_color, accent_color, dashboard_enabled=true, webmail_enabled=true).
2. Importez des logos (facultatif). set_domain_brand_logo(slot="light", content_base64=…), puis répétez pour dark et favicon.
3. Lisez les enregistrements DNS. get_domain_branding → copiez le tableau dns_records renvoyé. Ne devinez pas et ne générez pas de valeurs.
4. Écrivez les CNAME. Publiez ces enregistrements avec le proxy désactivé. Dans Cloudflare, le nuage doit être gris pour permettre les validations DNS et SSL.
5. Vérifiez. verify_domain_branding_dns.
6. Interrogez. Rappelez get_domain_branding jusqu’à ce que le status de chaque hôte soit active.
7. Aperçu (facultatif). Utilisez create_branding_preview pour obtenir une URL de démonstration réelle avant de diriger les clients vers le domaine avec marque.

Exemple pratique (MCP)

set_domain_branding(
  domain_id=123,
  mode="custom",
  name="Northwind Mail",
  primary_color="#2563eb",
  accent_color="#10b981",
  dashboard_enabled=true,
  webmail_enabled=true,
  support_email="support@northwind.com",
  sender_email="noreply@northwind.com"
)

set_domain_brand_logo(domain_id=123, slot="light", content_base64="iVBORw0KGgo…")
set_domain_brand_logo(domain_id=123, slot="dark", content_base64="iVBORw0KGgo…")

get_domain_branding(domain_id=123)
# → Copy the returned dns_records exactly. Do not substitute an example host or target.

apply_cloudflare_dns(domain_ids=[123])   # writes the CNAMEs, proxy off

verify_domain_branding_dns(domain_id=123)

# poll until active
get_domain_branding(domain_id=123)
# → hosts[].status: "active"

create_branding_preview(domain_id=123)   # optional live demo

Demandez à l’agent de communiquer les noms d’hôte avec marque et leurs états finaux, afin de confirmer leur activation réelle et non un simple état pending_dns.

Points d’attention

• Les droits contrôlent les surfaces API et MCP. Un essai actif ou un add-on payant est nécessaire pour écrire. Le propriétaire dispose d’une période de récupération en lecture seule après l’annulation; tous les autres perdent immédiatement ces outils.
• PATCH est une fusion partielle. Les champs omis sont conservés. Pour modifier uniquement la couleur d’accentuation, envoyez {"accent_color":"#10b981"}. Il n’est pas nécessaire de renvoyer le nom, les logos ou les bascules.
• La réactivation depuis l’état désactivé exige mode. Si la marque est actuellement off, un PATCH sans mode ne la réactivera pas. Transmettez mode=custom (ou inherit) pour la réactiver.
• sender_email exige un domaine DKIM vérifié. L’adresse From doit appartenir à un domaine dont une clé DKIM a déjà été provisionnée sur le compte, sinon la mise à jour est refusée. Vérifiez le DKIM du domaine (retry_domain_dkim / get_dns_check) avant de définir un expéditeur personnalisé.
• Les logos sont en base64, ≤1 MB, sans SVG. Envoyez un fichier PNG ou JPG (ICO est aussi autorisé pour favicon) comme content_base64. SVG est refusé. Compressez d’abord les fichiers sources volumineux.
• Conservez les enregistrements CNAME renvoyés sans proxy. Un nuage Cloudflare orange ou un autre proxy CDN empêche la validation DNS et SSL. Publiez les dns_records tels qu’ils sont renvoyés, avec proxied:false.
• Les écritures nécessitent le bon accès. Tous les outils sauf get_domain_branding modifient des données. Utilisez donc la portée d’écriture requise et activez les écritures si l’administrateur de votre MCP hébergé localement a choisi de les protéger.

Articles connexes

• Configurer White Label Lite
• Présentation de White Label Lite et de son public
• Bonnes pratiques pour les ressources de marque White Label
• Gérer les clients et membres d’équipe White Label avec API et MCP
• Présentation de l’API
• Connecter les agents IA (MCP)