Gerenciar equipes White Label com API e MCP

As contas White Label podem ser gerenciadas sem voltar ao painel. A API REST e o servidor MCP abrangem o status de configuração da conta, clientes e membros da equipe, funções, acesso a domínios, convites, suspensões, remoções, restaurações e histórico de atividades. A identidade visual é tratada pelo mesmo conjunto de ferramentas White Label e por seu próprio guia de identidade visual.

O limite importante é simples: uma conexão nunca pode conceder mais acesso do que a pessoa por trás dela já possui. Um gerente limitado a determinados domínios não pode convidar alguém para domínios não relacionados, e uma função personalizada não pode conceder permissões que o autor da chamada não possui.

O que está disponível

O catálogo MCP completo agora contém 261 ferramentas via stdio e até 260 ferramentas via HTTP hospedado. O White Label oferece 20 ferramentas: sete para identidade visual e 13 para gerenciamento de contas, membros e atividades.

Essas ferramentas não são carregadas para todos. A TrekMail avalia em tempo real o direito da conta ao White Label, a associação atual da pessoa, o token ou a concessão OAuth, qualquer restrição de domínio, os conjuntos de ferramentas selecionados e as configurações locais de segurança antes de criar tools/list. Uma conexão sem acesso ao White Label não recebe os esquemas.

Estados de direito

Com acesso de leitura ao White Label, chame GET /api/v1/white-label ou a ferramenta get_white_label para diferenciar active do modo somente leitura grace e para ver o progresso da configuração e o prazo do período de carência. Uma conta indisponível não pode chamar esse endpoint: quando uma credencial armazenada ainda inclui um escopo White Label que a conta não pode mais usar, a API retorna scope_blocked_by_entitlement e explica onde reativá-lo.

Escopos

O endpoint de atividade de um membro precisa de activity:read e members:read, pois sua resposta contém um registro do membro, além da atividade. A conexão OAuth hospedada usa o seletor tools:white_label para solicitar essa família de ferramentas; os escopos REST efetivos continuam limitados pela conta e pela associação.

Para um servidor MCP auto-hospedado, adicione white_label a TREKMAIL_TOOLSETS quando usar uma lista de permissão de conjuntos de ferramentas. As ferramentas de gravação também respeitam os controles locais de segurança descritos abaixo.

Endpoints REST

Todos os caminhos ficam sob https://trekmail.net/api/v1.

Cada gravação nesta tabela exige um cabeçalho Idempotency-Key. Repetir a mesma solicitação com a mesma chave retorna o resultado seguro original; segredos de uso único em uma repetição, como um token de convite, são ocultados. Reutilizar uma chave com um corpo diferente retorna idempotency_mismatch.

Leia primeiro o catálogo de acesso

Não fixe as permissões de função no código de uma integração. Chame o catálogo de acesso antes de um convite ou de uma alteração de acesso. Seus indicadores grantable refletem a associação atual do autor da chamada e podem mudar quando o proprietário ajusta essa associação.

As funções oferecidas atualmente para novos convites são:

• client - gerencia os domínios e as caixas de correio atribuídos sem ver a relação privada do revendedor com a TrekMail.
• webmail_only - aparece na lista da equipe, mas não recebe permissões do painel.
• domain_admin - gerencia os domínios atribuídos e o DNS deles, mas não as caixas de correio.
• mailbox_operator - gerencia caixas de correio dentro dos domínios atribuídos, mas não os próprios domínios.
• read_only - pode examinar a área permitida da conta sem alterá-la.
• custom - recebe somente as permissões listadas em permissions.

Algumas funções exigem domain_ids explícitos; outras podem usar all_domains. O catálogo de acesso informa qual regra se aplica. Se o autor da chamada tentar conceder uma função, permissão ou conjunto de domínios mais amplo, a TrekMail retorna scope_blocked_by_membership em vez de restringir o convite silenciosamente.

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

A resposta inclui o membro, informa se a entrega do e-mail foi bem-sucedida e fornece uma URL de convite de uso único. Um problema de entrega não apaga o convite: o proprietário pode copiar a URL ou reenviá-lo mais tarde.

Para uma função personalizada, leia grantable_permissions no catálogo de acesso e envie os valores selecionados em permissions. É necessária pelo menos uma permissão.

Acompanhar o estado do membro

Cada resposta de membro inclui allowed_operations. Use essa lista em vez de tentar adivinhar:

• Um convite pendente pode ser atualizado, suspenso, reenviado ou removido.
• Um membro ativo pode ser atualizado, suspenso ou removido.
• Um membro suspenso pode ser atualizado, reativado ou removido.
• Um membro removido pode ser restaurado.
• A linha do proprietário fica visível para fins de contexto, mas não pode ser alterada por esses endpoints.

A lista também é filtrada para o autor atual da chamada. Ela fica vazia para uma conexão somente leitura, para a própria associação do autor da chamada e para membros cujas permissões sejam mais amplas do que ele pode gerenciar.

Os autores de chamadas não podem remover nem suspender a si mesmos. Autores delegados também não podem gerenciar um membro cujo acesso seja mais amplo que o seu. Transições inválidas retornam membership_state_conflict com uma sugestão para ler o membro novamente.

Suspender ou remover alguém revoga as chaves de API e de caixa de correio criadas sob essa associação. Retomar ou restaurar a associação nunca recupera essas chaves antigas; a pessoa precisa se reconectar ou criar novas credenciais.

Limites de atividade e privacidade

GET /white-label/activity retorna convites, alterações de função e domínio, suspensões, remoções, restaurações e ações de segurança relacionadas. Filtre com action, member_id e per_page.

GET /white-label/members/{id}/activity combina as ações desse membro na conta com logins recentes, incluindo horário, endereço IP, localização aproximada, navegador, sistema operacional e tipo de dispositivo. Essa rota exige deliberadamente os dois escopos de leitura. Autores de chamadas com restrições de domínio só podem solicitar membros que estejam totalmente dentro de seu limite de domínios; um membro inacessível é retornado como 404, para que o endpoint não revele a existência de outro locatário ou cliente.

Ferramentas MCP

As ferramentas de convite exigem TREKMAIL_ALLOW_SENDING=true no MCP stdio auto-hospedado. As ferramentas que alteram o acesso exigem TREKMAIL_ALLOW_DESTRUCTIVE=true; a remoção também exige confirm_remove=true. Essas opções são controles locais de segurança, não permissões adicionais da API. O MCP hospedado aplica sua própria política de segurança aprovada.

As ferramentas criam chaves de idempotência determinísticas quando você não fornece uma. Informar seu próprio idempotency_key é útil quando um fluxo de trabalho pode reiniciar em outro processo.

Um fluxo de automação seguro

1. Chame get_white_label. Pare em scope_blocked_by_entitlement; em uma resposta grace bem-sucedida, continue somente com leituras.
2. Chame get_white_label_access_catalog imediatamente antes de conceder acesso.
3. Liste ou leia o membro alvo antes de alterá-lo.
4. Verifique allowed_operations, a função pretendida, as permissões e os IDs de domínio.
5. Use uma chave de idempotência estável para a gravação.
6. Leia o membro novamente e informe o status resultante e as permissões efetivas.
7. Consulte a atividade White Label quando precisar de um registro de auditoria da alteração.

Erros que indicam o que fazer