API cliente: decidi la sorte delle tue email dal tuo server

A cosa serve

I filtri di Clean Mailbox si basano sui nostri motori e, con il modulo Regole YARA, sui pattern che scrivi tu. L'API cliente va oltre: è il tuo server a prendere la decisione. Per ogni email ricevuta dal tuo dominio, Clean Mailbox invia il messaggio a un URL HTTPS che ospiti tu e il tuo server risponde indicando cosa farne.

È l'opzione giusta quando la tua decisione dipende da dati che Clean Mailbox non possiede: il tuo CRM (il mittente è un cliente noto?), un elenco interno di fornitori, i tuoi motori di analisi, regole aziendali complesse e così via.

• il tuo server sceglie l'azione: non fare nulla, taggare l'oggetto o bloccare l'email;
• l'API viene chiamata una volta per email e per dominio (un'email indirizzata a tre persone dello stesso dominio = una sola chiamata);
• viene eseguita dopo l'antivirus e l'antispam e prima delle regole YARA: un'email già eliminata dall'antivirus o dall'antispam non le viene inviata;
• non può mai trattenere o perdere un'email per errore: in caso di problemi, l'email viene consegnata normalmente.

Dichiarare il tuo URL

Nell'interfaccia di Clean Mailbox, apri il tuo dominio, poi il menu API cliente. Il modulo è riservato agli amministratori del dominio e deve essere attivato sul dominio: se la voce di menu non è visibile, contattaci per farlo attivare.

1. Inserisci il tuo URL dell'API, ad esempio https://api.example.com/clean-mailbox, poi salva.
2. Un segreto di firma viene generato automaticamente e mostrato nella pagina (pulsanti Mostra e Copia). Ti servirà nel tuo codice per verificare la provenienza delle richieste.
3. Per rimuovere l'opzione, svuota il campo e salva (oppure usa Rimuovi l'API): il segreto viene eliminato contemporaneamente.

L'URL deve rispettare queste regole:

• solo HTTPS, con un certificato valido emesso da un'autorità pubblica per il nome host (nessun certificato autofirmato), TLS 1.2 minimo;
• un nome host completo: nessun indirizzo IP, nessuna credenziale nell'URL, nessun frammento (#), al massimo 2048 caratteri;
• il nome host deve risolvere a un indirizzo pubblico: un indirizzo privato, locale o riservato viene rifiutato;
• i reindirizzamenti non vengono mai seguiti: l'URL deve rispondere direttamente.

La richiesta inviata da Clean Mailbox

Clean Mailbox invia un POST HTTPS al tuo URL. Il corpo è l'email grezza, così com'è stata ricevuta (header e poi contenuto, con le codifiche originali: base64, quoted-printable, ecc.), fino a 5 MB. Oltre questo limite l'email non viene inviata all'API e viene consegnata.

Verificare la firma

Chiunque conosca il tuo URL può inviargli una richiesta. Per essere certo che una richiesta provenga da Clean Mailbox, il tuo server deve verificare la firma di ogni chiamata:

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

dove timestamp è il valore di X-CMB-Timestamp e body l'email grezza ricevuta. Il tuo server deve:

1. ricalcolare la firma e confrontarla in tempo costante (hash_equals in PHP, hmac.compare_digest in Python);
2. rifiutare una richiesta il cui timestamp si discosta dall'ora attuale di più di qualche minuto (protezione contro il replay);
3. rispondere 401 in entrambi i casi: Clean Mailbox consegna allora l'email, non perdi nulla.

Azioni: non fare nulla, taggare, bloccare

Il tuo server ha al massimo 2 secondi per rispondere. L'azione viene scelta nella risposta, in JSON di al massimo 4 KB:

{ "action": "none | tag | block", "tag": "[Suspect]", "reason": "testo breve, facoltativo" }

• action è obbligatorio, in minuscolo (none, tag o block);
• tag è obbligatorio con l'azione tag: al massimo 100 caratteri, nessun a capo né carattere di controllo (viene scritto nell'oggetto). Si somma ai tag delle regole YARA e dell'antispam, con il tag dell'API in prima posizione;
• reason è facoltativo, al massimo 200 caratteri: viene mostrato nell'interfaccia per un blocco («API cliente: …»). Non inserirvi dati personali;
• le chiavi sconosciute vengono ignorate, quindi il formato può evolvere senza compromettere il tuo codice;
• vengono considerati solo i codici 200 e 204: un 4xx o 5xx non viene mai interpretato come una decisione.

Garanzie e timeout

L'API non può mai causare la perdita o il trattenimento accidentale di un'email. Solo una risposta «block» valida blocca; in ogni altro caso l'email viene consegnata normalmente:

• timeout di 2 secondi superato (risoluzione DNS, connessione, TLS, invio e risposta inclusi);
• errore di rete, certificato non valido, server non disponibile;
• codice HTTP diverso da 200 o 204;
• JSON non valido, azione sconosciuta o tag non valido;
• email più grande di 5 MB.

• Punta a meno di 500 ms: il tempo di attesa viene sottratto alla consegna dell'email.
• Nessun nuovo tentativo: Clean Mailbox chiama la tua API una volta per email. Ma la stessa email può esserti inviata due volte (nuovo tentativo dopo un errore temporaneo): rispondi in modo idempotente.
• Non fare affidamento sull'API come unica protezione: se non è disponibile, la tua email non viene più filtrata da essa.

Server di esempio

Un esempio minimo in PHP: verifica la firma, poi risponde in base a una parola chiave di test trovata nell'email. Sostituisci la logica di test con i tuoi controlli.

<?php
const CMB_SECRET = 'INCOLLA_QUI_IL_SEGRETO';
$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);
// Verifica la firma e il timestamp (5 minuti al massimo)
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' => 'parola chiave di test']);
} elseif (str_contains($body, '[TAG-ME]')) {
    echo json_encode(['action' => 'tag', 'tag' => '[Test API]']);
} else {
    echo json_encode(['action' => 'none']);
}

Testare la tua configurazione

1. Distribuisci questo script su un server HTTPS (certificato valido) e imposta il segreto mostrato nell'interfaccia.
2. Dichiara il suo URL nella pagina API cliente del tuo dominio.
3. Invia un'email a un indirizzo del dominio con [TAG-ME], poi un'altra con [BLOCK-ME] nell'oggetto.
4. Verifica che la prima arrivi con il tag [Test API] e che la seconda venga bloccata (copia in quarantena).

Se non succede nulla, probabilmente una delle regole del contratto non è rispettata (firma, certificato, timeout, codice HTTP): l'email viene allora consegnata senza modifiche.

Seguire le decisioni

Le email gestite dalla tua API possono essere individuate nell'interfaccia:

• nella vista tempo reale, un blocco dell'API è mostrato come «API» (non «Regole») e un filtro API permette di vedere solo queste email;
• le email bloccate vengono conservate nella tua quarantena, dove puoi esaminarle e ripristinarle in caso di falso positivo;
• il motivo (reason) che restituisci viene mostrato per ogni blocco.

Domande frequenti

In cosa si differenzia dalle regole YARA?

Le regole YARA sono pattern che scrivi nell'interfaccia e che Clean Mailbox valuta direttamente, con gli stati inattiva, audit e attiva. L'API cliente affida la decisione al tuo server, così puoi usare i tuoi dati e la tua logica. Non ha una modalità «audit»: l'azione che restituisci viene applicata. Per testare in sicurezza, rispondi none e registra i log dalla tua parte.

Cosa succede se il mio server è inattivo?

L'email viene consegnata normalmente, senza passare dalla tua decisione. Non viene né trattenuta né persa.

Un'email bloccata va persa?

No. Viene conservata nella tua quarantena, dove puoi esaminarla e ripristinarla in caso di falso positivo.

Posso impostare l'API per tutti i miei domini in una volta sola?

L'URL è attualmente impostato dominio per dominio. Un URL comune per tutti i domini di un account è allo studio per il futuro.