Criar e gerenciar tokens de API

Os tokens de API controlam o que um aplicativo ou agente pode fazer na sua conta. Cada token tem um nome, permissões, restrições opcionais de domínio e uma data de validade.

Vai conectar um cliente MCP? Se ele aceitar autorização pelo navegador, adicione https://trekmail.net/mcp como servidor MCP remoto e aprove o acesso no navegador. Normalmente, não é preciso criar nem colar um token. Os tokens tm_live_ manuais são destinados a scripts, tarefas de CI, MCP auto-hospedado e clientes que não aceitam esse fluxo. Consulte Conectar agentes de IA (MCP).

Antes de começar

• Todos os planos podem criar tokens de API, inclusive o Nano. Os planos Nano são limitados às permissões do Email Verifier (verify:read, verify:write).
• Os planos Starter permitem permissões de infraestrutura somente para leitura, além de todas as permissões do Drive e do Email Verifier. O Starter também pode gerenciar encaminhamento no painel, mas o acesso de gravação para encaminhamento pela API (mailboxes:forwarding:write) exige Pro ou Agency. Pro e Agency liberam todas as permissões.
• O proprietário pode gerenciar todas as credenciais da conta. Um membro delegado com permissão para tokens de API pode gerenciar somente as credenciais que criou e conceder apenas permissões e domínios já presentes na sua associação.
• Dica: Clique em Iniciar tour na página Agentes de IA e API para ver uma rápida apresentação das opções de conexão, tokens, aplicativos conectados e log de auditoria.

Criar um token de automação do Drive

A API do Drive e as ferramentas MCP usam tokens de operações (tm_live_...). Selecione apenas as permissões do Drive necessárias para o fluxo de trabalho:

• Relatórios somente para leitura: drive:account:read, drive:mailbox:read ou drive:addon:read.
• Automação de uploads: adicione drive:account:write ou drive:mailbox:write.
• Links públicos de entrega: adicione drive:account:share ou drive:mailbox:share.
• Limpeza permanente: use drive:account:purge ou drive:mailbox:purge somente em um token separado e rigorosamente controlado.

A compra, o redimensionamento e o cancelamento do complemento Drive não estão disponíveis por tokens de API. Os agentes podem consultar o status e os preços do complemento com drive:addon:read, mas as alterações de assinatura continuam no painel.

Criar um token de automação do White Label

O White Label usa cinco permissões de token de operações: branding:read, branding:write, members:read, members:write e activity:read. Elas aparecem somente enquanto a conta tem acesso ao White Label. members:write é marcada como perigosa porque pode remover o acesso e revogar as chaves de outra pessoa.

Para uma integração de status e auditoria somente para leitura, selecione branding:read, members:read e activity:read. Adicione branding:write apenas para configurar a marca e o DNS. Adicione members:write somente quando a automação precisar convidar ou alterar pessoas.

Durante o período de tolerância do cancelamento, o proprietário mantém as três permissões de leitura para recuperação, enquanto as operações de gravação e as credenciais delegadas do White Label deixam de funcionar. A reativação não recupera uma credencial revogada; crie ou autorize uma nova.

Criar um token

1. Acesse Agentes de IA e API → Tokens.
2. Clique em Criar token.
3. Preencha o formulário:
   • Nome: Um rótulo para identificar o token (por exemplo, "Agente Claude", "Pipeline de CI/CD").
   • Validade: Escolha 7 dias, 30 dias, 90 dias, uma data personalizada ou nunca.
   • Permissões: Selecione as operações que o token pode realizar. Todas as permissões disponíveis vêm marcadas por padrão.
   • Restrição de domínio: Escolha "Todos os domínios" ou selecione domínios específicos para limitar o acesso do token.
4. Clique em Criar token.

Após a criação, o token em texto simples é exibido uma única vez. Copie-o imediatamente ou use o botão Baixar para salvá-lo como um arquivo .txt.

O token não poderá ser visto novamente. Guarde-o com segurança antes de fechar a confirmação.

Criar um token de mensagem

Os tokens de mensagem permitem que agentes leiam e enviem e-mails por uma caixa específica. Eles são separados dos tokens de operações e criados de forma programática pela API com seu token de operações.

Para criar um token de mensagem, seu agente chama:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

Escolha as menores permissões necessárias para o fluxo de trabalho:

O token em texto simples (tm_msg_...) é retornado uma única vez. Adicione-o à sua configuração MCP como TREKMAIL_MESSAGE_TOKEN.

Os tokens de mensagem estão disponíveis nos planos Pro e Agency. O token de operações deve ter a permissão mailboxes:message-tokens:manage.

Para uma caixa do Gmail conectada ou outra caixa externa, use external_account_id. Para que os destinatários vejam um endereço comercial autorizado, use também um identity_id retornado pelo endpoint de identidades. Consulte Endereços Enviar como por API e MCP.

Formato do token

O TrekMail usa dois prefixos para diferenciar os tipos de token:

Os primeiros 8 caracteres após o prefixo são armazenados como um prefixo visível no painel para facilitar a identificação.

Permissões

As permissões controlam o que o token pode fazer. As opções disponíveis dependem do seu plano:

• Nano: Somente Email Verifier (verify:read, verify:write). Adicionar o Drive Storage também concede à conta os recursos da API do Drive e do MCP aos quais ela tem direito.
• Starter: Acesso completo ao Drive e ao Email Verifier, além de acesso somente para leitura a todo o restante (domínios, caixas, encaminhamento, filtros de e-mail, resposta automática, migrações, tickets, SMTP, Cloudflare). Use o painel para as ações de gravação que o Starter não oferece pela API, como criar migrações, responder a tickets ou alterar a resposta automática.
• Pro e Agency: Acesso completo. Leitura, gravação, criação e exclusão em todas as famílias, além de tokens de mensagem para ler e enviar e-mails pela API.

As permissões do White Label são um direito do complemento, e não um atalho pela tabela de planos. Elas são oferecidas apenas quando o White Label está ativo; o proprietário mantém acesso de recuperação somente para leitura durante o período de tolerância do cancelamento.

Consulte Permissões da API e dos planos para ver a referência de cada permissão.

Restrições de domínio

Por padrão, os tokens podem acessar todos os domínios da sua conta. Para restringir um token a domínios específicos:

1. Selecione Domínios selecionados na seção de restrição de domínio.
2. Marque os domínios que o token deve acessar.

Um token restrito receberá respostas 404 ao tentar acessar recursos de outros domínios; a API se comportará como se esses domínios não existissem.

Revogar um token

1. Acesse Agentes de IA e API → Tokens.
2. Encontre o token na lista.
3. Clique em Revogar.
4. Confirme a revogação.

Os tokens revogados deixam de funcionar imediatamente. Qualquer solicitação à API que use um token revogado recebe 401 Unauthorized.

A revogação é permanente e não pode ser desfeita. Crie um novo token se precisar restaurar o acesso.

Status do token

Os tokens têm três estados:

Use o filtro de status na página Tokens para visualizar os tokens por estado.

Trilha de auditoria

Cada criação e revogação de token aparece na guia Log de auditoria. Os eventos incluem o nome do token, a ação e o horário.

Soluções rápidas

• "Permissões não disponíveis no seu plano": Seu plano não inclui essas permissões. O Nano fica limitado a verify:read e verify:write (adicione o complemento Drive Storage para também obter as permissões drive:*). O Starter adiciona acesso de leitura a todas as famílias de infraestrutura, além do Drive e Email Verifier completos. Pro e Agency liberam gravações em todos os lugares.
• Perdeu o token em texto simples: O token não pode ser recuperado. Revogue-o e crie um novo.
• O token funciona, mas retorna 404 para alguns domínios: Provavelmente existe uma restrição de domínio. Revogue e recrie com "Todos os domínios" ou adicione os domínios ausentes à restrição.
• Uma permissão do White Label retorna scope_blocked_by_entitlement: Reative o White Label e crie ou autorize uma credencial com a permissão necessária.
• Um token delegado parou após a alteração de uma função: Reduzir, suspender ou remover o acesso de um membro revoga imediatamente as credenciais afetadas. Crie um novo token depois que o proprietário restaurar o acesso correto.