Kunden-API: über das Schicksal Ihrer E-Mails von Ihrem eigenen Server aus entscheiden

Wofür sie dient

Die Filter von Clean Mailbox stützen sich auf unsere Engines und, mit dem Modul YARA-Regeln, auf von Ihnen geschriebene Muster. Die Kunden-API geht weiter: Ihr eigener Server trifft die Entscheidung. Für jede an Ihre Domain gerichtete E-Mail sendet Clean Mailbox die Nachricht an eine von Ihnen gehostete HTTPS-URL, und Ihr Server antwortet, was damit geschehen soll.

Sie ist die richtige Option, wenn Ihre Entscheidung von Daten abhängt, die Clean Mailbox nicht hat: Ihr CRM (ist der Absender ein bekannter Kunde?), eine interne Lieferantenliste, Ihre eigenen Analyse-Engines, komplexe Geschäftsregeln und so weiter.

• Ihr Server wählt die Aktion: nichts tun, den Betreff markieren oder die E-Mail blockieren;
• die API wird einmal pro E-Mail und pro Domain aufgerufen (eine E-Mail an drei Personen derselben Domain = ein einziger Aufruf);
• sie läuft nach dem Virenschutz und dem Spamschutz und vor den YARA-Regeln: Eine E-Mail, die bereits vom Virenschutz oder Spamschutz entfernt wurde, wird nicht an sie gesendet;
• sie kann nie versehentlich eine E-Mail zurückhalten oder verlieren: Geht etwas schief, wird die E-Mail normal zugestellt.

Ihre URL angeben

Öffnen Sie in der Clean-Mailbox-Oberfläche Ihre Domain und dann das Menü Kunden-API. Das Modul ist den Domain-Administratoren vorbehalten und muss für die Domain aktiviert sein: Ist der Menüeintrag nicht sichtbar, kontaktieren Sie uns, damit wir ihn aktivieren.

1. Geben Sie Ihre API-URL ein, zum Beispiel https://api.example.com/clean-mailbox, und speichern Sie.
2. Ein Signaturschlüssel wird automatisch erzeugt und auf der Seite angezeigt (Schaltflächen Anzeigen und Kopieren). Sie benötigen ihn in Ihrem Code, um die Herkunft der Anfragen zu prüfen.
3. Um die Option zu entfernen, leeren Sie das Feld und speichern Sie (oder nutzen Sie API entfernen): Der Schlüssel wird dabei gelöscht.

Die URL muss diese Regeln erfüllen:

• nur HTTPS, mit einem gültigen Zertifikat einer öffentlichen Zertifizierungsstelle für den Hostnamen (kein selbstsigniertes Zertifikat), mindestens TLS 1.2;
• ein vollständiger Hostname: keine IP-Adresse, keine Zugangsdaten in der URL, kein Fragment (#), höchstens 2048 Zeichen;
• der Hostname muss auf eine öffentliche Adresse auflösen: Eine private, lokale oder reservierte Adresse wird abgelehnt;
• Weiterleitungen werden nie verfolgt: Die URL muss direkt antworten.

Die von Clean Mailbox gesendete Anfrage

Clean Mailbox sendet einen HTTPS-POST an Ihre URL. Der Body ist die Roh-E-Mail so, wie sie empfangen wurde (Header, dann Inhalt, mit den ursprünglichen Kodierungen: Base64, Quoted-Printable usw.), bis zu 5 MB. Darüber hinaus wird die E-Mail nicht an die API gesendet, sondern zugestellt.

Die Signatur prüfen

Jeder, der Ihre URL kennt, kann ihr eine Anfrage senden. Um sicher zu sein, dass eine Anfrage von Clean Mailbox stammt, muss Ihr Server bei jedem Aufruf die Signatur prüfen:

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

Dabei ist timestamp der Wert von X-CMB-Timestamp und body die empfangene Roh-E-Mail. Ihr Server muss:

1. die Signatur neu berechnen und in konstanter Zeit vergleichen (hash_equals in PHP, hmac.compare_digest in Python);
2. eine Anfrage ablehnen, deren Zeitstempel um mehr als einige Minuten von der aktuellen Zeit abweicht (Schutz vor Wiedereinspielung);
3. in beiden Fällen mit 401 antworten: Clean Mailbox stellt die E-Mail dann zu, Sie verlieren nichts.

Aktionen: nichts tun, markieren, blockieren

Ihr Server hat höchstens 2 Sekunden Zeit zu antworten. Die Aktion wird in der Antwort gewählt, als JSON von höchstens 4 KB:

{ "action": "none | tag | block", "tag": "[Suspect]", "reason": "kurzer Text, optional" }

• action ist erforderlich, in Kleinbuchstaben (none, tag oder block);
• tag ist bei der Aktion tag erforderlich: höchstens 100 Zeichen, kein Zeilenumbruch und kein Steuerzeichen (er wird in den Betreff geschrieben). Er wird zu den Tags der YARA-Regeln und des Spamschutzes addiert, wobei der Tag der API zuerst steht;
• reason ist optional, höchstens 200 Zeichen: Er wird in der Oberfläche bei einer Blockierung angezeigt („Kunden-API: …“). Geben Sie darin keine personenbezogenen Daten an;
• unbekannte Schlüssel werden ignoriert, sodass sich das Format weiterentwickeln kann, ohne Ihren Code zu beeinträchtigen;
• nur die Codes 200 und 204 werden berücksichtigt: Ein 4xx oder 5xx wird nie als Entscheidung interpretiert.

Garantien und Zeitlimits

Die API kann nie dazu führen, dass eine E-Mail versehentlich verloren geht oder zurückgehalten wird. Nur eine gültige Antwort „block“ blockiert; in jedem anderen Fall wird die E-Mail normal zugestellt:

• Zeitlimit von 2 Sekunden überschritten (einschließlich DNS-Auflösung, Verbindung, TLS, Senden und Antwort);
• Netzwerkfehler, ungültiges Zertifikat, Server nicht verfügbar;
• anderer HTTP-Code als 200 oder 204;
• ungültiges JSON, unbekannte Aktion oder ungültiger Tag;
• E-Mail größer als 5 MB.

• Streben Sie unter 500 ms an: Die Wartezeit geht von der Zustellung der E-Mail ab.
• Kein erneuter Versuch: Clean Mailbox ruft Ihre API einmal pro E-Mail auf. Dieselbe E-Mail kann Ihnen aber zweimal gesendet werden (erneuter Versuch nach einem vorübergehenden Fehler): Antworten Sie idempotent.
• Verlassen Sie sich nicht allein auf die API als Schutz: Ist sie nicht verfügbar, wird Ihre E-Mail nicht mehr von ihr gefiltert.

Beispielserver

Ein minimales PHP-Beispiel: Es prüft die Signatur und antwortet dann anhand eines Testschlüsselworts in der E-Mail. Ersetzen Sie die Testlogik durch Ihre eigenen Prüfungen.

<?php
const CMB_SECRET = 'SCHLUESSEL_HIER_EINFUEGEN';
$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);
// Signatur und Zeitstempel prüfen (höchstens 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' => 'Testschlüsselwort']);
} elseif (str_contains($body, '[TAG-ME]')) {
    echo json_encode(['action' => 'tag', 'tag' => '[API-Test]']);
} else {
    echo json_encode(['action' => 'none']);
}

Ihre Einrichtung testen

1. Stellen Sie dieses Skript auf einem HTTPS-Server (gültiges Zertifikat) bereit und tragen Sie den in der Oberfläche angezeigten Schlüssel ein.
2. Geben Sie seine URL auf der Seite Kunden-API Ihrer Domain an.
3. Senden Sie eine E-Mail an eine Adresse der Domain mit [TAG-ME] und eine weitere mit [BLOCK-ME] im Betreff.
4. Prüfen Sie, dass die erste mit dem Tag [API-Test] eintrifft und die zweite blockiert wird (Kopie in Quarantäne).

Passiert nichts, ist vermutlich eine der Regeln des Vertrags nicht erfüllt (Signatur, Zertifikat, Zeitlimit, HTTP-Code): Die E-Mail wird dann unverändert zugestellt.

Entscheidungen verfolgen

Von Ihrer API bearbeitete E-Mails lassen sich in der Oberfläche erkennen:

• in der Echtzeit-Ansicht wird eine Blockierung durch die API als „API“ (nicht als „Regeln“) angezeigt, und ein API-Filter zeigt nur diese E-Mails;
• blockierte E-Mails werden in Ihrer Quarantäne aufbewahrt, wo Sie sie prüfen und bei einem Fehlalarm wiederherstellen können;
• der von Ihnen zurückgesendete Grund (reason) wird bei jeder Blockierung angezeigt.

Häufige Fragen

Worin unterscheidet sie sich von den YARA-Regeln?

YARA-Regeln sind Muster, die Sie in der Oberfläche schreiben und die Clean Mailbox selbst auswertet, mit den Status inaktiv, Audit und aktiv. Die Kunden-API überlässt die Entscheidung Ihrem Server, sodass Sie Ihre eigenen Daten und Ihre eigene Logik nutzen können. Sie hat keinen „Audit“-Modus: Die von Ihnen zurückgegebene Aktion wird angewendet. Um sicher zu testen, antworten Sie mit none und protokollieren Sie auf Ihrer Seite.

Was passiert, wenn mein Server ausfällt?

Die E-Mail wird normal zugestellt, ohne Ihre Entscheidung zu durchlaufen. Sie wird weder zurückgehalten noch geht sie verloren.

Geht eine blockierte E-Mail verloren?

Nein. Sie wird in Ihrer Quarantäne aufbewahrt, wo Sie sie prüfen und bei einem Fehlalarm wiederherstellen können.

Kann ich die API für alle meine Domains auf einmal festlegen?

Die URL wird derzeit domainweise festgelegt. Eine gemeinsame URL für alle Domains eines Kontos wird für später in Betracht gezogen.