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

A API TrekMail foi projetada para evitar a perda acidental de dados. As operações destrutivas exigem várias etapas de confirmação, os limites de taxa evitam erros em massa e todas as ações são registradas.

Lixeira. Confirmar uma intenção de exclusão de caixa de correio agora move a caixa para uma lixeira de 7 dias (exibida como Excluídos recentemente no painel), em vez de destruí-la na hora. Você pode listar as caixas excluídas 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 exclui definitivamente as caixas na lixeira. A restauração verifica de novo o limite de caixas por domínio e, para uma caixa com tamanho fixo, se esse tamanho ainda cabe no espaço livre e, quando o domínio tem um, no limite de armazenamento do cliente (caso contrário, mailbox_limit_reached ou storage_pool_exceeded). Os agentes MCP usam as ferramentas restore_mailbox e list_trashed_mailboxes; confirm_delete_intent agora é recuperável, não irreversível. Excluir um domínio ou uma conta remove as caixas dele definitivamente e não usa a lixeira.

Exclusão em duas etapas (intenções de exclusão)

A exclusão de caixas de correio e de domínios está entre as operações destrutivas de maior impacto na API. Ela usa um processo em duas etapas:

Etapa 1: criar uma intenção de exclusão

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

Isso cria uma intenção temporária que descreve o que será excluído. A resposta inclui:

• Indicadores de risco: avisos sobre regras de encaminhamento, aliases ou migrações ativas que serão afetados.
• Expiração: a intenção expira após 10 minutos. Depois disso, você precisa criar uma nova.
• URL de confirmação: o URL a chamar na etapa 2.

Nenhum dado é excluído nesta fase.

Etapa 2: confirmar a intenção

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

Com a lixeira de caixas do TrekMail ativada, a confirmação move a caixa para Excluídos recentemente e retorna uma intenção concluída com status: "executed". A caixa pode ser restaurada durante sete dias, desde que o domínio ainda tenha uma vaga para caixas e, para uma caixa com tamanho fixo, que esse tamanho caiba no espaço livre e, quando o domínio tem um, no limite de armazenamento do cliente.

{
  "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"
}

Depois do período de recuperação, a limpeza diária do TrekMail remove a caixa definitivamente. Antes disso, use a lista da lixeira ou o endpoint de restauração. A exclusão de um domínio ou de uma conta não segue esse caminho de recuperação de caixas.

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

Indicadores de risco

Ao criar uma intenção de exclusão, a API procura condições que possam indicar que você não quer continuar:

Revise esses indicadores antes de confirmar. A API não bloqueia a confirmação com base nos indicadores de risco. Eles servem apenas como informação.

Limites de taxa 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 exclusão por dia.
• Intervalo entre confirmações: depois de confirmar uma exclusão, há um breve intervalo antes que a próxima confirmação seja aceita.

Quando acionados, os dois retornam 429 Too Many Requests com um cabeçalho Retry-After.

Controle de segurança do MCP para servidores hospedados localmente

Se você executa o servidor MCP stdio, o administrador pode exigir TREKMAIL_ALLOW_DESTRUCTIVE=true antes de liberar as ferramentas de exclusão. Esse é um controle de segurança local, não uma chave de recurso do produto TrekMail. O MCP hospedado usa as permissões aprovadas durante o OAuth.

As ferramentas de leitura continuam disponíveis dentro dos escopos concedidos. Revise a tarefa e os escopos do agente antes de permitir exclusões.

Idempotência

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

Idempotency-Key: create-mailbox-alice-2024

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

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

Proteções de segurança para o envio

O envio de e-mails pelo servidor MCP tem o próprio modelo de segurança com dois controles, parecido com o das operações destrutivas, mas com duas verificações independentes:

Controle 1: controle do servidor local

Em um servidor MCP hospedado localmente, defina TREKMAIL_ALLOW_SENDING=true para liberar a ferramenta send_message. O MCP hospedado usa as permissões aprovadas durante o OAuth.

Controle 2: confirmação por chamada

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

Por que dois controles?

O controle local é definido uma vez pelo administrador que configura o servidor MCP. O controle por chamada exige que o agente decida ativamente enviar cada mensagem. Nenhum dos controles basta sozinho; os dois precisam ser atendidos antes que qualquer mensagem saia do servidor.

Isso evita envios acidentais por agentes que exploram as ferramentas disponíveis sem entender as consequências. Um agente pode listar e ler mensagens livremente com um token de mensagens, mas não pode enviar até que os dois controles sejam atendidos.

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

A migração de e-mails pelo servidor MCP tem as próprias proteções, parecidas com as do envio e das operações destrutivas.

Controle do servidor local para migrações

Em um servidor MCP hospedado localmente, defina TREKMAIL_ALLOW_MIGRATION=true para liberar as ferramentas de gravação de migrações (start_migration, retry_migration, delete_migration). O MCP hospedado usa as permissões aprovadas durante o OAuth.

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

As ferramentas de migração somente leitura (list_migrations, get_migration) funcionam sem controles. test_migration_connection exige TREKMAIL_ALLOW_MIGRATION=true, porque abre conexões IMAP de saída.

Confirmação por chamada para migrações

Cada ferramenta de gravação 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 retorna um erro que pede confirmação ao agente.

Limite de simultaneidade em todo o servidor

A API aplica um limite global de migrações simultâneas (padrão: 20). Quando o limite é atingido, as novas solicitações de migração retornam 503 com migration_capacity_reached e retryable: true. Isso protege os recursos do servidor quando muitas contas migram ao mesmo tempo.

Registro de auditoria

Todas as ações da API que alteram algo ficam no registro de auditoria, visível em Agentes 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 exclusão para uma caixa específica.
• Intenção confirmada: a solicitação de exclusão foi aceita.
• Exclusão executada: a caixa foi movida para Excluídos recentemente e começou o período de recuperação dela.
• Intenção expirada: uma intenção não confirmada expirou após 10 minutos.
• Caixa criada: uma nova caixa foi provisionada pela API.
• Convite criado: foi enviado um convite de configuração de caixa.
• Encaminhamento atualizado: as regras de encaminhamento de uma caixa foram alteradas.
• Nova verificação de DNS iniciada: foi solicitada uma verificação de DNS para um domínio.
• Migração iniciada: uma migração de e-mails foi iniciada pela API.
• Migração cancelada: uma migração em andamento foi cancelada.
• Migração repetida: uma migração que falhou ou foi cancelada foi executada de novo.
• Migração excluída: um registro de migração foi excluído.
• Mensagem lida: mensagens foram listadas ou lidas pela API de mensagens.
• Mensagem enviada: uma mensagem foi enviada pela API de mensagens.
• Falha no envio da mensagem: uma tentativa de envio de mensagem falhou.
• Indicadores da mensagem atualizados: os indicadores da mensagem foram alterados (lida/não lida, sinalizada).
• Mensagem excluída: uma mensagem foi excluída de uma pasta da caixa.
• Mensagem movida: uma mensagem foi movida entre pastas.
• Domínio criado: um domínio foi adicionado pela API.
• Domínio excluído: um domínio foi removido pela API.
• Ticket de suporte criado: um ticket de suporte foi aberto pela API.
• Resposta ao ticket de suporte: uma resposta foi publicada em um ticket.
• Ticket de suporte fechado: um ticket de suporte foi fechado.
• SMTP configurado: as configurações de SMTP foram atualizadas.
• Conexão SMTP excluída: uma conexão SMTP personalizada foi removida.
• Teste SMTP na fila: um teste de conexão SMTP foi iniciado.
• Token da Cloudflare excluído: um token da Cloudflare armazenado foi removido pela API.

Todos os eventos da API de mensagens, incluindo leituras, envios, atualizações de indicadores, exclusões e movimentações, são registrados por completo. Os registros de auditoria são mantidos por 90 dias.

Cada evento registra o token usado, o recurso afetado, o endereço IP e um ID de solicitação.

Filtre o registro 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 exclusão. As intenções expiram após 10 minutos.
• "Missing confirm header": adicione o cabeçalho X-Confirm-Delete: true à solicitação de confirmação.
• 429 ao confirmar a exclusão: você atingiu o limite diário ou o intervalo entre confirmações. Aguarde o período indicado por Retry-After.
• Um agente MCP auto-hospedado informa que as ferramentas de exclusão estão desativadas: o administrador local pode definir TREKMAIL_ALLOW_DESTRUCTIVE=true no ambiente desse processo MCP.
• Um agente MCP auto-hospedado informa "Sending is disabled": o administrador local pode definir TREKMAIL_ALLOW_SENDING=true no ambiente desse processo MCP.
• O agente MCP informa "Send not confirmed": o agente precisa enviar confirm_send=true como parâmetro em cada chamada a send_message.
• Um agente MCP auto-hospedado informa 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": há migrações demais em execução em todo o servidor. Aguarde alguns minutos e tente de novo.
• 409 "active migration running": cancele a migração existente ou espere ela terminar antes de iniciar uma nova.