API opt-out dla nadawców

API ma dwa punkty końcowe. /v1/suppression/check odpowiada dla jednego odbiorcy naraz i jest używane w czasie rzeczywistym — na przykład w kolejce wybierania numerów albo tuż przed wysyłką. /v1/suppression/batch przyjmuje listę i jest używane, gdy przygotowywana jest kampania.

Oba przyjmują zahaszowane identyfikatory. Żaden punkt końcowy nie zwraca danych osobowych i żaden nie potwierdza, że dana osoba istnieje w naszym systemie — tylko tyle, że nie powinno się kontaktować z tym hashem.

Odpowiedź z suppressed: false oznacza, że nie wiemy o żadnym opt-out. To nie jest zgoda i nie zastępuje Twojej własnej oceny zgodności z prawem.

Każde wywołanie przenosi klucz w nagłówku Authorization. Klucze są przypisane do środowiska: mm_test_ dla środowiska testowego, mm_live_ dla produkcyjnego. Klucz użyty w niewłaściwym środowisku jest odrzucany kodem 401, zamiast po cichu przełączać się na inne.

Authorization: Bearer mm_live_…Content-Type: application/jsonIdempotency-Key: <uuid v4>   # zalecane dla każdego wywołania zapisującego

Hash jest obliczany po Twojej stronie, z pieprzem (pepper) unikalnym dla Twojej organizacji. To daje dwie rzeczy: nie możemy odtworzyć danych kontaktowych, a wyciek Twoich hashy nie da się zestawić z hashami nikogo innego.

# 1. Znormalizuj do E.164, zanim zrobisz cokolwiek innego  070-123 45 67        ->  +46701234567  Name@Example.COM     ->  name@example.com # 2. Zahaszuj z przypisanym Ci pieprzem (nigdy po stronie klienta)  sha256(pepper + normalized) # 3. Wyślij hash, nigdy wartość  "identifier_hash": "sha256:9f1a3c…c07d"

Normalizacja musi nastąpić przed haszowaniem. 070-123 45 67 i +46 70 123 45 67 to ten sam abonent, ale różne ciągi znaków — bez normalizacji zostaną zahaszowane inaczej, a sprawdzenie nie wykryje opt-out.

Używane dla pojedynczego odbiorcy, w czasie rzeczywistym. Czas odpowiedzi jest zaprojektowany tak, by zmieścić się w przebiegu połączenia, więc sprawdzenie może znajdować się tuż przed wybraniem numeru.

POST /v1/suppression/check HTTP/1.1Host: api.marketmute.comAuthorization: Bearer mm_live_…Content-Type: application/jsonIdempotency-Key: 8c1f0b52-3a77-4a1e-9f0c-2b7d4e11ab90 {  "channel": "phone",                         "identifier_hash": "sha256:9f1a3c…c07d",  "purpose": "direct_marketing",  "sender_ref": "campaign-2026-h2"}

HTTP/1.1 200 OKContent-Type: application/jsonRateLimit-Remaining: 986 {  "suppressed": true,  "channel": "phone",  "scope": "sender",  "effective_from": "2026-03-04T09:12:00Z",  "receipt_id": "rcpt_01HZK4Q2M8V3XT",  "checked_at": "2026-08-19T07:41:02Z"}

Przechowuj receipt_id razem z rejestrem swoich wysyłek. To jedyne odniesienie, które łączy Twoje sprawdzenie z naszą odpowiedzią, gdyby wynik został kiedyś zakwestionowany.

Wyślij do 10 000 hashy na jedno wywołanie. Lista wyników zawsze ma tę samą kolejność i tę samą długość co identifier_hashes, więc możesz indeksować bezpośrednio, bez dopasowywania po wartościach.

POST /v1/suppression/batch HTTP/1.1Authorization: Bearer mm_live_…Content-Type: application/json {  "channel": "phone",  "purpose": "direct_marketing",  "identifier_hashes": [    "sha256:9f1a3c…c07d",    "sha256:41b8ee…9a20"  ]} # Odpowiedź: ta sama kolejność co żądanie, nigdy nie zmieniana{  "results": [    { "suppressed": true,  "scope": "sender" },    { "suppressed": false, "scope": null }  ],  "receipt_id": "rcpt_01HZK4Q2M8V44P"}

Większe listy dzielisz Ty, nie my. Wywołanie przekraczające limit jest odrzucane kodem 400, a nie po cichu obcinane.

Wszystkie błędy są zwracane jako JSON z polami error i message. Kod statusu jest rozstrzygający — odczytaj go przed treścią.

• 200OK — Sprawdzenie zostało zakończone. Wynik odczytaj z pola suppressed.
• 202Accepted — Paczka została przyjęta, ale jest przetwarzana asynchronicznie. Wynik pobierz za pomocą receipt_id.
• 400Bad Request — Nie udało się przetworzyć treści albo identifier_hash nie ma prefiksu sha256:.
• 401Unauthorized — Klucz jest nieobecny, został unieważniony albo należy do innego środowiska.
• 409Conflict — Idempotency-Key został użyty ponownie z inną treścią.
• 422Unprocessable — Kanał albo cel nie są obsługiwane. Zobacz dopuszczalne wartości channel i purpose powyżej.
• 429Too Many Requests — Limit został wyczerpany. Odczekaj liczbę sekund podaną w Retry-After.
• 503Service Unavailable — Planowana konserwacja albo przeciążenie. Ponów próbę z rosnącym opóźnieniem (exponential backoff).

Limit żądań

1000 wywołań na minutę na klucz. Pozostały limit znajduje się w RateLimit-Remaining.

Limit paczki

10 000 hashy na wywołanie. Nadmiar jest odrzucany, nigdy nie obcinany.

Ponawianie

Rosnące opóźnienie zaczynające się od 1 s. Wyślij ten sam Idempotency-Key, a próba zostanie policzona tylko raz.

Przechowywanie danych

Przechowujemy potwierdzenie i hash, o który zapytałeś — nigdy nic, co dałoby się powiązać z konkretną osobą.