Klant-API: bepaal vanaf uw eigen server wat er met uw e-mail gebeurt

Waarvoor het dient

De filters van Clean Mailbox zijn gebaseerd op onze engines en, met de module Yara-regels, op patronen die u zelf schrijft. De Klant-API gaat verder: uw eigen server neemt de beslissing. Voor elke e-mail die uw domein ontvangt, stuurt Clean Mailbox het bericht naar een HTTPS-URL die u host, en uw server antwoordt wat ermee moet gebeuren.

Het is de juiste optie wanneer uw beslissing afhangt van gegevens die Clean Mailbox niet heeft: uw CRM (is de afzender een bekende klant?), een interne leverancierslijst, uw eigen analyse-engines, complexe bedrijfsregels enzovoort.

• uw server kiest de actie: niets doen, het onderwerp taggen of de e-mail blokkeren;
• de API wordt één keer per e-mail en per domein aangeroepen (een e-mail aan drie personen van hetzelfde domein = één enkele aanroep);
• ze wordt uitgevoerd na de antivirus en antispam en vóór de Yara-regels: een e-mail die al door de antivirus of antispam is verwijderd, wordt er niet naartoe gestuurd;
• ze kan nooit per ongeluk een e-mail tegenhouden of kwijtmaken: als er iets misgaat, wordt de e-mail normaal afgeleverd.

Uw URL opgeven

Open in de Clean Mailbox-interface uw domein en vervolgens het menu Klant-API. De module is voorbehouden aan domeinbeheerders en moet op het domein zijn ingeschakeld: ziet u het menu-item niet, neem dan contact met ons op om het te laten activeren.

1. Voer uw API-URL in, bijvoorbeeld https://api.example.com/clean-mailbox, en sla op.
2. Er wordt automatisch een ondertekeningsgeheim gegenereerd en op de pagina weergegeven (knoppen Tonen en dan Kopiëren). U hebt het nodig in uw code om te controleren waar verzoeken vandaan komen.
3. Om de optie te verwijderen, wist u het veld en slaat u op (of gebruikt u API verwijderen): het geheim wordt tegelijkertijd verwijderd.

De URL moet aan de volgende regels voldoen:

• alleen HTTPS, met een geldig certificaat van een openbare autoriteit voor de hostnaam (geen zelfondertekend certificaat), minimaal TLS 1.2;
• een volledige hostnaam: geen IP-adres, geen inloggegevens in de URL, geen fragment (#), maximaal 2048 tekens;
• de hostnaam moet naar een openbaar adres verwijzen: een privé-, lokaal of gereserveerd adres wordt geweigerd;
• redirects worden nooit gevolgd: de URL moet rechtstreeks antwoorden.

Het verzoek van Clean Mailbox

Clean Mailbox stuurt een HTTPS-POST naar uw URL. De body is de ruwe e-mail zoals die is ontvangen (headers en daarna inhoud, met de oorspronkelijke coderingen: base64, quoted-printable enz.), tot 5 MB. Daarboven wordt de e-mail niet naar de API gestuurd maar afgeleverd.

De handtekening controleren

Iedereen die uw URL kent, kan er een verzoek naartoe sturen. Om zeker te weten dat een verzoek van Clean Mailbox komt, moet uw server de handtekening van elke aanroep controleren:

signature = hex( HMAC-SHA256( secret, timestamp + "." + body ) )
header    : X-CMB-Signature: v1=<signature>

waarbij timestamp de waarde van X-CMB-Timestamp is en body de ontvangen ruwe e-mail. Uw server moet:

1. de handtekening opnieuw berekenen en in constante tijd vergelijken (hash_equals in PHP, hmac.compare_digest in Python);
2. een verzoek weigeren waarvan de timestamp meer dan een paar minuten van de huidige tijd afwijkt (bescherming tegen replay);
3. in beide gevallen 401 antwoorden: Clean Mailbox levert de e-mail dan af, u verliest niets.

Acties: niets doen, taggen, blokkeren

Uw server heeft maximaal 2 seconden om te antwoorden. De actie wordt gekozen in het antwoord, als JSON van maximaal 4 KB:

{ "action": "none | tag | block", "tag": "[Suspect]", "reason": "korte tekst, optioneel" }

• action is verplicht, in kleine letters (none, tag of block);
• tag is verplicht bij de actie tag: maximaal 100 tekens, geen regeleinde of stuurteken (het wordt in het onderwerp geschreven). Het wordt opgeteld bij de tags van Yara-regels en antispam, waarbij de tag van de API vooraan staat;
• reason is optioneel, maximaal 200 tekens: het wordt bij een blokkade in de interface getoond ("Klant-API: …"). Zet er geen persoonsgegevens in;
• onbekende sleutels worden genegeerd, zodat het formaat kan evolueren zonder uw code te breken;
• alleen de codes 200 en 204 worden in aanmerking genomen: een 4xx of 5xx wordt nooit als beslissing geïnterpreteerd.

Garanties en time-outs

De API kan er nooit voor zorgen dat een e-mail per ongeluk verloren gaat of wordt tegengehouden. Alleen een geldig antwoord "block" blokkeert; in alle andere gevallen wordt de e-mail normaal afgeleverd:

• time-out van 2 seconden overschreden (inclusief DNS-resolutie, verbinding, TLS, verzending en antwoord);
• netwerkfout, ongeldig certificaat, server niet beschikbaar;
• andere HTTP-code dan 200 of 204;
• ongeldige JSON, onbekende actie of ongeldige tag;
• e-mail groter dan 5 MB.

• Mik op minder dan 500 ms: de wachttijd gaat af van de aflevering van de e-mail.
• Geen nieuwe poging: Clean Mailbox roept uw API één keer per e-mail aan. Maar dezelfde e-mail kan u twee keer worden gestuurd (nieuwe poging na een tijdelijke fout): antwoord idempotent.
• Vertrouw niet op de API als uw enige bescherming: als ze niet beschikbaar is, wordt uw e-mail er niet meer door gefilterd.

Voorbeeldserver

Een minimaal PHP-voorbeeld: het controleert de handtekening en antwoordt vervolgens op basis van een testtrefwoord in de e-mail. Vervang de testlogica door uw eigen controles.

<?php
const CMB_SECRET = 'PLAK_HIER_HET_GEHEIM';

$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_CMB_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_CMB_SIGNATURE'] ?? '';
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $body, CMB_SECRET);

// Controleer de handtekening en de timestamp (maximaal 5 minuten)
if (!ctype_digit($ts) || abs(time() - (int) $ts) > 300 || !hash_equals($expected, $sig)) {
    http_response_code(401);
    exit;
}

header('Content-Type: application/json');

if (str_contains($body, '[BLOCK-ME]')) {
    echo json_encode(['action' => 'block', 'reason' => 'testtrefwoord']);
} elseif (str_contains($body, '[TAG-ME]')) {
    echo json_encode(['action' => 'tag', 'tag' => '[API test]']);
} else {
    echo json_encode(['action' => 'none']);
}

Uw configuratie testen

1. Zet dit script op een HTTPS-server (geldig certificaat) en stel het in de interface getoonde geheim in.
2. Geef de URL op in de pagina Klant-API van uw domein.
3. Stuur een e-mail naar een adres van het domein met [TAG-ME] en daarna een andere met [BLOCK-ME] in het onderwerp.
4. Controleer of de eerste aankomt met de tag [API test] en of de tweede wordt geblokkeerd (kopie in quarantaine).

Gebeurt er niets, dan is waarschijnlijk een van de regels van het contract niet nageleefd (handtekening, certificaat, time-out, HTTP-code): de e-mail wordt dan ongewijzigd afgeleverd.

De beslissingen volgen

E-mails die door uw API zijn afgehandeld, kunt u in de interface herkennen:

• in de realtime-weergave wordt een API-blokkade getoond als "API" (niet "Regels"), en met een API-filter ziet u alleen die e-mails;
• geblokkeerde e-mails blijven bewaard in uw quarantaine, waar u ze kunt bekijken en bij een fout-positief kunt herstellen;
• de reden (reason) die u terugstuurt, wordt bij elke blokkade getoond.

Veelgestelde vragen

Wat is het verschil met Yara-regels?

Yara-regels zijn patronen die u in de interface schrijft en die Clean Mailbox zelf evalueert, met de statussen inactief, audit en actief. De Klant-API draagt de beslissing over aan uw server, zodat u uw eigen gegevens en logica kunt gebruiken. Er is geen "audit"-modus: de actie die u teruggeeft wordt toegepast. Om veilig te testen antwoordt u none en logt u aan uw kant.

Wat gebeurt er als mijn server uitvalt?

De e-mail wordt normaal afgeleverd, zonder langs uw beslissing te gaan. Hij wordt niet tegengehouden en gaat niet verloren.

Gaat een geblokkeerde e-mail verloren?

Nee. Hij wordt bewaard in uw quarantaine, waar u hem kunt bekijken en bij een fout-positief kunt herstellen.

Kan ik de API voor al mijn domeinen tegelijk instellen?

De URL wordt momenteel per domein ingesteld. Een gemeenschappelijke URL voor alle domeinen van een account wordt voor later overwogen.