Guía de API y MCP para marca White Label

La marca White Label por dominio puede configurarse por completo mediante la API y MCP, sin usar el panel. Un agente puede definir el nombre y los colores de marca de un dominio, subir logotipos, activar hosts de panel y webmail con marca, leer los registros DNS que debe crear y solicitar la verificación DNS. Es la misma configuración que escribe la pestaña Marca del panel; la API permite que un agente o script lo haga por ti.

La marca se configura por dominio (el dominio es el id numérico). Un dominio puede tener su propia marca (custom), heredar el valor predeterminado de la cuenta (inherit) o estar desactivado. La API devuelve los nombres de host con marca y los registros CNAME del dominio. Copia siempre los registros devueltos de forma exacta. No construyas un nombre de host ni un destino CNAME a partir de un ejemplo de esta guía.

Control del complemento

Cada plan de correo incluye una prueba y vista previa de White Label de 30 días. Usa ese periodo para configurar la marca y probar la experiencia antes de ofrecer los hosts con marca a tus clientes.

La API aplica los mismos derechos que el panel White Label:

• Prueba activa o complemento de pago: están disponibles los alcances de lectura y escritura. Los hosts habilitados pasan de pending_dns a active después de que se resuelva su CNAME y se emita el certificado SSL.
• Periodo de gracia de cancelación: el propietario de la cuenta conserva el acceso de solo lectura hasta la hora hard_delete_at mostrada. La escritura se bloquea y las conexiones delegadas pierden de inmediato el acceso White Label.
• Sin derechos activos: los alcances White Label se eliminan de los permisos efectivos de la credencial y sus herramientas MCP no se cargan.

Si un token almacenado tuvo un alcance White Label pero los derechos ya no están activos, la API devuelve 403 scope_blocked_by_entitlement con el siguiente paso directo. Crear un token más amplio no evita este requisito.

Alcances necesarios

La marca tiene sus propios alcances. Así se evita que una automatización que administra dominios comunes vea o cambie por accidente la identidad del revendedor.

Endpoints REST

Todos los endpoints están bajo https://trekmail.net/api/v1. {id} es el id numérico del dominio.

Todos los endpoints excepto verify-dns y preview devuelven la misma carga de marca que GET, por lo que un único viaje de ida y vuelta muestra el nuevo estado.

Carga de marca

{
  "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 y mail_zone son null cuando mode es off. mail_zone.enabled es la intención guardada; usa sus dos campos de estado para distinguir los estados pendientes, activos, fallidos y de limpieza. El status del host indica si DNS y SSL siguen pendientes o si el host está activo. Los valores de marcador del ejemplo son deliberados: los valores devueltos en dns_records y cname_target son los únicos que deben publicarse.

mail_zone describe los nombres de host de correo propios de la marca (consulta más adelante). dns_status cubre el estado DNS del correo y client_hosts_status el estado del host del cliente y del certificado; ambos pueden ser off, pending_dns, active o failed. records enumera los registros DNS que debe publicar tu proveedor. dav_url siempre es seguro: permanece en TrekMail hasta que estén listos el certificado DAV con marca y la ruta web restringida. Cambia solo cuando dav_ready sea true; entonces cert_expires_at muestra la fecha de caducidad más próxima de los certificados de hosts de aplicaciones de correo con marca.

Leer la marca actual

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

Definir la marca (combinación parcial)

PATCH es una combinación parcial. Los campos omitidos se conservan, así que envía únicamente lo que quieras cambiar.

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

Campos del cuerpo:

Subir un logotipo

Los logotipos se envían en base64. slot puede ser light, dark o favicon. Se aceptan PNG y JPG en cualquier espacio, además de ICO para favicon. Máximo 1 MB. SVG se rechaza por seguridad. El valor predeterminado scope=domain solo cambia un dominio en modo custom; nunca sigue un perfil heredado. Para cambiar intencionadamente el perfil compartido a través de un dominio inherit, envía scope=account_default y usa un token branding:write sin restricción. Los tokens limitados por dominio no pueden cambiar el valor predeterminado de la cuenta.

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

Elimina un espacio con 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"

Ambas operaciones devuelven la carga de marca con logo_url / logo_dark_url / favicon_url actualizados. PUT acepta scope en el cuerpo JSON; DELETE lo acepta como parámetro de consulta. Un cambio implícito con alcance de dominio sobre un perfil heredado devuelve 422 inherited_brand.

Verificar DNS

Después de crear los registros CNAME (consulta el flujo siguiente), pon la verificación en cola:

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

Se ejecuta en segundo plano. Vuelve a leer GET /branding y observa cómo el status del host cambia a active. Si caduca White Label, la solicitud devuelve 403 scope_blocked_by_entitlement con una indicación para reactivarlo.

También vuelve a comprobar la zona de correo de la marca si existe, por lo que mail_zone.dns_status y mail_zone.client_hosts_status avanzan con la misma llamada. No necesitas llamarla para la zona: comprobamos periódicamente las zonas en espera y las activamos pocos minutos después de que se resuelvan los registros. verify-dns solo solicita hacerlo ahora en lugar de esperar al siguiente ciclo.

Correo en el dominio propio de la marca

mail_zone_enabled coloca el nombre del revendedor en las aplicaciones de correo y clientes de sincronización DAV de sus clientes. Actívalo y publica todos los registros devueltos en mail_zone.records. Incluyen un registro SPF TXT y registros CNAME de IMAP y DAV. Los nombres y destinos exactos de tu respuesta son los valores definitivos.

Usa un CNAME en lugar de un registro A cuando el registro devuelto así lo indique y deja gris la nube de Cloudflare. Los clientes de correo y DAV deben conectarse directamente; un proxy DNS puede romper las comprobaciones de certificados y los protocolos ajenos al navegador. La respuesta indica todos los registros que debes publicar, así que no añadas registros de correo supuestos.

Cuando se resuelven los registros, TrekMail emite los certificados y activa los nombres de host. Observa mail_zone.client_hosts_status hasta que sea active y mail_zone.dav_ready hasta que sea true. Sigue usando el dav_url devuelto; solo cambia de la dirección de la plataforma a la dirección con marca cuando es seguro servir DAV. Si el estado del host indica failed, vuelve a ejecutar la verificación DNS y abre un ticket de soporte si el error continúa.

Crear una vista previa real

POST /branding/preview crea una URL válida durante 72 horas para ver la experiencia con marca antes de que DNS esté activo:

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 respuesta contiene una URL de vista previa que caduca después de 72 horas. Devuelve 422 no_brand cuando no existe ninguna marca que mostrar porque está desactivada o aún no se ha configurado.

Eliminar la marca

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 borra solo este dominio; scope=all borra la marca de toda la cuenta. Devuelve la carga de marca.

Herramientas MCP

Siete herramientas gestionan la marca dentro del conjunto white_label de 20 herramientas. Solo se registran cuando la conexión tiene un alcance de marca efectivo y White Label está disponible. La herramienta de lectura requiere branding:read; las otras seis necesitan branding:write. Un servidor MCP alojado localmente también puede requerir que su administrador permita las escrituras.

get_domain_branding es de solo lectura. Durante el periodo de gracia de cancelación del propietario, sigue disponible, mientras desaparecen las seis herramientas de escritura. Sin derechos White Label, ninguna de estas herramientas se anuncia en tools/list.

Flujo autónomo completo

Si el DNS de tu dominio está en Cloudflare, un agente puede llevar un dominio sin marca hasta un host activo con marca sin intervención humana, porque las herramientas DNS existentes de Cloudflare (apply_cloudflare_dns) pueden escribir los CNAME devueltos por get_domain_branding.

1. Define la marca. set_domain_branding(mode=custom, name, primary_color, accent_color, dashboard_enabled=true, webmail_enabled=true).
2. Sube logotipos (opcional). set_domain_brand_logo(slot="light", content_base64=…), y repite para dark y favicon.
3. Lee los registros DNS. get_domain_branding → copia el array dns_records devuelto. No supongas ni generes valores.
4. Escribe los CNAME. Publica esos registros con el proxy desactivado. En Cloudflare significa una nube gris para que funcionen las validaciones DNS y SSL.
5. Verifica. verify_domain_branding_dns.
6. Consulta. Vuelve a llamar a get_domain_branding hasta que el status de cada host sea active.
7. Vista previa (opcional). Usa create_branding_preview para obtener una URL de demostración real antes de dirigir a los clientes al dominio con marca.

Ejemplo práctico (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

Pide al agente que informe de los nombres de host con marca y sus estados finales, para saber que realmente están activos y no solo en pending_dns.

Consideraciones

• Los derechos controlan las superficies API y MCP. Se necesita una prueba activa o complemento de pago para escribir. El propietario obtiene un periodo de recuperación de solo lectura después de cancelar; todos los demás pierden estas herramientas de inmediato.
• PATCH es una combinación parcial. Los campos omitidos se conservan. Para cambiar solo el color de acento, envía {"accent_color":"#10b981"}. No es necesario volver a enviar el nombre, los logotipos ni los interruptores.
• Reactivar desde desactivado requiere mode. Si la marca está en off, un PATCH sin mode no la activará. Envía mode=custom (o inherit) para reactivarla.
• sender_email necesita un dominio DKIM verificado. La dirección de remitente debe pertenecer a un dominio que ya tenga una clave DKIM aprovisionada en la cuenta o se rechazará la actualización. Verifica el DKIM del dominio (retry_domain_dkim / get_dns_check) antes de definir un remitente personalizado.
• Los logotipos usan base64, ≤1 MB, sin SVG. Envía PNG o JPG (también ICO para favicon) como content_base64. SVG se rechaza. Comprime primero los archivos de origen grandes.
• Mantén sin proxy los registros CNAME devueltos. La nube naranja de Cloudflare u otro proxy CDN impide validar DNS y SSL. Publica los dns_records como se devuelven, con proxied:false.
• Las escrituras necesitan el acceso correcto. Todas las herramientas excepto get_domain_branding cambian datos, así que usa el alcance de escritura requerido y habilita las escrituras si el administrador de tu MCP alojado localmente ha decidido protegerlas.