API klienta: o losie poczty decyduje Państwa własny serwer

Do czego służy

Filtry Clean Mailbox opierają się na naszych silnikach, a dzięki modułowi reguł Yara także na wzorcach napisanych przez Państwa. API klienta idzie dalej: decyzję podejmuje Państwa własny serwer. Dla każdej wiadomości odebranej przez domenę Clean Mailbox wysyła ją na hostowany przez Państwa adres HTTPS, a serwer odpowiada, co z nią zrobić.

To właściwa opcja, gdy decyzja zależy od danych, których Clean Mailbox nie ma: Państwa CRM (czy nadawca jest znanym klientem?), wewnętrznej listy dostawców, własnych silników analizy, złożonych reguł biznesowych itd.

• serwer wybiera akcję: nic nie robić, oznaczyć temat lub zablokować wiadomość;
• API jest wywoływane raz na wiadomość i domenę (wiadomość do trzech osób z tej samej domeny = jedno wywołanie);
• jest uruchamiane po antywirusie i antyspamie oraz przed regułami Yara: wiadomość usunięta już przez antywirus lub antyspam nie jest do niego wysyłana;
• nigdy nie może przez pomyłkę wstrzymać ani utracić wiadomości: jeśli coś pójdzie nie tak, wiadomość jest dostarczana normalnie.

Podanie adresu URL

W interfejsie Clean Mailbox należy otworzyć domenę, a następnie menu API klienta. Moduł jest dostępny tylko dla administratorów domeny i musi być włączony dla domeny: jeśli pozycja menu nie jest widoczna, prosimy o kontakt, aby ją aktywować.

1. Należy wpisać adres URL API, na przykład https://api.example.com/clean-mailbox, i zapisać.
2. Tajny klucz podpisu jest generowany automatycznie i wyświetlany na stronie (przyciski Pokaż, a następnie Kopiuj). Będzie potrzebny w kodzie do weryfikacji źródła żądań.
3. Aby usunąć opcję, należy wyczyścić pole i zapisać (lub użyć Usuń API): tajny klucz zostaje wtedy usunięty.

Adres URL musi spełniać następujące zasady:

• wyłącznie HTTPS, z ważnym certyfikatem wystawionym przez publiczny urząd dla nazwy hosta (bez certyfikatu z podpisem własnym), minimum TLS 1.2;
• pełna nazwa hosta: bez adresu IP, bez danych logowania w adresie URL, bez fragmentu (#), najwyżej 2048 znaków;
• nazwa hosta musi wskazywać adres publiczny: adres prywatny, lokalny lub zarezerwowany jest odrzucany;
• przekierowania nigdy nie są obsługiwane: adres URL musi odpowiadać bezpośrednio.

Żądanie wysyłane przez Clean Mailbox

Clean Mailbox wysyła żądanie HTTPS POST na Państwa adres URL. Treścią żądania jest surowa wiadomość w takiej postaci, w jakiej została odebrana (nagłówki, a następnie treść, z oryginalnymi kodowaniami: base64, quoted-printable itd.), do 5 MB. Powyżej tego rozmiaru wiadomość nie jest wysyłana do API, lecz dostarczana.

Weryfikacja podpisu

Każdy, kto zna Państwa adres URL, może wysłać na niego żądanie. Aby mieć pewność, że żądanie pochodzi od Clean Mailbox, serwer musi weryfikować podpis każdego wywołania:

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

gdzie timestamp to wartość X-CMB-Timestamp, a body to odebrana surowa wiadomość. Serwer musi:

1. ponownie obliczyć podpis i porównać go w stałym czasie (hash_equals w PHP, hmac.compare_digest w Pythonie);
2. odrzucić żądanie, którego znacznik czasu różni się od bieżącego o więcej niż kilka minut (ochrona przed odtwarzaniem);
3. w obu przypadkach odpowiedzieć 401: Clean Mailbox dostarcza wtedy wiadomość, nic Państwo nie tracą.

Akcje: nic, oznaczenie, blokada

Serwer ma najwyżej 2 sekundy na odpowiedź. Akcja jest wybierana w odpowiedzi, w formacie JSON o rozmiarze do 4 KB:

{ "action": "none | tag | block", "tag": "[Suspect]", "reason": "krótki tekst, opcjonalnie" }

• action jest wymagane, małymi literami (none, tag lub block);
• tag jest wymagane przy akcji tag: najwyżej 100 znaków, bez łamania wiersza i znaków sterujących (jest wpisywane do tematu). Dodaje się do oznaczeń reguł Yara i antyspamu, przy czym oznaczenie z API znajduje się na początku;
• reason jest opcjonalne, najwyżej 200 znaków: przy blokadzie jest wyświetlane w interfejsie („API klienta: …”). Nie należy w nim umieszczać danych osobowych;
• nieznane klucze są ignorowane, dzięki czemu format może ewoluować bez psucia Państwa kodu;
• uwzględniane są tylko kody 200 i 204: kod 4xx lub 5xx nigdy nie jest interpretowany jako decyzja.

Gwarancje i limity czasu

API nigdy nie może przez pomyłkę spowodować utraty ani wstrzymania wiadomości. Blokuje wyłącznie prawidłowa odpowiedź „block”; w każdym innym przypadku wiadomość jest dostarczana normalnie:

• przekroczenie limitu 2 sekund (łącznie z rozwiązywaniem DNS, połączeniem, TLS, wysłaniem i odpowiedzią);
• błąd sieci, nieprawidłowy certyfikat, serwer niedostępny;
• kod HTTP inny niż 200 lub 204;
• nieprawidłowy JSON, nieznana akcja lub nieprawidłowe oznaczenie;
• wiadomość większa niż 5 MB.

• Celem powinno być poniżej 500 ms: czas oczekiwania opóźnia dostarczenie wiadomości.
• Bez ponowień: Clean Mailbox wywołuje Państwa API raz na wiadomość. Ta sama wiadomość może jednak zostać przysłana dwukrotnie (ponowienie po błędzie przejściowym): należy odpowiadać idempotentnie.
• Nie należy polegać na API jako jedynej ochronie: jeśli jest niedostępne, wiadomości nie są przez nie filtrowane.

Przykładowy serwer

Minimalny przykład w PHP: weryfikuje podpis, a następnie odpowiada na podstawie testowego słowa kluczowego w wiadomości. Logikę testową należy zastąpić własnymi kontrolami.

<?php
const CMB_SECRET = 'WKLEJ_TUTAJ_TAJNY_KLUCZ';

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

// Sprawdź podpis i znacznik czasu (najwyżej 5 minut)
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' => 'testowe słowo kluczowe']);
} elseif (str_contains($body, '[TAG-ME]')) {
    echo json_encode(['action' => 'tag', 'tag' => '[API test]']);
} else {
    echo json_encode(['action' => 'none']);
}

Test konfiguracji

1. Należy wdrożyć ten skrypt na serwerze HTTPS (z ważnym certyfikatem) i ustawić tajny klucz wyświetlany w interfejsie.
2. Podać jego adres URL na stronie API klienta domeny.
3. Wysłać wiadomość na adres w domenie z [TAG-ME] w temacie, a następnie drugą z [BLOCK-ME].
4. Sprawdzić, czy pierwsza dociera z oznaczeniem [API test], a druga jest blokowana (kopia w kwarantannie).

Jeśli nic się nie dzieje, prawdopodobnie nie jest spełniona któraś z zasad kontraktu (podpis, certyfikat, limit czasu, kod HTTP): wiadomość jest wtedy dostarczana bez zmian.

Śledzenie decyzji

Wiadomości obsłużone przez Państwa API można rozpoznać w interfejsie:

• w widoku czasu rzeczywistego blokada przez API jest oznaczona jako „API” (a nie „Reguły”), a filtr API pozwala wyświetlić tylko takie wiadomości;
• zablokowane wiadomości są przechowywane w Państwa kwarantannie, gdzie można je przejrzeć i w razie fałszywego wykrycia przywrócić;
• przesłany przez Państwa powód (reason) jest wyświetlany przy każdej blokadzie.

Najczęstsze pytania

Czym różnią się od reguł Yara?

Reguły Yara to wzorce pisane w interfejsie, które Clean Mailbox ocenia samodzielnie, ze statusami nieaktywna, audyt i aktywna. API klienta przekazuje decyzję Państwa serwerowi, dzięki czemu można korzystać z własnych danych i logiki. Nie ma trybu „audytu”: zwrócona akcja jest wykonywana. Aby bezpiecznie testować, należy odpowiadać none i logować po swojej stronie.

Co się stanie, jeśli mój serwer nie działa?

Wiadomość jest dostarczana normalnie, z pominięciem Państwa decyzji. Nie jest wstrzymywana ani tracona.

Czy zablokowana wiadomość przepada?

Nie. Jest przechowywana w Państwa kwarantannie, gdzie można ją przejrzeć i w razie fałszywego wykrycia przywrócić.

Czy mogę ustawić API dla wszystkich domen naraz?

Adres URL jest obecnie ustawiany osobno dla każdej domeny. Wspólny adres dla wszystkich domen konta jest rozważany na przyszłość.