Protezioni di sicurezza e intenti di eliminazione

L’API TrekMail è progettata per prevenire la perdita accidentale di dati. Le operazioni distruttive richiedono più passaggi di conferma, i limiti di frequenza prevengono gli errori su larga scala e ogni azione viene registrata.

Cestino. La conferma di un intento di eliminazione della casella ora sposta la casella in un cestino di 7 giorni (mostrato come Eliminati di recente nel pannello) anziché distruggerla immediatamente. Puoi elencare le caselle eliminate e ripristinarne una durante questo periodo:

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

Al termine del periodo di conservazione, un processo giornaliero elimina definitivamente le caselle nel cestino. Il ripristino verifica di nuovo il limite di caselle per dominio. Gli agenti MCP usano gli strumenti restore_mailbox e list_trashed_mailboxes; ora confirm_delete_intent è recuperabile e non irreversibile. L’eliminazione di un dominio o di un account rimuove definitivamente le relative caselle e non usa il cestino.

Eliminazione in due passaggi (intenti di eliminazione)

L’eliminazione di caselle e domini rientra tra le operazioni distruttive di maggiore impatto nell’API. Utilizza un processo in due passaggi:

Passaggio 1: crea un intento di eliminazione

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

Questa operazione crea un intento a tempo limitato che descrive ciò che verrà eliminato. La risposta include:

• Indicatori di rischio: avvisi relativi a regole di inoltro, alias o migrazioni attive che saranno interessati.
• Scadenza: l’intento scade dopo 10 minuti. In seguito dovrai crearne uno nuovo.
• URL di conferma: l’URL da chiamare per il passaggio 2.

In questa fase non viene eliminato alcun dato.

Passaggio 2: conferma l’intento

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

Con il cestino delle caselle TrekMail abilitato, la conferma sposta la casella in Eliminati di recente e restituisce un intento completato con status: "executed". La casella può essere ripristinata per sette giorni, purché il dominio abbia spazio disponibile al momento del ripristino.

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

Dopo il periodo di recupero, la pulizia giornaliera di TrekMail rimuove definitivamente la casella. Prima di allora usa l’elenco del cestino o l’endpoint di ripristino. L’eliminazione di un dominio o account non usa questo percorso di recupero delle caselle.

L’intestazione X-Confirm-Delete: true è obbligatoria nella richiesta di conferma come controllo di sicurezza aggiuntivo.

Indicatori di rischio

Quando crei un intento di eliminazione, l’API verifica la presenza di condizioni che potrebbero indicare che non vuoi procedere:

Esamina questi indicatori prima di confermare. L’API non blocca la conferma in base agli indicatori di rischio. Sono solo informativi.

Limiti di frequenza per le operazioni distruttive

Le operazioni distruttive hanno due livelli di limitazione oltre al normale limite API per minuto:

• Limite giornaliero per token: ogni token può confermare un numero limitato di intenti di eliminazione al giorno.
• Attesa tra le conferme: dopo aver confermato un’eliminazione, è prevista una breve attesa prima che venga accettata la conferma successiva.

Quando vengono attivati, entrambi restituiscono 429 Too Many Requests con un’intestazione Retry-After.

Controllo di sicurezza MCP per server ospitati localmente

Se esegui personalmente il server MCP stdio, l’amministratore può richiedere TREKMAIL_ALLOW_DESTRUCTIVE=true prima di rendere disponibili gli strumenti di eliminazione. Si tratta di un controllo di sicurezza locale, non di un interruttore di funzionalità del prodotto TrekMail. MCP ospitato usa le autorizzazioni approvate durante OAuth.

Gli strumenti di lettura rimangono disponibili negli ambiti concessi. Esamina l’attività e gli ambiti dell’agente prima di consentire le eliminazioni.

Idempotenza

Gli endpoint di scrittura che richiedono un Idempotency-Key lo indicano nella tabella degli endpoint e nella specifica OpenAPI. Usa una nuova chiave per ogni operazione logica prima di riprovare una richiesta:

Idempotency-Key: create-mailbox-alice-2024

• La stessa chiave e lo stesso corpo riproducono la risposta originale senza ripetere l’operazione.
• La stessa chiave e un corpo diverso restituiscono 409 Conflict.
• Token diversi usano spazi di chiavi indipendenti.

Il server MCP genera chiavi di idempotenza sicure contro le ripetizioni per le chiamate agli strumenti, quindi i nuovi tentativi non ripetono un’operazione già completata.

Protezioni di sicurezza per l’invio

L’invio di e-mail tramite il server MCP ha una propria protezione a doppio controllo, simile a quella delle operazioni distruttive ma con due verifiche indipendenti:

Controllo 1: controllo del server locale

Per un server MCP ospitato localmente, imposta TREKMAIL_ALLOW_SENDING=true per consentire lo strumento send_message. MCP ospitato usa le autorizzazioni approvate durante OAuth.

Controllo 2: conferma per ogni chiamata

Anche con il controllo dell’ambiente abilitato, ogni chiamata a send_message deve includere confirm_send=true come parametro. Senza questo parametro, lo strumento restituisce un errore che chiede conferma all’agente.

Perché due controlli?

Il controllo locale viene impostato una volta dall’amministratore che configura il server MCP. Il controllo per chiamata richiede che l’agente decida attivamente di inviare ogni e-mail. Nessun controllo è sufficiente da solo; entrambi devono essere superati prima che un’e-mail lasci il server.

Questo evita invii accidentali da parte di agenti che esplorano gli strumenti disponibili senza comprenderne le conseguenze. Un agente può elencare e leggere liberamente i messaggi con un token di messaggi, ma non può inviare finché entrambi i controlli di sicurezza non sono soddisfatti.

Protezioni di sicurezza per le migrazioni

La migrazione delle e-mail tramite il server MCP dispone di protezioni proprie, simili a quelle per l’invio e le operazioni distruttive.

Controllo del server locale per le migrazioni

Per un server MCP ospitato localmente, imposta TREKMAIL_ALLOW_MIGRATION=true per consentire gli strumenti di scrittura delle migrazioni (start_migration, retry_migration, delete_migration). MCP ospitato usa le autorizzazioni approvate durante OAuth.

cancel_migration è sempre disponibile indipendentemente da questa impostazione. È un’operazione di sicurezza che deve essere sempre accessibile per interrompere una migrazione fuori controllo.

Gli strumenti di migrazione di sola lettura (list_migrations, get_migration) funzionano senza controlli. test_migration_connection richiede TREKMAIL_ALLOW_MIGRATION=true perché effettua connessioni IMAP in uscita.

Conferma per ogni chiamata di migrazione

Ogni strumento di scrittura delle migrazioni richiede un parametro di conferma:

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

Senza il parametro di conferma, lo strumento restituisce un errore che chiede conferma all’agente.

Limite di concorrenza per l’intero server

L’API applica un limite globale alle migrazioni simultanee (valore predefinito: 20). Quando viene raggiunto, le nuove richieste di migrazione restituiscono 503 con migration_capacity_reached e retryable: true. Ciò protegge le risorse del server quando molti account effettuano la migrazione contemporaneamente.

Registrazione degli audit

Ogni azione API che modifica dati viene registrata nel registro di audit, visibile in Agenti IA e API → Registro di audit nel pannello. Gli eventi includono:

• Token creato o revocato: chi ha creato o revocato un token operativo e quando.
• Token di messaggi creato o revocato: chi ha creato o revocato un token di messaggi.
• Intento creato: è stato creato un intento di eliminazione per una casella specifica.
• Intento confermato: la richiesta di eliminazione è stata accettata.
• Eliminazione eseguita: la casella è stata spostata in Eliminati di recente ed è iniziato il periodo di recupero.
• Intento scaduto: un intento non confermato è scaduto dopo 10 minuti.
• Casella creata: è stata predisposta una nuova casella tramite l’API.
• Invito creato: è stato inviato un invito per configurare una casella.
• Inoltro aggiornato: sono state modificate le regole di inoltro di una casella.
• Nuova verifica DNS avviata: è stata richiesta la verifica DNS di un dominio.
• Migrazione avviata: è stata avviata una migrazione e-mail tramite l’API.
• Migrazione annullata: è stata annullata una migrazione in corso.
• Migrazione riprovata: è stata riprovata una migrazione non riuscita o annullata.
• Migrazione eliminata: è stato eliminato un record di migrazione.
• Messaggio letto: sono stati elencati o letti messaggi tramite l’API dei messaggi.
• Messaggio inviato: è stata inviata un’e-mail tramite l’API dei messaggi.
• Invio del messaggio non riuscito: un tentativo di invio e-mail non è riuscito.
• Indicatori del messaggio aggiornati: sono stati modificati gli indicatori del messaggio (letto/non letto, preferito).
• Messaggio eliminato: è stato eliminato un messaggio da una cartella della casella.
• Messaggio spostato: un messaggio è stato spostato tra cartelle.
• Dominio creato: è stato aggiunto un dominio tramite l’API.
• Dominio eliminato: è stato rimosso un dominio tramite l’API.
• Ticket creato: è stato aperto un ticket di assistenza tramite l’API.
• Risposta al ticket: è stata pubblicata una risposta in un ticket.
• Ticket chiuso: è stato chiuso un ticket.
• SMTP configurato: sono state aggiornate le impostazioni SMTP.
• Connessione SMTP eliminata: è stata rimossa una connessione SMTP personalizzata.
• Test SMTP messo in coda: è stato avviato un test della connessione SMTP.
• Token Cloudflare eliminato: è stato rimosso tramite l’API un token Cloudflare memorizzato.

Tutti gli eventi dell’API dei messaggi, incluse letture, invii, modifiche agli indicatori, eliminazioni e spostamenti, vengono registrati completamente. I record di audit vengono conservati per 90 giorni.

Ogni evento registra il token usato, la risorsa interessata, l’indirizzo IP e un ID di richiesta.

Filtra il registro di audit per tipo di evento, token o intervallo di date per esaminare attività specifiche.

Soluzioni rapide

• L’intento è scaduto prima della conferma: crea un nuovo intento di eliminazione. Gli intenti scadono dopo 10 minuti.
• "Missing confirm header": aggiungi l’intestazione X-Confirm-Delete: true alla richiesta di conferma.
• 429 durante la conferma dell’eliminazione: hai raggiunto il limite giornaliero o il periodo di attesa. Attendi il periodo indicato da Retry-After.
• Un agente MCP auto-ospitato segnala che gli strumenti di eliminazione sono disabilitati: l’amministratore locale può impostare TREKMAIL_ALLOW_DESTRUCTIVE=true nell’ambiente del processo MCP.
• Un agente MCP auto-ospitato segnala "Sending is disabled": l’amministratore locale può impostare TREKMAIL_ALLOW_SENDING=true nell’ambiente del processo MCP.
• L’agente MCP segnala "Send not confirmed": l’agente deve passare confirm_send=true come parametro in ogni chiamata a send_message.
• Un agente MCP auto-ospitato segnala che gli strumenti di migrazione sono disabilitati: l’amministratore locale può impostare TREKMAIL_ALLOW_MIGRATION=true nell’ambiente del processo MCP.
• 503 "migration_capacity_reached": troppe migrazioni sono in esecuzione sul server. Attendi alcuni minuti e riprova.
• 409 "active migration running": annulla la migrazione esistente o attendi che termini prima di avviarne una nuova.