Guia da API e MCP para branding White Label

O branding White Label por domínio pode ser configurado de ponta a ponta pela API e pelo MCP, sem precisar do dashboard. Um agente pode definir o nome e as cores da marca de um domínio, enviar logotipos, ativar hosts personalizados para o dashboard e o webmail, consultar os registros DNS que precisa criar e solicitar a verificação de DNS. Este é o mesmo branding gravado pela aba Branding do dashboard; a API apenas permite que um agente ou script faça isso por você.

O branding é configurado por domínio (o domínio é o id numérico). Um domínio pode ter sua própria marca (custom), herdar o padrão da conta (inherit) ou ficar desativado. A API retorna os nomes de host personalizados e os registros CNAME desse domínio. Sempre copie exatamente os registros retornados. Não crie um nome de host ou destino CNAME a partir de um exemplo deste guia.

O controle do add-on

Todos os planos de e-mail incluem um teste e uma prévia de White Label por 30 dias. Use esse período para configurar a marca e testar a experiência antes de disponibilizar os hosts personalizados aos clientes.

A API segue o mesmo direito de acesso do dashboard White Label:

• Teste ativo ou add-on pago: os escopos de leitura e gravação ficam disponíveis. Os hosts ativados passam de pending_dns para active depois que o CNAME é resolvido e o SSL é emitido.
• Período de carência após cancelamento: o proprietário da conta mantém acesso somente para leitura até o horário indicado em hard_delete_at. As gravações são bloqueadas, e conexões delegadas perdem imediatamente o acesso ao White Label.
• Sem direito de acesso ativo: os escopos de White Label são removidos das permissões efetivas da credencial, e suas ferramentas MCP não são carregadas.

Se um token armazenado já teve um escopo de White Label, mas o direito de acesso não está mais ativo, a API retorna 403 scope_blocked_by_entitlement com uma próxima etapa direta. Criar um token mais amplo não ignora esse direito de acesso.

Escopos obrigatórios

O branding tem seus próprios escopos. Isso impede que uma automação que gerencia domínios comuns veja ou altere acidentalmente a identidade do revendedor.

Endpoints REST

Todos os endpoints ficam em https://trekmail.net/api/v1. {id} é o id numérico do domínio.

Todos os endpoints, exceto verify-dns e preview, retornam o mesmo payload de branding retornado por GET. Assim, uma única solicitação informa o novo estado.

O payload de branding

{
  "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 e mail_zone são null quando mode é off. mail_zone.enabled é a intenção salva; use seus dois campos de status para distinguir os estados pendente, ativo, com falha e de limpeza. O status do host informa se o DNS e o SSL ainda estão pendentes ou se o host está ativo. Os valores de espaço reservado no exemplo são intencionais: os dns_records e o cname_target retornados são os únicos valores que devem ser publicados.

mail_zone descreve os nomes de host de e-mail próprios da marca (veja abaixo). dns_status abrange o estado do DNS de e-mail, e client_hosts_status abrange o estado dos hosts de cliente e certificados; ambos indicam off, pending_dns, active ou failed. records lista os registros DNS que seu provedor precisa publicar. É sempre seguro usar dav_url: ele permanece na TrekMail até que o certificado DAV personalizado e a rota web restrita estejam prontos. Faça a troca somente quando dav_ready passar a true; então cert_expires_at informará a expiração mais próxima dos certificados dos hosts personalizados para aplicativos de e-mail.

Ler o branding atual

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

Definir a marca (mesclagem parcial)

PATCH é uma mesclagem parcial. Todos os campos omitidos são preservados, portanto envie somente o que deseja alterar.

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

Os campos do corpo:

Enviar um logotipo

Os logotipos são enviados em base64. slot pode ser light, dark ou favicon. Formatos aceitos: PNG e JPG em qualquer slot, além de ICO para favicon. Tamanho máximo de 1 MB. SVG é rejeitado por motivos de segurança. O scope=domain padrão altera somente um domínio no modo custom; ele nunca acompanha um perfil herdado. Para alterar intencionalmente o perfil compartilhado por meio de um domínio inherit, envie scope=account_default e use um token branding:write sem restrição. Tokens restritos a um domínio não podem modificar o padrão da conta.

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

Remova um slot com 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"

Ambos retornam o payload de branding com logo_url / logo_dark_url / favicon_url atualizado. PUT aceita scope no corpo JSON; DELETE o aceita como parâmetro de consulta. Uma modificação implícita com escopo de domínio em um perfil herdado retorna 422 inherited_brand.

Verificar o DNS

Depois de criar os registros CNAME (consulte o fluxo abaixo), coloque a verificação na fila:

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

Isso é executado em segundo plano. Consulte novamente GET /branding e acompanhe o status do host mudar para active. Se o White Label expirar, a solicitação retornará 403 scope_blocked_by_entitlement com uma orientação para reativação.

A solicitação também verifica novamente a zona de e-mail da marca quando ela existe, portanto mail_zone.dns_status e mail_zone.client_hosts_status avançam na mesma chamada. Você não precisa chamá-la para a zona: verificamos as zonas pendentes em intervalos regulares e as ativamos poucos minutos após a resolução dos registros. verify-dns apenas solicita que isso aconteça agora, em vez de aguardar a próxima verificação.

E-mail no domínio próprio da marca

mail_zone_enabled coloca o nome do revendedor nos aplicativos de e-mail e clientes de sincronização DAV dos clientes. Ative essa opção e publique todos os registros retornados em mail_zone.records. Eles incluem um registro TXT de SPF e registros CNAME de IMAP e DAV. Os nomes e destinos exatos da resposta são a referência oficial.

Use um CNAME em vez de um registro A quando o registro retornado pedir isso, e deixe a nuvem da Cloudflare cinza. Os clientes de e-mail e DAV precisam se conectar diretamente; um proxy DNS pode interromper as verificações de certificado e protocolos que não usam navegador. A resposta indica todos os registros que você deve publicar, portanto não adicione registros de e-mail estimados.

Quando os registros forem resolvidos, a TrekMail emitirá os certificados e ativará os nomes de host. Acompanhe mail_zone.client_hosts_status até active e mail_zone.dav_ready até true. Continue usando o dav_url retornado; ele muda do endereço da plataforma para o endereço personalizado somente depois que for seguro disponibilizar o DAV. Se o status do host indicar failed, execute novamente a verificação de DNS e abra um chamado de suporte se a falha continuar.

Criar uma prévia ao vivo

POST /branding/preview cria uma URL válida por 72 horas para você conferir a experiência personalizada antes que o DNS esteja ativo:

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"

A resposta contém uma URL de prévia que expira após 72 horas. Ela retorna 422 no_brand quando não há uma marca para visualizar porque o branding está desativado ou ainda não foi definido.

Excluir o branding

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 limpa apenas este domínio; scope=all limpa o branding em toda a conta. Retorna o payload de branding.

Ferramentas MCP

Sete ferramentas abrangem o branding dentro do conjunto de 20 ferramentas white_label. Elas são registradas somente quando a conexão tem um escopo efetivo de branding e o White Label está disponível. A ferramenta de leitura exige branding:read; as outras seis exigem branding:write. Um servidor MCP hospedado localmente também pode exigir que o administrador permita ações de gravação.

get_domain_branding é somente para leitura. Durante o período de carência após o cancelamento pelo proprietário, ela permanece disponível, enquanto todas as seis ferramentas de gravação desaparecem. Sem o direito de acesso ao White Label, nenhuma dessas ferramentas é anunciada em tools/list.

O fluxo autônomo de ponta a ponta

Se o DNS do seu domínio estiver na Cloudflare, um agente poderá levar um domínio sem branding até um host personalizado ativo sem nenhuma etapa humana, pois as ferramentas de DNS da Cloudflare existentes (apply_cloudflare_dns) podem gravar os CNAMEs retornados por get_domain_branding.

1. Defina a marca. set_domain_branding(mode=custom, name, primary_color, accent_color, dashboard_enabled=true, webmail_enabled=true).
2. Envie logotipos (opcional). set_domain_brand_logo(slot="light", content_base64=…); repita para dark e favicon.
3. Leia os registros DNS. get_domain_branding → copie o array dns_records retornado. Não estime nem gere valores.
4. Grave os CNAMEs. Publique esses registros com o proxy desativado. Na Cloudflare, isso significa uma nuvem cinza para permitir o funcionamento da validação de DNS e SSL.
5. Verifique. verify_domain_branding_dns.
6. Consulte repetidamente. Chame get_domain_branding novamente até o status de cada host ser active.
7. Visualize (opcional). Use create_branding_preview para obter uma URL de demonstração ao vivo antes de direcionar os clientes ao domínio personalizado.

Exemplo prático (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

Peça ao agente que informe os nomes de host personalizados e os status finais para confirmar que tudo realmente ficou ativo, e não apenas em pending_dns.

Cuidados

• O direito de acesso controla a API e a superfície MCP. É necessário ter um teste ativo ou add-on pago para fazer gravações. O proprietário recebe uma janela de recuperação somente para leitura após o cancelamento; todos os demais perdem essas ferramentas imediatamente.
• PATCH é uma mesclagem parcial. Os campos omitidos são preservados. Para alterar apenas a cor de destaque, envie {"accent_color":"#10b981"}. Não é necessário reenviar o nome, os logotipos ou as opções.
• A reativação após a desativação exige mode. Se o branding estiver off, um PATCH sem mode não o reativará. Envie mode=custom (ou inherit) para reativar.
• sender_email exige um domínio DKIM verificado. O endereço do remetente definido deve pertencer a um domínio que já tenha uma chave DKIM provisionada na conta, caso contrário a atualização será rejeitada. Verifique o DKIM do domínio (retry_domain_dkim / get_dns_check) antes de definir um remetente personalizado.
• Os logotipos usam base64, ≤1 MB e não aceitam SVG. Envie PNG ou JPG (ICO também é aceito para favicon) como content_base64. SVG é rejeitado. Primeiro compacte arquivos de origem grandes.
• Mantenha sem proxy os registros CNAME retornados. Uma nuvem laranja da Cloudflare ou outro proxy CDN impede a validação de DNS e SSL. Publique os dns_records como foram retornados, com proxied:false.
• Ações de gravação exigem o acesso correto. Todas as ferramentas, exceto get_domain_branding, alteram dados. Portanto, use o escopo de gravação obrigatório e ative as gravações se o administrador do MCP hospedado localmente tiver optado por protegê-las.