Proteções de segurança e intenções de eliminação

A API TrekMail foi concebida para evitar a perda acidental de dados. As operações destrutivas exigem vários passos de confirmação, os limites de frequência evitam erros em massa e todas as ações são registadas.

Reciclagem. Confirmar uma intenção de eliminação de caixa de correio move agora a caixa para uma reciclagem de 7 dias (apresentada como Eliminados recentemente no painel), em vez de a destruir imediatamente. Pode listar as caixas eliminadas e restaurar uma durante esse período:

GET  /api/v1/mailboxes?status=trashed        # list the recycle bin
POST /api/v1/mailboxes/{id}:restore          # restore to active (scope mailboxes:delete)

Depois do período de retenção, uma tarefa diária elimina definitivamente as caixas na reciclagem. A restauração volta a verificar o limite de caixas por domínio. Os agentes MCP usam as ferramentas restore_mailbox e list_trashed_mailboxes; confirm_delete_intent é agora recuperável, não irreversível. Eliminar um domínio ou uma conta remove permanentemente as respetivas caixas e não usa a reciclagem.

Eliminação em dois passos (intenções de eliminação)

A eliminação de caixas de correio e domínios está entre as operações destrutivas de maior impacto na API. É usado um processo de dois passos:

Passo 1: criar uma intenção de eliminação

POST /api/v1/mailboxes/{id}:delete-intent

Isto cria uma intenção temporária que descreve o que será eliminado. A resposta inclui:

• Indicadores de risco: avisos sobre regras de reencaminhamento, aliases ou migrações ativas que serão afetados.
• Expiração: a intenção expira após 10 minutos. Depois disso, terá de criar uma nova.
• URL de confirmação: o URL a chamar no passo 2.

Nenhum dado é eliminado nesta fase.

Passo 2: confirmar a intenção

POST /api/v1/delete-intents/{id}:confirm
Headers: X-Confirm-Delete: true

Com a reciclagem de caixas do TrekMail ativada, a confirmação move a caixa para Eliminados recentemente e devolve uma intenção concluída com status: "executed". A caixa pode ser restaurada durante sete dias, desde que o domínio tenha capacidade para ela no momento da restauração.

{
  "id": 1,
  "mailbox_id": 4,
  "mailbox_email": "user@acme.test",
  "status": "executed",
  "risk_flags": [],
  "confirmed_at": "2026-05-28T11:22:08+00:00",
  "executed_at": "2026-05-28T11:22:08+00:00"
}

Após o período de recuperação, a limpeza diária do TrekMail remove a caixa definitivamente. Use antes a lista da reciclagem ou o endpoint de restauração. A eliminação de um domínio ou conta não segue este percurso de recuperação de caixas.

O cabeçalho X-Confirm-Delete: true é obrigatório no pedido de confirmação como verificação de segurança adicional.

Indicadores de risco

Ao criar uma intenção de eliminação, a API procura condições que possam indicar que não pretende continuar:

Reveja estes indicadores antes de confirmar. A API não bloqueia a confirmação com base nos indicadores de risco. Servem apenas para informação.

Limites de frequência em operações destrutivas

As operações destrutivas têm dois níveis de limitação além do limite padrão por minuto da API:

• Limite diário por token: cada token pode confirmar um número limitado de intenções de eliminação por dia.
• Intervalo entre confirmações: após confirmar uma eliminação, existe um breve intervalo antes de ser aceite a confirmação seguinte.

Quando ativados, ambos devolvem 429 Too Many Requests com um cabeçalho Retry-After.

Controlo de segurança MCP para servidores alojados localmente

Se executar o servidor MCP stdio, o administrador pode exigir TREKMAIL_ALLOW_DESTRUCTIVE=true antes de disponibilizar as ferramentas de eliminação. Este é um controlo de segurança local, não um interruptor de funcionalidade do produto TrekMail. O MCP alojado usa as permissões aprovadas durante o OAuth.

As ferramentas de leitura continuam disponíveis dentro dos âmbitos concedidos. Reveja a tarefa e os âmbitos do agente antes de permitir eliminações.

Idempotência

Os endpoints de escrita que exigem um Idempotency-Key indicam-no na tabela do endpoint e na especificação OpenAPI. Use uma nova chave para cada operação lógica antes de repetir um pedido:

Idempotency-Key: create-mailbox-alice-2024

• A mesma chave e o mesmo corpo reproduzem a resposta original sem repetir a operação.
• A mesma chave e um corpo diferente devolvem 409 Conflict.
• Tokens diferentes usam espaços de chaves independentes.

O servidor MCP gera chaves de idempotência seguras contra repetições para as chamadas de ferramentas, pelo que uma nova tentativa não repete uma operação já concluída.

Proteções de segurança para o envio

O envio de correio através do servidor MCP tem o seu próprio modelo de segurança com dois controlos, semelhante ao das operações destrutivas, mas com duas verificações independentes:

Controlo 1: controlo do servidor local

Num servidor MCP alojado localmente, defina TREKMAIL_ALLOW_SENDING=true para permitir a ferramenta send_message. O MCP alojado usa as permissões aprovadas durante o OAuth.

Controlo 2: confirmação por chamada

Mesmo com o controlo de ambiente ativado, cada chamada a send_message deve incluir confirm_send=true como parâmetro. Sem ele, a ferramenta devolve um erro que pede confirmação ao agente.

Porquê dois controlos?

O controlo local é definido uma vez pelo administrador que configura o servidor MCP. O controlo por chamada exige que o agente decida ativamente enviar cada mensagem. Nenhum controlo é suficiente por si só; ambos têm de ser aprovados antes de qualquer mensagem sair do servidor.

Isto evita envios acidentais por agentes que exploram as ferramentas disponíveis sem compreender as consequências. Um agente pode listar e ler mensagens livremente com um token de mensagens, mas não pode enviar até que ambos os controlos sejam satisfeitos.

Proteções de segurança para migrações

A migração de correio através do servidor MCP tem as suas próprias proteções, semelhantes às do envio e das operações destrutivas.

Controlo do servidor local para migrações

Num servidor MCP alojado localmente, defina TREKMAIL_ALLOW_MIGRATION=true para permitir ferramentas de escrita de migrações (start_migration, retry_migration, delete_migration). O MCP alojado usa as permissões aprovadas durante o OAuth.

cancel_migration está sempre disponível, independentemente desta definição. É uma operação de segurança que deve estar sempre acessível para interromper uma migração descontrolada.

As ferramentas de migração só de leitura (list_migrations, get_migration) funcionam sem controlos. test_migration_connection exige TREKMAIL_ALLOW_MIGRATION=true, pois estabelece ligações IMAP de saída.

Confirmação por chamada para migrações

Cada ferramenta de escrita de migrações exige um parâmetro de confirmação:

• start_migration exige confirm_start=true
• cancel_migration exige confirm_cancel=true
• retry_migration exige confirm_retry=true

Sem o parâmetro de confirmação, a ferramenta devolve um erro que pede confirmação ao agente.

Limite de simultaneidade de todo o servidor

A API aplica um limite global de migrações simultâneas (predefinição: 20). Quando o limite é atingido, os novos pedidos de migração devolvem 503 com migration_capacity_reached e retryable: true. Isto protege os recursos do servidor quando muitas contas migram em simultâneo.

Registo de auditoria

Todas as ações de alteração da API são registadas no registo de auditoria, visível em Agentes de IA e API → Registo de auditoria no painel. Os eventos incluem:

• Token criado ou revogado: quem criou ou revogou um token de operações e quando.
• Token de mensagens criado ou revogado: quem criou ou revogou um token de mensagens.
• Intenção criada: foi criada uma intenção de eliminação para uma caixa específica.
• Intenção confirmada: o pedido de eliminação foi aceite.
• Eliminação executada: a caixa foi movida para Eliminados recentemente e começou o seu período de recuperação.
• Intenção expirada: uma intenção não confirmada expirou após 10 minutos.
• Caixa criada: uma nova caixa foi aprovisionada através da API.
• Convite criado: foi enviado um convite de configuração de caixa.
• Reencaminhamento atualizado: as regras de reencaminhamento de uma caixa foram alteradas.
• Nova verificação DNS iniciada: foi pedida uma verificação DNS para um domínio.
• Migração iniciada: foi iniciada uma migração de correio através da API.
• Migração cancelada: uma migração em curso foi cancelada.
• Migração repetida: uma migração falhada ou cancelada foi repetida.
• Migração eliminada: foi eliminado um registo de migração.
• Mensagem lida: foram listadas ou lidas mensagens através da API de mensagens.
• Mensagem enviada: foi enviada uma mensagem através da API de mensagens.
• Falha no envio da mensagem: falhou uma tentativa de envio de mensagem.
• Indicadores da mensagem atualizados: foram alterados os indicadores da mensagem (lida/não lida, assinalada).
• Mensagem eliminada: foi eliminada uma mensagem de uma pasta da caixa.
• Mensagem movida: uma mensagem foi movida entre pastas.
• Domínio criado: foi adicionado um domínio através da API.
• Domínio eliminado: foi removido um domínio através da API.
• Pedido de suporte criado: foi aberto um pedido de suporte através da API.
• Resposta ao pedido de suporte: foi publicada uma resposta num pedido.
• Pedido de suporte fechado: foi fechado um pedido de suporte.
• SMTP configurado: foram atualizadas as definições de SMTP.
• Ligação SMTP eliminada: foi removida uma ligação SMTP personalizada.
• Teste SMTP colocado em fila: foi iniciado um teste de ligação SMTP.
• Token Cloudflare eliminado: foi removido através da API um token Cloudflare armazenado.

Todos os eventos da API de mensagens, incluindo leituras, envios, atualizações de indicadores, eliminações e movimentos, são totalmente registados. Os registos de auditoria são conservados durante 90 dias.

Cada evento regista o token usado, o recurso afetado, o endereço IP e um ID de pedido.

Filtre o registo de auditoria por tipo de evento, token ou intervalo de datas para investigar uma atividade específica.

Soluções rápidas

• A intenção expirou antes da confirmação: crie uma nova intenção de eliminação. As intenções expiram após 10 minutos.
• "Missing confirm header": adicione o cabeçalho X-Confirm-Delete: true ao pedido de confirmação.
• 429 na confirmação da eliminação: atingiu o limite diário ou o intervalo entre confirmações. Aguarde o período indicado por Retry-After.
• Um agente MCP autoalojado indica que as ferramentas de eliminação estão desativadas: o administrador local pode definir TREKMAIL_ALLOW_DESTRUCTIVE=true no ambiente desse processo MCP.
• Um agente MCP autoalojado indica "Sending is disabled": o administrador local pode definir TREKMAIL_ALLOW_SENDING=true no ambiente desse processo MCP.
• O agente MCP indica "Send not confirmed": o agente deve enviar confirm_send=true como parâmetro em cada chamada a send_message.
• Um agente MCP autoalojado indica que as ferramentas de migração estão desativadas: o administrador local pode definir TREKMAIL_ALLOW_MIGRATION=true no ambiente desse processo MCP.
• 503 "migration_capacity_reached": existem demasiadas migrações em execução em todo o servidor. Aguarde alguns minutos e tente novamente.
• 409 "active migration running": cancele a migração existente ou aguarde que termine antes de iniciar uma nova.