Criar e gerenciar tokens de API

Abra TrekMail no Claude, escolha Connect, entre e autorize o acesso. Não é preciso criar um token de API. Revise as permissões ou desconecte em Agentes de IA e API → Tokens → Aplicativos conectados.

Sua própria marca White Label: use o endereço MCP do painel da sua marca e dê ao conector o nome dela. Adicione como custom connector; a página pública do TrekMail faz login no TrekMail e não substitui a conexão da sua marca.

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).

Ler email com uma única chave

Nos planos Pro e Agency, escolha Ler email ao criar uma chave API. A permissão explícita é mailboxes:messages:read; mailboxes:read apenas mostra endereços e dados de configuração. Todas as caixas inclui as atuais e futuras; também pode limitar o acesso a domínios e caixas selecionados. As chaves existentes não recebem novas permissões automaticamente.

Use a chave de conta nas rotas GET abaixo. Enviar, eliminar e alterar dados continua a exigir credenciais e permissões de mensagens separadas. O MCP alojado aceita OAuth, não tm_live_ ou tm_msg_. O erro de tipo de token indica ao agente a rota ou autorização correta.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

Escolher e editar permissões da aplicação

Abra os detalhes de uma chave API ou aplicação ligada, escolha Editar acesso, reveja e confirme as alterações. O segredo da chave API mantém-se. Reduzir permissões, recursos ou validade também limita tokens de caixas existentes e cancela envios não iniciados. As novas ligações OAuth podem ser limitadas imediatamente; ampliar acesso exige nova aprovação. Editar uma ligação antiga desliga-a e guarda as escolhas para voltar a ligar. Os tokens de mensagens apenas podem perder permissões ou ter a validade encurtada.

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 (atuais e futuros)", "Apenas domínios selecionados" ou "Todos os domínios (atuais e futuros) exceto…" para deixar alguns domínios de fora.
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, inclusive os que você adicionar depois. Duas opções limitam esse acesso:

• Apenas domínios selecionados: o token acessa os domínios marcados e nada mais. Um domínio adicionado depois fica de fora até você editar o token e marcá-lo.
• Todos os domínios (atuais e futuros) exceto…: o token acessa todos os domínios, menos os marcados, inclusive os adicionados depois. Use para manter seus agentes longe do e-mail de um cliente sem editar o token a cada novo domínio.

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. Nos dois casos, o token também não pode alterar configurações da conta inteira que afetariam domínios fora do seu alcance, como o padrão para novas caixas de correio.

Para um membro da equipe limitado a alguns domínios, "exceto…" significa os domínios desse membro, menos os marcados; domínios adicionados depois à conta não entram. Se você apagar um domínio que estava de fora e adicioná-lo de novo, ele conta como um domínio novo: deixe-o de fora outra vez.

Regenerar um token

Regenere um token quando precisar do segredo de novo ou quando o segredo puder ter vazado. O token mantém o nome, as permissões, os domínios, as caixas de correio, a validade e o histórico de auditoria. Só o segredo muda.

1. Acesse Agentes de IA e API → Tokens e abra os Detalhes do token.
2. Clique em Regenerar.
3. Escolha quando o segredo antigo deixa de funcionar: Agora, Daqui a 1 hora, Daqui a 24 horas, Daqui a 3 dias ou Daqui a 7 dias. O segredo antigo nunca funciona além da validade do próprio token.
4. Clique em Regenerar e copie o novo segredo. Como um token novo, ele é exibido uma única vez.

Enquanto o segredo antigo funcionar, os detalhes do token mostram até quando e oferecem Desativar agora. Substitua o segredo em todos os aplicativos antes disso: as solicitações que ainda usarem o segredo antigo recebem depois 401 Unauthorized.

Os tokens de mensagem (tm_msg_...) criados com o segredo antigo deixam de funcionar ao mesmo tempo. Um aplicativo que cria os próprios tokens de mensagem pode criar novos com o novo segredo. Se o segredo puder ter vazado, escolha Agora.

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, regeneraçã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, mas você pode regenerá-lo: abra os Detalhes, clique em Regenerar e copie o novo segredo. O token mantém as configurações.
• O token funciona, mas retorna 404 para alguns domínios: Provavelmente existe uma restrição de domínio. Abra Detalhes do token, escolha Editar acesso e adicione os domínios que faltam, ou mude para "Todos os domínios (atuais e futuros)" ou "Todos os domínios (atuais e futuros) exceto…".
• 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.