Beveiligingen en verwijderintenties

De TrekMail-API is ontworpen om onbedoeld gegevensverlies te voorkomen. Voor destructieve bewerkingen zijn meerdere bevestigingsstappen nodig, frequentielimieten voorkomen grootschalige fouten en elke actie wordt vastgelegd.

Prullenbak. Als je een verwijderintentie voor een mailbox bevestigt, wordt de mailbox nu naar een prullenbak met een bewaartermijn van 7 dagen verplaatst (in het dashboard weergegeven als Recent verwijderd) en niet meteen vernietigd. Je kunt verwijderde mailboxen weergeven en er binnen deze termijn een herstellen:

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

Na de bewaartermijn verwijdert een dagelijkse taak de mailboxen in de prullenbak definitief. Bij herstel wordt je mailboxlimiet per domein opnieuw gecontroleerd. MCP-agents gebruiken de tools restore_mailbox en list_trashed_mailboxes; confirm_delete_intent is nu herstelbaar en niet onomkeerbaar. Als je een domein of account verwijdert, worden de mailboxen daarvan definitief verwijderd zonder de prullenbak te gebruiken.

Verwijderen in twee stappen (verwijderintenties)

Het verwijderen van mailboxen en domeinen behoort tot de destructieve bewerkingen met de grootste gevolgen in de API. Hiervoor wordt een proces in twee stappen gebruikt:

Stap 1: maak een verwijderintentie

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

Hiermee maak je een tijdelijke intentie die beschrijft wat er wordt verwijderd. Het antwoord bevat:

• Risicovlaggen: waarschuwingen over doorstuurregels, aliassen of actieve migraties die worden beïnvloed.
• Vervaldatum: de intentie verloopt na 10 minuten. Daarna moet je een nieuwe maken.
• Bevestigings-URL: de URL die je voor stap 2 aanroept.

In deze fase worden geen gegevens verwijderd.

Stap 2: bevestig de intentie

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

Als de TrekMail-prullenbak voor mailboxen is ingeschakeld, verplaatst de bevestiging de mailbox naar Recent verwijderd en wordt een voltooide intentie met status: "executed" geretourneerd. De mailbox kan zeven dagen worden hersteld, mits het domein daarvoor ruimte heeft op het moment van herstel.

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

Na de herstelperiode verwijdert de dagelijkse opschoning van TrekMail de mailbox definitief. Gebruik voor die tijd de prullenbaklijst of het herstelendpoint. Bij het verwijderen van een domein of account wordt dit herstelpad voor mailboxen niet gebruikt.

De header X-Confirm-Delete: true is als extra veiligheidscontrole verplicht in het bevestigingsverzoek.

Risicovlaggen

Wanneer je een verwijderintentie maakt, controleert de API op omstandigheden die erop kunnen wijzen dat je niet wilt doorgaan:

Controleer deze vlaggen voordat je bevestigt. De API blokkeert de bevestiging niet op basis van risicovlaggen. Ze zijn alleen ter informatie.

Frequentielimieten voor destructieve bewerkingen

Voor destructieve bewerkingen gelden naast de standaard API-limiet per minuut nog twee beperkingslagen:

• Daglimiet per token: elk token kan per dag een beperkt aantal verwijderintenties bevestigen.
• Wachttijd tussen bevestigingen: na de bevestiging van een verwijdering geldt een korte wachttijd voordat de volgende bevestiging wordt geaccepteerd.

Wanneer een van beide wordt geactiveerd, wordt 429 Too Many Requests met een Retry-After-header geretourneerd.

MCP-veiligheidsbeheer voor lokaal gehoste servers

Als je de stdio-MCP-server zelf uitvoert, kan de beheerder TREKMAIL_ALLOW_DESTRUCTIVE=true vereisen voordat verwijdertools beschikbaar zijn. Dit is een lokale veiligheidsinstelling en geen functieschakelaar van het TrekMail-product. Gehoste MCP gebruikt de machtigingen die tijdens OAuth zijn goedgekeurd.

Leestools blijven beschikbaar binnen de verleende scopes. Controleer de taak en scopes van de agent voordat je verwijderacties toestaat.

Idempotentie

Schrijfendpoints waarvoor een Idempotency-Key vereist is, vermelden dit in de endpointtabel en OpenAPI-specificatie. Gebruik een nieuwe sleutel voor elke logische bewerking voordat je een verzoek opnieuw probeert:

Idempotency-Key: create-mailbox-alice-2024

• Dezelfde sleutel en dezelfde body geven het oorspronkelijke antwoord opnieuw zonder de bewerking te herhalen.
• Dezelfde sleutel en een andere body geven 409 Conflict terug.
• Verschillende tokens gebruiken onafhankelijke sleutelruimtes.

De MCP-server genereert herhalingsveilige idempotentiesleutels voor toolaanroepen, zodat een nieuwe poging een reeds voltooide bewerking niet herhaalt.

Veiligheidscontroles voor verzenden

Voor het verzenden van e-mail via de MCP-server geldt een eigen dubbele beveiliging, vergelijkbaar met de beveiliging voor destructieve bewerkingen maar met twee onafhankelijke controles:

Controle 1: lokaal serverbeheer

Stel voor een lokaal gehoste MCP-server TREKMAIL_ALLOW_SENDING=true in om de tool send_message toe te staan. Gehoste MCP gebruikt de machtigingen die tijdens OAuth zijn goedgekeurd.

Controle 2: bevestiging per aanroep

Zelfs als de omgevingscontrole is ingeschakeld, moet elke aanroep van send_message de parameter confirm_send=true bevatten. Zonder deze parameter geeft de tool een fout die de agent om bevestiging vraagt.

Waarom twee controles?

De lokale controle wordt eenmaal ingesteld door de beheerder die de MCP-server configureert. De controle per aanroep vereist dat de agent actief besluit elke e-mail te verzenden. Geen van beide controles is op zichzelf voldoende; beide moeten slagen voordat een e-mail de server verlaat.

Dit voorkomt onbedoelde verzendingen door agents die beschikbare tools verkennen zonder de gevolgen te begrijpen. Een agent kan berichten vrij weergeven en lezen met een berichtentoken, maar kan niets verzenden totdat aan beide veiligheidscontroles is voldaan.

Veiligheidscontroles voor migraties

Voor e-mailmigratie via de MCP-server gelden eigen veiligheidscontroles, vergelijkbaar met die voor verzending en destructieve bewerkingen.

Lokaal serverbeheer voor migraties

Stel voor een lokaal gehoste MCP-server TREKMAIL_ALLOW_MIGRATION=true in om schrijvende migratietools (start_migration, retry_migration, delete_migration) toe te staan. Gehoste MCP gebruikt de machtigingen die tijdens OAuth zijn goedgekeurd.

cancel_migration is altijd beschikbaar, ongeacht deze instelling. Het is een veiligheidsbewerking die altijd toegankelijk moet zijn om een ontspoorde migratie te stoppen.

Alleen-lezen migratietools (list_migrations, get_migration) werken zonder controles. test_migration_connection vereist TREKMAIL_ALLOW_MIGRATION=true, omdat deze tool uitgaande IMAP-verbindingen maakt.

Bevestiging per migratieaanroep

Elke schrijvende migratietool vereist een bevestigingsparameter:

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

Zonder de bevestigingsparameter geeft de tool een fout die de agent om bevestiging vraagt.

Serverbrede gelijktijdigheidslimiet

De API handhaaft een globale limiet voor gelijktijdige migraties (standaard: 20). Wanneer deze is bereikt, geven nieuwe migratieverzoeken 503 terug met migration_capacity_reached en retryable: true. Dit beschermt serverbronnen wanneer veel accounts tegelijkertijd migreren.

Auditregistratie

Elke wijzigende API-actie wordt vastgelegd in het auditlogboek, dat in het dashboard onder AI-agents en API → Auditlogboek staat. Gebeurtenissen zijn onder meer:

• Token gemaakt of ingetrokken: wie een bewerkingstoken heeft gemaakt of ingetrokken, en wanneer.
• Berichtentoken gemaakt of ingetrokken: wie een berichtentoken heeft gemaakt of ingetrokken.
• Intentie gemaakt: er is een verwijderintentie voor een specifieke mailbox gemaakt.
• Intentie bevestigd: het verwijderverzoek is geaccepteerd.
• Verwijdering uitgevoerd: de mailbox is naar Recent verwijderd verplaatst en de herstelperiode is begonnen.
• Intentie verlopen: een onbevestigde intentie is na 10 minuten verlopen.
• Mailbox gemaakt: er is via de API een nieuwe mailbox ingericht.
• Uitnodiging gemaakt: er is een uitnodiging voor het instellen van een mailbox verzonden.
• Doorsturen bijgewerkt: de doorstuurregels voor een mailbox zijn gewijzigd.
• DNS-hercontrole gestart: er is om DNS-verificatie voor een domein gevraagd.
• Migratie gestart: er is via de API een e-mailmigratie gestart.
• Migratie geannuleerd: een actieve migratie is geannuleerd.
• Migratie opnieuw geprobeerd: een mislukte of geannuleerde migratie is opnieuw geprobeerd.
• Migratie verwijderd: een migratierecord is verwijderd.
• Bericht gelezen: berichten zijn via de Berichten-API weergegeven of gelezen.
• Bericht verzonden: er is via de Berichten-API een e-mail verzonden.
• Verzenden van bericht mislukt: een poging om een e-mail te verzenden is mislukt.
• Berichtvlaggen bijgewerkt: berichtvlaggen (gelezen/ongelezen, met ster) zijn gewijzigd.
• Bericht verwijderd: een bericht is uit een mailboxmap verwijderd.
• Bericht verplaatst: een bericht is tussen mappen verplaatst.
• Domein gemaakt: er is via de API een domein toegevoegd.
• Domein verwijderd: er is via de API een domein verwijderd.
• Ticket gemaakt: er is via de API een ondersteuningsticket geopend.
• Ticket beantwoord: er is een antwoord op een ticket geplaatst.
• Ticket gesloten: een ticket is gesloten.
• SMTP geconfigureerd: SMTP-instellingen zijn bijgewerkt.
• SMTP-verbinding verwijderd: een aangepaste SMTP-verbinding is verwijderd.
• SMTP-test in wachtrij geplaatst: een SMTP-verbindingstest is gestart.
• Cloudflare-token verwijderd: een opgeslagen Cloudflare-token is via de API verwijderd.

Alle gebeurtenissen van de Berichten-API, waaronder lezen, verzenden, vlagwijzigingen, verwijderen en verplaatsen, worden volledig vastgelegd. Auditrecords worden 90 dagen bewaard.

Elke gebeurtenis legt het gebruikte token, de betrokken bron, het IP-adres en een verzoek-ID vast.

Filter het auditlogboek op gebeurtenistype, token of datumbereik om specifieke activiteiten te onderzoeken.

Snelle oplossingen

• Intentie verlopen voor bevestiging: maak een nieuwe verwijderintentie. Intenties verlopen na 10 minuten.
• "Missing confirm header": voeg de header X-Confirm-Delete: true toe aan het bevestigingsverzoek.
• 429 bij verwijderbevestiging: je hebt de daglimiet of wachttijd bereikt. Wacht gedurende de door Retry-After aangegeven periode.
• Een zelfgehoste MCP-agent meldt dat verwijdertools zijn uitgeschakeld: de lokale beheerder kan TREKMAIL_ALLOW_DESTRUCTIVE=true instellen in de omgeving van dat MCP-proces.
• Een zelfgehoste MCP-agent meldt "Sending is disabled": de lokale beheerder kan TREKMAIL_ALLOW_SENDING=true instellen in de omgeving van dat MCP-proces.
• De MCP-agent meldt "Send not confirmed": de agent moet bij elke aanroep van send_message de parameter confirm_send=true doorgeven.
• Een zelfgehoste MCP-agent meldt dat migratietools zijn uitgeschakeld: de lokale beheerder kan TREKMAIL_ALLOW_MIGRATION=true instellen in de omgeving van dat MCP-proces.
• 503 "migration_capacity_reached": er worden serverbreed te veel migraties uitgevoerd. Wacht enkele minuten en probeer het opnieuw.
• 409 "active migration running": annuleer de bestaande migratie of wacht tot deze is voltooid voordat je een nieuwe start.