Aliases de domínio pela API e pelo MCP

Um alias de domínio permite que um domínio acompanhe os endereços de recebimento de outro. Se hello@company.example pode receber e-mails, hello@brand.example pode entregá-los ao mesmo lugar sem criar e manter uma segunda caixa postal ou um segundo alias.

Esse recurso serve apenas para recebimento. Ele não cria um endereço De, não altera o SMTP nem permite que alguém envie como o domínio conectado.

Quando é útil

Aliases de domínio funcionam bem quando uma empresa tem vários domínios de marca, um domínio antigo que ainda recebe mensagens de clientes ou domínios nacionais separados que devem compartilhar os mesmos nomes de caixa de entrada.

Por exemplo:

hello@brand.example   → hello@company.example
billing@brand.example → billing@company.example

A parte antes de @ permanece exatamente igual. Se o endereço correspondente não existir no domínio principal, a TrekMail não o inventará.

Planos e limites

Um domínio conectado pode acompanhar apenas um domínio principal por vez. Um domínio principal pode atender vários domínios conectados, até o limite normal de domínios da conta. Um domínio não pode ser conectado e principal ao mesmo tempo, o que simplifica o roteamento e evita ciclos.

Os dois domínios devem pertencer à mesma conta, usar a TrekMail para mensagens recebidas, estar ativos e ter registros MX funcionais. Se o estado do plano, da conta ou do DNS mudar posteriormente, a TrekMail manterá a conexão salva, mas pausará a entrega até o requisito ser restaurado.

O que mantém a prioridade

O alias de domínio só é executado depois que a TrekMail verifica os endereços exatos já configurados no domínio conectado. Caixas postais, aliases, endereços de encaminhamento, encaminhamentos de caixa postal e configurações catch-all existentes mantêm a prioridade documentada.

Isso significa que uma regra intencional para sales@brand.example não será substituída silenciosamente por sales@company.example.

API REST

Os três endpoints usam o ID do domínio conectado:

O endpoint mantém o caminho original /matching-addresses para não interromper integrações existentes. O painel e a documentação usam o termo mais claro do setor alias de domínio.

PUT e DELETE exigem um cabeçalho Idempotency-Key. É seguro repetir a mesma solicitação bem-sucedida com a mesma chave.

Conectar um domínio

PUT /api/v1/domains/42/matching-addresses
Authorization: Bearer tm_live_...
Idempotency-Key: matching-brand-company-v1
Content-Type: application/json

{
  "primary_domain_id": 7
}

Ler o resultado

{
  "configured": true,
  "enabled": true,
  "delivering": true,
  "status": "delivering",
  "paused_reason": null,
  "alias_domain": {
    "id": 42,
    "domain": "brand.example"
  },
  "primary_domain": {
    "id": 7,
    "domain": "company.example"
  },
  "primary_domain_restricted": false
}

configured informa se a conexão está salva. delivering informa se ela está funcionando agora. Verifique ambos em vez de tratar uma linha salva como prova de que as mensagens estão fluindo.

Quando um token pode acessar o domínio conectado, mas não o principal, a resposta define primary_domain_restricted como true e oculta a identidade do domínio principal. Ela nunca revela um domínio fora da lista de permissões do token.

Estados de entrega

Ferramentas MCP

O mesmo processo está disponível por meio de três ferramentas de domínio:

• get_domain_alias: lê a conexão salva e o estado de entrega em tempo real;
• set_domain_alias: conecta ou altera o domínio principal;
• remove_domain_alias: desconecta após confirm_remove: true.

O MCP hospedado aplica as permissões aprovadas durante o OAuth. Um administrador de MCP hospedado localmente pode exigir aprovação explícita para ações de gravação. Os dois caminhos impõem o plano da conta, os escopos do token, a lista de domínios permitidos e a validação no servidor.

Os nomes das ferramentas e os títulos para clientes usam alias de domínio. O endpoint REST mantém o caminho original para compatibilidade.

Remoção segura e redução de plano

Remover uma conexão não exclui nenhum domínio nem caixa postal. Caixas postais exatas, aliases, endereços de encaminhamento e regras catch-all permanecem inalterados. Endereços sem correspondência que dependiam somente desse recurso podem começar a rejeitar mensagens, portanto revise o domínio antes de confirmar a remoção.

Excluir um domínio conectado remove sua conexão automaticamente. A TrekMail não excluirá um domínio principal enquanto domínios conectados ainda dependerem dele; desconecte esses domínios primeiro.

Após reduzir para o Nano, a conexão permanece salva, mas deixa de entregar. Voltar ao Starter ou superior a restaura sem inserir novamente o domínio principal.

Trilha de auditoria

Toda alteração pela API ou pelo MCP aparece em Agentes de IA e API → Log de auditoria. Eventos de conexão e alteração registram os dois IDs de domínio, o domínio principal anterior quando aplicável, o token atuante, o ID da solicitação e o horário. A remoção registra qual conexão foi removida. Nenhum conteúdo de e-mail ou credencial é gravado nesses eventos.

Lista de solução de problemas

1. Confirme que os dois domínios aparecem como Ativos e usam a TrekMail para mensagens recebidas.
2. Verifique se os registros MX dos dois domínios estão corretos.
3. Confirme que a conta está no Starter, Pro ou Agency.
4. Analise configured, delivering, status e paused_reason em conjunto.
5. Verifique se uma caixa postal exata, alias, endereço de encaminhamento ou regra catch-all já controla o endereço.
6. Consulte no log de auditoria a última conexão, alteração ou remoção.