EN FR
Fonctionnalités Comment ça marche Tarifs Contact Connexion
🕒 Dernière mise à jour : 14 octobre 2026

API client : décidez du sort de vos emails depuis votre propre serveur

Comprenez comment l'option « API client » de l'interface Clean Mailbox transmet vos emails à une URL que vous hébergez, et comment votre serveur répond par l'action à mener : ne rien faire, taguer ou bloquer.

id="usage">
⚠️

Fonctionnalité en version bêta : l'API client est actuellement en bêta. Son fonctionnement et son interface peuvent évoluer, et des imperfections sont possibles. N'hésitez pas à nous faire part de vos retours.

À quoi ça sert

Les filtres de Clean Mailbox s'appuient sur nos moteurs et, avec le module Règles Yara, sur des motifs que vous écrivez. L'API client va plus loin : c'est votre propre serveur qui décide. Pour chaque email reçu par votre domaine, Clean Mailbox envoie le message à une URL HTTPS que vous hébergez, et votre serveur répond ce qu'il faut en faire.

C'est l'option adaptée si votre décision dépend de données que Clean Mailbox ne connaît pas : votre CRM (l'expéditeur est-il un client connu ?), une liste interne de fournisseurs, vos propres moteurs d'analyse, des règles métier complexes, etc.

⚠️

Contenu des emails : en activant cette option, le contenu complet de vos emails est transmis au serveur dont vous déclarez l'URL. Assurez-vous que cet hébergement respecte vos exigences de sécurité et de confidentialité (RGPD notamment).

Déclarer votre URL

Dans l'interface Clean Mailbox, ouvrez votre domaine puis le menu API client. Le module est réservé aux administrateurs du domaine et doit être activé sur celui-ci : si l'entrée de menu n'apparaît pas, contactez-nous pour l'activer.

  1. Saisissez l'URL de votre API, par exemple https://api.exemple.fr/clean-mailbox, puis enregistrez.
  2. Un secret de signature est généré automatiquement et affiché sur la page (bouton Afficher puis Copier). Vous en aurez besoin dans votre code pour vérifier l'origine des requêtes.
  3. Pour retirer l'option, videz le champ et enregistrez (ou utilisez Retirer l'API) : le secret est supprimé en même temps.

L'URL doit respecter les règles suivantes :

💡

Si vous filtrez les connexions entrantes par adresse IP, demandez à notre support la liste des serveurs d'analyse de Clean Mailbox à autoriser. Si le secret est régénéré (bouton Générer un nouveau secret), l'ancien cesse de fonctionner immédiatement : mettez votre serveur à jour aussitôt.

La requête envoyée par Clean Mailbox

Clean Mailbox envoie un POST HTTPS à votre URL. Le corps est l'email brut, tel qu'il a été reçu (en-têtes puis contenu, avec les encodages d'origine : base64, quoted-printable, etc.), dans la limite de 5 Mo. Au-delà, l'email n'est pas envoyé à l'API et il est livré.

En-têteValeur
Content-Typemessage/rfc822
X-CMB-API-Version1
X-CMB-Domaindomaine destinataire concerné
X-CMB-Recipientsadresses destinataires de ce domaine, séparées par des virgules
X-CMB-Envelope-Fromexpéditeur d'enveloppe (vide pour un message de rebond)
X-CMB-Client-IPadresse IP du serveur qui a envoyé l'email
X-CMB-Queue-Ididentifiant de file (utile pour nous communiquer un cas)
X-CMB-Timestampheure d'envoi, en secondes Unix
X-CMB-Signaturev1= suivi de la signature

Vérifier la signature

N'importe qui connaissant votre URL peut lui envoyer une requête. Pour être certain qu'elle vient de Clean Mailbox, votre serveur doit impérativement vérifier la signature de chaque appel :

signature = hex( HMAC-SHA256( secret, timestamp + "." + corps ) )
en-tête   : X-CMB-Signature: v1=<signature>

où timestamp est la valeur de X-CMB-Timestamp et corps l'email brut reçu. Votre serveur doit :

  1. recalculer la signature et la comparer en temps constant (hash_equals en PHP, hmac.compare_digest en Python) ;
  2. refuser une requête dont l'horodatage s'écarte de plus de quelques minutes de l'heure actuelle (protection contre le rejeu) ;
  3. répondre 401 dans les deux cas : Clean Mailbox livre alors l'email, vous ne perdez rien.
⚠️

Ne mettez jamais le secret dans l'URL ni dans un dépôt public. Sans vérification de la signature, un tiers pourrait appeler votre API en se faisant passer pour Clean Mailbox.

Les actions : ne rien faire, taguer, bloquer

Votre serveur dispose de 2 secondes au plus pour répondre. L'action se choisit dans la réponse, en JSON de 4 Ko au plus :

{ "action": "none | tag | block", "tag": "[Suspect]", "reason": "texte court, facultatif" }
Réponse de votre serveurEffet sur l'email
204 No Content (sans corps), ou 200 avec {"action": "none"} Ne rien faire : l'email est livré normalement.
200 avec {"action": "tag", "tag": "[Suspect]"} Taguer : l'email est livré, avec [Suspect] ajouté au début du sujet.
200 avec {"action": "block", "reason": "texte court"} Bloquer : l'email n'est pas livré et l'expéditeur ne voit rien. Une copie est conservée dans votre quarantaine.
Toute autre réponse L'email est livré, rien n'est modifié.

Garanties et délais

L'API ne peut jamais faire perdre ou retenir un email par accident. Seule une réponse correcte « bloquer » bloque ; dans tous les autres cas, l'email est livré normalement :

Exemple de serveur

Un exemple minimal en PHP : il vérifie la signature, puis répond selon un mot-clé de test présent dans l'email. Remplacez la logique de test par vos propres contrôles.

<?php
const CMB_SECRET = 'COLLEZ_ICI_LE_SECRET';

$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);

// Vérifier la signature et l'horodatage (5 minutes au plus)
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' => 'mot-clé de test']);
} elseif (str_contains($body, '[TAG-ME]')) {
    echo json_encode(['action' => 'tag', 'tag' => '[Test API]']);
} else {
    echo json_encode(['action' => 'none']);
}

Tester votre configuration

  1. Déployez ce script sur un serveur HTTPS (certificat valide) et renseignez le secret affiché dans l'interface.
  2. Déclarez son URL dans la page API client de votre domaine.
  3. Envoyez à une adresse du domaine un email avec [TAG-ME] puis un autre avec [BLOCK-ME] dans le sujet.
  4. Vérifiez que le premier arrive avec le tag [Test API] et que le second est bloqué (copie en quarantaine).

Si rien ne se passe, c'est probablement qu'une règle du contrat n'est pas respectée (signature, certificat, délai, code HTTP) : l'email est alors livré sans modification.

Suivre les décisions

Les emails traités par votre API sont identifiables dans l'interface :

Questions fréquentes

Quelle différence avec les Règles Yara ?

Les règles Yara sont des motifs que vous écrivez dans l'interface et que Clean Mailbox évalue lui-même, avec les statuts inactive, audit et active. L'API client déporte la décision sur votre serveur, ce qui permet d'utiliser vos propres données et logiques. Elle n'a pas de mode « audit » : l'action que vous renvoyez est appliquée. Pour tester sans risque, répondez none et journalisez de votre côté.

Que se passe-t-il si mon serveur est en panne ?

Les emails sont livrés normalement, sans passer par votre décision. Ils ne sont ni retenus ni perdus.

Un email bloqué est-il perdu ?

Non. Il est conservé dans votre quarantaine, où vous pouvez le consulter et le restaurer en cas de faux positif.

Puis-je définir l'API pour tous mes domaines ?

L'URL se définit aujourd'hui domaine par domaine. Une URL commune à tous les domaines d'un compte est envisagée pour plus tard.

Besoin d'aide pour activer l'option ?

Notre support peut vous aider à activer l'API client sur votre domaine et à valider sa configuration. Le développement, l'hébergement et la disponibilité de votre serveur restent de votre responsabilité.

Contacter Clean Mailbox →

Protégeons votre boîte mail.

Questions sur l'essai, la configuration, les tarifs ou un partenariat ? Nous sommes là — et nous répondons vite.

✓ Essai 30 jours, sans carte bancaire
✓ Compatible avec tous les serveurs mail
✓ Mise en place en moins de 5 minutes
✓ Infrastructure hébergée en France 🇫🇷