Gestionar equipos White Label con API y MCP

Las cuentas White Label se pueden gestionar sin volver al panel. La API REST y el servidor MCP abarcan el estado de configuración de la cuenta, los clientes y miembros del equipo, los roles, el acceso a dominios, las invitaciones, las suspensiones, las eliminaciones, las restauraciones y el historial de actividad. La personalización de marca forma parte del mismo conjunto de herramientas White Label y tiene su propia guía de personalización de marca.

El límite importante es sencillo: una conexión nunca puede conceder más acceso del que ya tiene la persona que está detrás. Un administrador limitado a ciertos dominios no puede invitar a alguien a dominios no relacionados, y un rol personalizado no puede conceder permisos que la persona que realiza la llamada no posee.

Qué está disponible

El catálogo completo de MCP contiene ahora 261 herramientas mediante stdio y hasta 260 herramientas mediante HTTP alojado. White Label aporta 20 herramientas: siete para la personalización de marca y 13 para la gestión de cuentas, miembros y actividad.

Estas herramientas no se cargan para todo el mundo. TrekMail evalúa en tiempo real el derecho de la cuenta a White Label, la membresía actual de la persona, el token o la concesión OAuth, cualquier restricción de dominio, los conjuntos de herramientas seleccionados y la configuración local de seguridad antes de crear tools/list. Una conexión sin acceso a White Label no recibe los esquemas en absoluto.

Estados del derecho de acceso

Con acceso de lectura a White Label, llama a GET /api/v1/white-label o a la herramienta get_white_label para distinguir active del modo de solo lectura grace, y para consultar el progreso de la configuración y la fecha límite del periodo de gracia. Una cuenta no disponible no puede llamar a ese endpoint: cuando una credencial almacenada sigue incluyendo un ámbito de White Label que la cuenta ya no puede usar, la API devuelve scope_blocked_by_entitlement y explica dónde reactivarlo.

Ámbitos

El endpoint de actividad de un miembro necesita tanto activity:read como members:read, porque su respuesta contiene un registro del miembro además de la actividad. La conexión OAuth alojada utiliza el selector tools:white_label para solicitar esta familia de herramientas; los ámbitos REST efectivos siguen estando limitados por la cuenta y la membresía.

Para un servidor MCP autoalojado, añade white_label a TREKMAIL_TOOLSETS cuando utilices una lista de conjuntos de herramientas permitidos. Las herramientas de escritura también respetan los controles locales de seguridad descritos a continuación.

Endpoints REST

Todas las rutas están bajo https://trekmail.net/api/v1.

Cada escritura de esta tabla requiere una cabecera Idempotency-Key. Repetir la misma solicitud con la misma clave devuelve el resultado seguro original; los secretos de un solo uso presentes en una repetición, como un token de invitación, se ocultan. Reutilizar una clave con un cuerpo diferente devuelve idempotency_mismatch.

Lee primero el catálogo de acceso

No codifiques de forma fija los permisos de los roles en una integración. Consulta el catálogo de acceso antes de enviar una invitación o cambiar el acceso. Sus indicadores grantable reflejan la membresía actual de la persona que realiza la llamada y pueden cambiar cuando el propietario ajusta esa membresía.

Los roles que se ofrecen actualmente para invitaciones nuevas son:

• client - gestiona los dominios y buzones asignados sin ver la relación privada del revendedor con TrekMail.
• webmail_only - aparece en la lista del equipo, pero no recibe permisos para el panel.
• domain_admin - gestiona los dominios asignados y su DNS, pero no los buzones.
• mailbox_operator - gestiona los buzones dentro de los dominios asignados, pero no los propios dominios.
• read_only - puede inspeccionar la superficie permitida de la cuenta sin modificarla.
• custom - recibe únicamente los permisos enumerados en permissions.

Algunos roles requieren domain_ids explícitos; otros pueden usar all_domains. El catálogo de acceso indica qué regla se aplica. Si la persona que realiza la llamada intenta conceder un rol, permiso o conjunto de dominios más amplio, TrekMail devuelve scope_blocked_by_membership en lugar de restringir silenciosamente la invitación.

Invitar a un cliente

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 respuesta incluye el miembro, si la entrega del correo electrónico se realizó correctamente y una URL de invitación de un solo uso. Un problema de entrega no borra la invitación: el propietario puede copiar la URL o reenviarla más tarde.

Para un rol personalizado, lee grantable_permissions en el catálogo de acceso y envía los valores seleccionados en permissions. Se requiere al menos un permiso.

Seguir el estado del miembro

Cada respuesta de miembro incluye allowed_operations. Usa esa lista en lugar de hacer suposiciones:

• Una invitación pendiente se puede actualizar, suspender, reenviar o eliminar.
• Un miembro activo se puede actualizar, suspender o eliminar.
• Un miembro suspendido se puede actualizar, reanudar o eliminar.
• Un miembro eliminado se puede restaurar.
• La fila del propietario es visible como contexto, pero no se puede cambiar mediante estos endpoints.

La lista también se filtra para la persona que realiza la llamada. Está vacía para una conexión de solo lectura, para la membresía de la propia persona y para miembros cuyos permisos sean más amplios de lo que esa persona puede gestionar.

Las personas que realizan llamadas no pueden eliminarse ni suspenderse a sí mismas. Las personas delegadas tampoco pueden gestionar a un miembro cuyo acceso sea más amplio que el suyo. Las transiciones no válidas devuelven membership_state_conflict con una sugerencia para volver a leer el miembro.

Suspender o eliminar a alguien revoca las claves de API y de buzón creadas bajo esa membresía. Reanudar o restaurar la membresía nunca recupera esas claves antiguas; la persona debe volver a conectarse o crear credenciales nuevas.

Límites de actividad y privacidad

GET /white-label/activity devuelve invitaciones, cambios de roles y dominios, suspensiones, eliminaciones, restauraciones y acciones de seguridad relacionadas. Filtra con action, member_id y per_page.

GET /white-label/members/{id}/activity combina las acciones de la cuenta de ese miembro con los inicios de sesión recientes, incluidos la hora, la dirección IP, la ubicación aproximada, el navegador, el sistema operativo y el tipo de dispositivo. Esta ruta exige deliberadamente ambos ámbitos de lectura. Las personas con restricciones de dominio solo pueden solicitar miembros que estén completamente dentro de su límite de dominios; un miembro inaccesible se devuelve como 404, por lo que el endpoint no revela que existe otro inquilino o cliente.

Herramientas MCP

Las herramientas de invitación requieren TREKMAIL_ALLOW_SENDING=true en MCP stdio autoalojado. Las herramientas que cambian el acceso requieren TREKMAIL_ALLOW_DESTRUCTIVE=true; la eliminación también requiere confirm_remove=true. Estos interruptores son controles locales de seguridad, no permisos adicionales de la API. MCP alojado aplica su propia política de seguridad aprobada.

Las herramientas crean claves de idempotencia deterministas cuando no proporcionas una. Indicar tu propio idempotency_key resulta útil cuando un flujo de trabajo puede reiniciarse en un proceso diferente.

Un flujo de automatización seguro

1. Llama a get_white_label. Detente ante scope_blocked_by_entitlement; en una respuesta grace correcta, continúa únicamente con lecturas.
2. Llama a get_white_label_access_catalog inmediatamente antes de conceder acceso.
3. Enumera o lee el miembro objetivo antes de modificarlo.
4. Comprueba allowed_operations, el rol previsto, los permisos y los identificadores de dominio.
5. Usa una clave de idempotencia estable para la escritura.
6. Vuelve a leer el miembro e informa del estado resultante y de los permisos efectivos.
7. Consulta la actividad de White Label cuando necesites un registro de auditoría del cambio.

Errores que indican qué hacer