Espacios de Trabajo

Los espacios de trabajo (tenants) son entornos aislados para sus operaciones de correo electrónico. Cada espacio de trabajo tiene sus propios dominios, suscriptores, API keys y facturación. Una sola cuenta de usuario puede pertenecer a múltiples espacios de trabajo.

Los subespacios organizan, los tenants separanCopiar enlace de la sección

Un subespacio de trabajo (/v1/account/workspaces) solo organiza recursos dentro de un único tenant, con los roles existentes. No es un límite de facturación, de entregabilidad ni de seguridad. Lo siguiente pertenece siempre al tenant:

• Facturación: plan, suscripción y facturas
• La lista de supresión
• Los límites y cuotas de envío
• Las IP de envío y la reputación del remitente
• La seguridad de las API keys

Si gestiona un negocio independiente o atiende a un cliente distinto, cree para él un tenant aparte, no un subespacio. De lo contrario, ese cliente comparte la lista de supresión, los límites de envío y la reputación con todos los demás del tenant.

Niveles de VerificaciónCopiar enlace de la sección

Cada espacio de trabajo tiene un nivel de verificación que determina las capacidades de envío:

Listar Espacios de TrabajoCopiar enlace de la sección

Obtenga todos los espacios de trabajo a los que pertenece el usuario actual:

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 respuesta es un arreglo simple, no { "tenants": [...] }. No hay roleName, verificationLevel, verificationLevelName, isCurrent ni createdAt aquí, isActive y status reemplazan a isCurrent, y el nivel de verificación se obtiene por separado (vea Facturación). id es el identificador numérico interno del tenant; publicId es el valor a usar en llamadas de API e interfaces (el campo numérico id se muestra aquí solo porque la API actual lo devuelve: no construya lógica de cliente en torno a él, ya que está siendo eliminado de las respuestas orientadas al cliente).

Crear un Espacio de TrabajoCopiar enlace de la sección

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" }'

RespuestaCopiar enlace de la sección

Devuelve 201 Created con la misma forma que la respuesta de Cambiar espacio de trabajo: nuevos tokens vinculados al nuevo espacio de trabajo, además del registro del espacio de trabajo anidado bajo 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"
  }
}

Al usuario creador se le asigna automáticamente el rol Owner. No hay verificationLevel/verificationLevelName en esta respuesta: vea Facturación para el estado de verificación/política.

Cambiar de Espacio de TrabajoCopiar enlace de la sección

Cambie el espacio de trabajo activo para las siguientes llamadas a la API:

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

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

refreshToken es opcional: si se omite, se usa en su lugar el valor de la cookie de refresh token. tenantId es el publicId del espacio de trabajo de Listar espacios de trabajo.

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"
  }
}

Cambiar de espacio de trabajo emite nuevos tokens con alcance al espacio de trabajo de destino. Los campos de tenant tienen la misma forma que la respuesta de Listar espacios de trabajo, anidados bajo tenant en lugar de planos como tenantId/tenantName/role.

Actualizar Espacio de TrabajoCopiar enlace de la sección

Actualice la configuración del espacio de trabajo actual:

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

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

name tiene de 2 a 100 caracteres; description es opcional, hasta 500 caracteres.

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" }'

Solo los Owners y Admins pueden actualizar el espacio de trabajo. Los Members, Viewers y las API keys reciben un 403 INSUFFICIENT_PERMISSIONS tipado (con el permiso faltante, tenant.edit, en details.permission).

RespuestaCopiar enlace de la sección

Devuelve 200 OK:

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

Contexto del Espacio de TrabajoCopiar enlace de la sección

Todas las solicitudes a la API tienen alcance al espacio de trabajo activo. El espacio de trabajo se determina por el claim de espacio de trabajo activo del token. Los recursos (dominios, suscriptores, campañas, API keys) están aislados entre espacios de trabajo.

Al usar API keys, cada clave tiene alcance a un solo espacio de trabajo. No es necesario cambiar de espacio de trabajo: la clave determina el contexto automáticamente.

Respuestas de ErrorCopiar enlace de la sección

Próximos PasosCopiar enlace de la sección

• Administración de Equipo: invite miembros a su espacio de trabajo
• Facturación: administre la suscripción del espacio de trabajo
• Autenticación: administración de tokens y sesiones
• API Keys: cree API keys con alcance de espacio de trabajo