Espaces de travail

Les espaces de travail (tenants) sont des environnements isolés pour vos opérations d'email. Chaque espace de travail possède ses propres domaines, abonnés, clés API et facturation. Un seul compte utilisateur peut appartenir à plusieurs espaces de travail.

Les sous-espaces organisent, les tenants séparentCopier le lien de la section

Un sous-espace de travail (/v1/account/workspaces) ne fait qu'organiser les ressources au sein d'un seul tenant, avec les rôles existants. Ce n'est pas une frontière de facturation, de délivrabilité ou de sécurité. Les éléments suivants appartiennent toujours au tenant :

• Facturation : forfait, abonnement et factures
• La liste de suppression
• Les limites et quotas d'envoi
• Les IP d'envoi et la réputation de l'expéditeur
• La sécurité des clés API

Si vous exploitez une entreprise indépendante ou servez un client distinct, créez pour lui un tenant séparé, et non un sous-espace de travail. Sinon, ce client partage la liste de suppression, les limites d'envoi et la réputation de tous les autres dans le tenant.

Niveaux de vérificationCopier le lien de la section

Chaque espace de travail dispose d'un niveau de vérification qui détermine les capacités d'envoi :

Lister les espaces de travailCopier le lien de la section

Obtenez tous les espaces de travail auxquels l'utilisateur actuel appartient :

GET https://api.mail.land/v1/account/tenants

curl https://api.mail.land/v1/account/tenants \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

[
  {
    "publicId": "k3m9x2p7qw4rtz",
    "name": "My Company",
    "role": "owner",
    "isActive": true,
    "status": "active"
  },
  {
    "publicId": "t2p9k4m7x1n6w3",
    "name": "Client Project",
    "role": "member",
    "isActive": true,
    "status": "active"
  }
]

La réponse est un tableau brut, pas { "tenants": [...] }. Il n'y a pas de roleName, verificationLevel, verificationLevelName, isCurrent ni createdAt ici, isActive et status remplacent isCurrent, et le niveau de vérification est récupéré séparément (voir Facturation). id est l'identifiant numérique interne du tenant ; publicId est la valeur à utiliser dans les appels API et les interfaces (le champ numérique id n'est montré ici que parce que l'API actuelle le renvoie : ne construisez pas de logique client autour de lui, car il est en cours de suppression des réponses côté client).

Créer un espace de travailCopier le lien de la section

POST https://api.mail.land/v1/account/tenants

{
  "name": "New Project",
  "description": "Optional workspace description"
}

curl -X POST https://api.mail.land/v1/account/tenants \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "New Project" }'

RéponseCopier le lien de la section

Renvoie 201 Created avec la même forme que la réponse de Changer d'espace de travail : de nouveaux tokens limités au nouvel espace de travail, plus l'enregistrement de l'espace de travail imbriqué sous tenant :

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_new_token...",
  "expiresAt": "2026-02-17T13:00:00Z",
  "tenant": {
    "publicId": "u6w1m8k3p5x9n2",
    "name": "New Project",
    "role": "owner",
    "isActive": true,
    "status": "active"
  }
}

L'utilisateur créateur se voit automatiquement attribuer le rôle Owner. Il n'y a pas de verificationLevel/verificationLevelName dans cette réponse : voir Facturation pour l'état de vérification/politique.

Changer d'espace de travailCopier le lien de la section

Basculez l'espace de travail actif pour les appels API suivants :

POST https://api.mail.land/v1/account/tenants/switch

{
  "tenantId": "t2p9k4m7x1n6w3",
  "refreshToken": "rt_a1b2c3d4e5..."
}

refreshToken est facultatif : s'il est omis, la valeur du cookie de refresh token est utilisée à la place. tenantId est le publicId de l'espace de travail issu de Lister les espaces de travail.

curl -X POST https://api.mail.land/v1/account/tenants/switch \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "t2p9k4m7x1n6w3" }'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_new_token...",
  "expiresAt": "2026-09-25T15:00:00Z",
  "tenant": {
    "publicId": "t2p9k4m7x1n6w3",
    "name": "Client Project",
    "role": "member",
    "isActive": true,
    "status": "active"
  }
}

Le changement d'espace de travail émet de nouveaux tokens limités à l'espace de travail cible. Les champs de tenant ont la même forme que la réponse de Lister les espaces de travail, imbriqués sous tenant plutôt qu'aplatis en tenantId/tenantName/role.

Mettre à jour l'espace de travailCopier le lien de la section

Mettre à jour les paramètres de l'espace de travail actuel :

PUT https://api.mail.land/v1/account/tenants/current

{
  "name": "Updated Project Name",
  "description": "Optional workspace description"
}

name fait 2 à 100 caractères ; description est facultatif, jusqu'à 500 caractères.

curl -X PUT https://api.mail.land/v1/account/tenants/current \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Updated Project Name" }'

Seuls les Owners et Admins peuvent mettre à jour l'espace de travail. Les Members, Viewers et clés API reçoivent un 403 INSUFFICIENT_PERMISSIONS typé (avec la permission manquante, tenant.edit, dans details.permission).

RéponseCopier le lien de la section

Retourne 200 OK :

{
  "publicId": "t2p9k4m7x1n6w3",
  "name": "Updated Project Name",
  "description": "Optional workspace description",
  "status": "Active",
  "createdAt": "2026-01-15T08:00:00Z"
}

Contexte de l'espace de travailCopier le lien de la section

Toutes les requêtes API sont limitées à l'espace de travail actif. L'espace de travail est déterminé par le claim d'espace de travail actif du token. Les ressources (domaines, abonnés, campagnes, clés API) sont isolées entre les espaces de travail.

Lors de l'utilisation de clés API, chaque clé est limitée à un seul espace de travail. Aucun changement d'espace de travail n'est nécessaire : la clé détermine automatiquement le contexte.

Réponses d'erreurCopier le lien de la section

Prochaines étapesCopier le lien de la section

• Gestion d'équipe : inviter des membres dans votre espace de travail
• Facturation : gérer l'abonnement de l'espace de travail
• Authentification : gestion des tokens et des sessions
• Clés API : créer des clés API limitées à un espace de travail