Gérer les équipes White Label avec API et MCP

Les comptes White Label peuvent être gérés sans revenir au tableau de bord. L'API REST et le serveur MCP couvrent l'état de configuration du compte, les clients et les membres de l'équipe, les rôles, l'accès aux domaines, les invitations, les suspensions, les suppressions, les restaurations, les limites de stockage des clients et l'historique des activités. La personnalisation de la marque fait partie du même ensemble d'outils White Label et possède son propre guide de personnalisation de la marque.

La limite importante est simple: une connexion ne peut jamais accorder plus d'accès que la personne qui l'utilise n'en possède déjà. Un gestionnaire limité à certains domaines ne peut pas inviter quelqu'un sur des domaines sans rapport, et un rôle personnalisé ne peut pas accorder des autorisations que l'appelant ne détient pas.

Fonctionnalités disponibles

Le catalogue MCP complet contient désormais 284 outils via stdio et jusqu'à 283 outils via HTTP hébergé. White Label fournit 23 outils: sept pour la personnalisation de la marque, 13 pour la gestion des comptes, des membres et des activités, et trois pour les limites de stockage des clients.

Ces outils ne sont pas chargés pour tout le monde. TrekMail évalue en temps réel le droit White Label du compte, l'adhésion actuelle de la personne, le jeton ou l'autorisation OAuth, toute restriction de domaine, les ensembles d'outils sélectionnés et les paramètres de sécurité locaux avant de générer tools/list. Une connexion sans accès à White Label ne reçoit aucun schéma.

États des droits

Avec un accès en lecture à White Label, appelez GET /api/v1/white-label ou l'outil get_white_label pour distinguer l'état active du mode grace en lecture seule, et pour consulter la progression de la configuration et l'échéance du délai de grâce. Un compte indisponible ne peut pas appeler cet endpoint: lorsqu'un identifiant enregistré mentionne encore une portée White Label que le compte ne peut plus utiliser, l'API renvoie scope_blocked_by_entitlement et indique où la réactiver.

Portées

L'endpoint d'activité d'un membre nécessite à la fois activity:read et members:read, car sa réponse contient une fiche de membre ainsi que l'activité. La connexion OAuth hébergée utilise le sélecteur tools:white_label pour demander cette famille d'outils; les portées REST effectives restent limitées par le compte et l'adhésion.

Pour un serveur MCP auto-hébergé, ajoutez white_label à TREKMAIL_TOOLSETS lorsque vous utilisez une liste d'ensembles d'outils autorisés. Les outils d'écriture respectent également les protections de sécurité locales décrites ci-dessous.

Endpoints REST

Tous les chemins se trouvent sous https://trekmail.net/api/v1.

Chaque écriture de ce tableau nécessite un en-tête Idempotency-Key. Répéter la même requête avec la même clé renvoie le résultat sûr d'origine; les secrets à usage unique présents dans une répétition, comme un jeton d'invitation, sont masqués. Réutiliser une clé avec un corps différent renvoie idempotency_mismatch.

Lire d'abord le catalogue des accès

Ne codez pas en dur les autorisations des rôles dans une intégration. Appelez le catalogue des accès avant une invitation ou une modification d'accès. Ses indicateurs grantable reflètent l'adhésion actuelle de l'appelant et peuvent changer lorsque le propriétaire modifie cette adhésion.

Les rôles actuellement proposés pour les nouvelles invitations sont:

• client - gère les domaines et les boîtes mail attribués sans voir la relation privée du revendeur avec TrekMail.
• webmail_only - apparaît dans la liste de l'équipe, mais ne reçoit aucune autorisation pour le tableau de bord.
• domain_admin - gère les domaines attribués et leur DNS, mais pas les boîtes mail.
• mailbox_operator - gère les boîtes mail dans les domaines attribués, mais pas les domaines eux-mêmes.
• read_only - peut examiner la partie autorisée du compte sans la modifier.
• custom - reçoit uniquement les autorisations énumérées dans permissions.

Certains rôles exigent des domain_ids explicites; d'autres peuvent utiliser all_domains. Le catalogue des accès indique la règle applicable. Si l'appelant tente d'accorder un rôle, une autorisation ou un ensemble de domaines plus large, TrekMail renvoie scope_blocked_by_membership au lieu de restreindre silencieusement l'invitation.

Inviter un client

curl -s -X POST "https://trekmail.net/api/v1/white-label/members" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invite-northwind-admin-20260904" \
  -d '{
    "email": "admin@northwind.example",
    "role": "client",
    "all_domains": false,
    "domain_ids": [123, 124],
    "note": "Northwind primary contact"
  }'

La réponse inclut le membre, l'état de réussite de l'envoi de l'e-mail et une URL d'invitation à usage unique. Un problème de livraison n'efface pas l'invitation: le propriétaire peut copier l'URL ou la renvoyer plus tard.

Pour un rôle personnalisé, lisez grantable_permissions dans le catalogue des accès et envoyez les valeurs sélectionnées dans permissions. Au moins une autorisation est requise.

Suivre l'état du membre

Chaque réponse concernant un membre inclut allowed_operations. Utilisez cette liste au lieu de faire des suppositions:

• Une invitation en attente peut être mise à jour, suspendue, renvoyée ou supprimée.
• Un membre actif peut être mis à jour, suspendu ou supprimé.
• Un membre suspendu peut être mis à jour, réactivé ou supprimé.
• Un membre supprimé peut être restauré.
• La ligne du propriétaire est visible à titre de contexte, mais elle ne peut pas être modifiée par ces endpoints.

La liste est également filtrée pour l'appelant actuel. Elle est vide pour une connexion en lecture seule, pour l'adhésion propre de l'appelant et pour les membres dont les autorisations dépassent ce que l'appelant peut gérer.

Les appelants ne peuvent ni se supprimer ni se suspendre eux-mêmes. Les appelants délégués ne peuvent pas non plus gérer un membre dont l'accès est plus étendu que le leur. Les transitions non valides renvoient membership_state_conflict avec une indication invitant à relire le membre.

La suspension ou la suppression d'une personne révoque les clés d'API et de boîte mail créées dans le cadre de cette adhésion. La reprise ou la restauration de l'adhésion ne rétablit jamais ces anciennes clés; la personne doit se reconnecter ou créer de nouveaux identifiants.

Limites relatives à l'activité et à la confidentialité

GET /white-label/activity renvoie les invitations, les changements de rôle et de domaine, les suspensions, les suppressions, les restaurations et les actions de sécurité associées. Filtrez avec action, member_id et per_page.

GET /white-label/members/{id}/activity combine les actions de ce membre sur le compte avec ses connexions récentes, notamment l'heure, l'adresse IP, la localisation approximative, le navigateur, le système d'exploitation et le type d'appareil. Cette route exige volontairement les deux portées de lecture. Les appelants soumis à des restrictions de domaine peuvent uniquement demander des membres qui se trouvent entièrement dans leur périmètre de domaines; un membre inaccessible est renvoyé sous la forme 404, afin que l'endpoint ne révèle pas l'existence d'un autre locataire ou client.

Limites de stockage des clients

Une limite de stockage client donne aux domaines d'un client une seule quantité d'espace, en MB, pour leurs boîtes mail et Drive. Pour son fonctionnement dans le tableau de bord, voir Une limite de stockage dédiée pour chaque client. Une limite dont personne dans l'équipe n'a les domaines, par exemple créée ici avant l'invitation du client, apparaît sur la page Équipe et clients dans Limites de stockage sans client.

• La lecture exige members:read. Un appelant limité à certains domaines ne voit que les limites dont tous les domaines sont les siens. La limite d'un autre client, ou une limite qui couvre aussi un domaine auquel il n'a pas accès, n'apparaît pas dans la liste, et sa lecture renvoie 404, comme si l'identifiant n'existait pas.
• La modification exige members:write et un appelant qui a accès à tous les domaines du compte. Un membre limité à certains domaines reçoit 403 scope_blocked_by_membership; une clé limitée à certains domaines reçoit 403 token_resource_constrained.
• POST suit la page Équipe et clients: les domaines sans limite en reçoivent une nouvelle (201); si les domaines partagent déjà une limite, celle-ci est modifiée et les domaines indiqués sans limite la rejoignent (200).
• PATCH accepte storage_limit_mb, domain_ids, ou les deux. domain_ids remplace l'ensemble complet, et les domaines laissés de côté reviennent au stockage du compte.
• Chaque limite renvoie storage_limit_mb, domain_ids, allocated_mb (tailles fixes des boîtes), pending_invites_mb (tailles fixes des invitations ouvertes), pool_mb (ce que se partagent les boîtes en stockage partagé), used_bytes et member_ids.

Chaque fiche de membre contient client_limit: la limite unique qui couvre tous les domaines du membre, avec id, storage_limit_mb, allocated_mb et used_bytes, ou null. Pour un appelant limité à certains domaines, il vaut aussi null lorsque cette limite couvre un domaine auquel il n'a pas accès.

La taille de chaque boîte se règle avec PATCH /mailboxes/{id}/storage (mailboxes:write) ou l'outil set_mailbox_storage, décrits dans le guide de l'API REST.

Outils MCP

Les outils d'invitation nécessitent TREKMAIL_ALLOW_SENDING=true sur un serveur MCP stdio auto-hébergé. Les outils qui modifient les accès et ceux des limites de stockage des clients nécessitent TREKMAIL_ALLOW_DESTRUCTIVE=true; supprimer un membre ou retirer une limite nécessite également confirm_remove=true. set_mailbox_storage, qui ne fait pas partie de l'ensemble White Label, a la même exigence. Ces options sont des contrôles de sécurité locaux, et non des autorisations d'API supplémentaires. Le serveur MCP hébergé applique sa propre politique de sécurité approuvée.

Les outils créent des clés d'idempotence déterministes lorsque vous n'en fournissez pas. Fournir votre propre idempotency_key est utile lorsqu'un flux de travail peut redémarrer dans un autre processus.

Un flux d'automatisation sûr

1. Appelez get_white_label. Arrêtez-vous sur scope_blocked_by_entitlement; dans une réponse grace réussie, poursuivez uniquement avec des lectures.
2. Appelez get_white_label_access_catalog immédiatement avant d'accorder l'accès.
3. Répertoriez ou lisez le membre cible avant de le modifier.
4. Vérifiez allowed_operations, le rôle prévu, les autorisations et les identifiants de domaine.
5. Utilisez une clé d'idempotence stable pour l'écriture.
6. Relisez le membre et indiquez l'état obtenu ainsi que les autorisations effectives.
7. Consultez l'activité White Label lorsque vous avez besoin d'une trace d'audit de la modification.

Erreurs qui indiquent la marche à suivre

Articles connexes

• Guide de l'API et de MCP pour la marque White Label
• Portées de l'API et autorisations des offres
• Créer et gérer des jetons d'API
• Connecter des agents d'IA à TrekMail via MCP
• Une limite de stockage dédiée pour chaque client