Suppresje
Twój obszar roboczy posiada listę suppresji: zbiór adresów e-mail, na które nie dostarczamy wiadomości. Twarde odbicia i zgłoszenia spamu trafiają na nią automatycznie, a Ty możesz dodawać adresy ręcznie. Wielokrotne wysyłanie wiadomości na adresy, które odbijają się lub zgłaszają spam, może spowodować zablokowanie Twojej domeny przez dostawców skrzynek pocztowych, dlatego zatrzymujemy takie wysyłki, zanim opuszczą platformę.
Nowa rezygnacja z subskrypcji nie dodaje rekordu blokady. Zapisuje ona deklarowaną preferencję odbiorcy, a nie fakt dotyczący dostarczalności, dlatego trafia na zakładkę Preferences zamiast na tę listę. Zobacz Linki rezygnacji z subskrypcji, aby dowiedzieć się, jak to działa.
Zarządzaj listą w Email > Suppressions, przez suppresje API lub za pomocą bird email suppressions.
Trzy powody i co blokują
Każdy rekord ma reason wskazujący, dlaczego adres jest na liście, oraz politykę applies_to kontrolującą, które kategorie blokuje:
| Powód | applies_to | Kategoria marketingowa | Kategoria transakcyjna |
|---|---|---|---|
| hard_bounce | all | Zablokowana | Zablokowana |
| complaint | non_transactional | Zablokowana | Dozwolona |
| manual | all | Zablokowana | Zablokowana |
Podział wynika z tego, co oznacza każdy powód:
- hard_bounce: adres nie istnieje. Wysyłanie jest bezcelowe w każdej kategorii, więc blokuje wszystko.
- complaint: oświadczenie o niechcianej poczcie. Ktoś, kto zgłosił Twój newsletter jako spam, może nadal potrzebować resetowania hasła lub potwierdzenia zamówienia, więc blokuje tylko wysyłki inne niż transakcyjne.
- manual: świadoma decyzja Twoja lub Twojego zespołu. Nie podważamy jej, więc ręczna suppresja blokuje każdą kategorię, łącznie z transakcyjną.
Adres może mieć po jednym rekordzie na każdy powód, więc twarde odbicie i wcześniejsze zgłoszenie spamu istnieją obok siebie jako osobne rekordy, a dostarczanie pozostaje zablokowane, dopóki istnieje jakikolwiek blokujący rekord. Stosujemy zasadę domyślnego blokowania: jeśli rekord zwróci applies_to, którego Twoja integracja nigdy nie widziała, traktuj go jako blokujący każdą kategorię, bo tak samo robimy to my.
Note: reason: unsubscribe is deprecated on the suppressions API. New unsubscribes record a preference instead of a suppression. The deprecated ?reason=unsubscribe filter still returns legacy suppression records with origin: unsubscribe_link or origin: unsubscribe_event until those records are removed.
Jak adresy są dodawane automatycznie
Dodajemy suppresje w odpowiedzi na sygnały od odbiorców, więc odbicie lub zgłoszenie spamu nie wymaga od Ciebie żadnego działania:
| Wyzwalacz | Wynikowa suppresja |
|---|---|
| Twarde odbicie (email.bounced) | reason: hard_bounce, origin: bounce_event, applies_to: all |
| Pozapasmowe twarde odbicie (email.out_of_band_bounce) | reason: hard_bounce, origin: bounce_event, applies_to: all |
| Zgłoszenie spamu (email.complained) | reason: complaint, origin: complaint_event, applies_to: non_transactional |
Wypisanie się, zarówno przez link w treści, jak i przycisk jednym kliknięciem, nie pojawia się tutaj: rejestruje preferencję na karcie Preferences zamiast dodawać wiersz do tej listy.
Tylko odbicie klasy hard powoduje suppresję, a tabela klasyfikacji pokazuje, które wartości bounce_class są uznawane za twarde. Dwa wyniki, które wyglądają jak błędy, pozostawiają adres zdatny do wysyłki:
- Miękkie odbicia i odroczenia (email.deferred lub email.bounced z bounce_type: "soft"): przejściowe błędy, np. pełna skrzynka. Ponawiamy próbę.
- Odrzucenia po stronie nadawcy: błędy generowania i odrzucenia wynikające z polityki to problemy z wysyłką, nie z adresem. Generują zdarzenia email.rejected i nie powodują suppresji.
Powtórne sygnały dla adresu, który jest już zablokowany z tego samego powodu, nie zmieniają oryginalnego rekordu, łącznie z jego created_at. Rekord zachowuje source_email_id i source_recipient_id, które wiążą automatyczną suppresję z dokładną wiadomością i odbiorcą, które ją spowodowały. Te dwa pola odpowiadają na pytanie do supportu "why did this person stop getting our email" i mają wartość null w ręcznych dodaniach.
Każde dodanie, automatyczne lub ręczne, wywołuje zdarzenie email_suppression.created na Twoim endpoincie webhooka z suppression_id, zablokowanym email, reason i workspace_id, dzięki czemu Twój system może odzwierciedlać listę bez odpytywania:
Przykład kodu
{
"type": "email_suppression.created",
"timestamp": "2026-07-23T14:52:03.192524705Z",
"data": {
"email": "user@example.com",
"reason": "manual",
"suppression_id": "sup_01ky7qckqrf06r38g49b9kxdbc",
"workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf"
}
}Zarządzanie suppresjami przez API
API dodaje, listuje, wyszukuje i usuwa pojedyncze rekordy. Adresy są zamieniane na małe litery przed zapisem i wyszukiwaniem i nigdy nie pojawiają się w ścieżce URL, ponieważ ścieżka trafia do logów dostępu, a adres e-mail jest daną osobową. Aby znaleźć rekord dla adresu, przefiltruj listę za pomocą ?email=.
Każdy SDK udostępnia te operacje jako typowane metody na zasobie suppressions.
Dodaj adres
const suppression = await bird.suppressions.add({ email: "user@example.com" });
console.log(suppression.id);suppression = client.suppressions.add(email="user@example.com")
print(suppression.id)suppression, err := client.Suppressions.Add(context.Background(), bird.SuppressionsAddParams{
Email: "user@example.com",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(suppression.Id)$suppression = $bird->suppressions->add(
(new SuppressionCreate())->setEmail('user@example.com'),
);
echo $suppression->getId();bird email suppressions add --email user@example.comcurl -X POST https://us1.platform.bird.com/v1/email/suppressions \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "user@example.com" }'Ręczne dodania otrzymują reason: manual i applies_to: all, więc blokują każdą kategorię. Wywołanie jest idempotentne: nowa suppresja zwraca 201 Created, a adres już ręcznie zablokowany zwraca 200 OK z istniejącym rekordem zamiast konfliktu. W obu przypadkach treść odpowiedzi to obiekt suppresji:
Przykład kodu
{
"applies_to": "all",
"created_at": "2026-07-23T14:52:03.192524705Z",
"email": "user@example.com",
"id": "sup_01ky7qckqrf06r38g49b9kxdbc",
"origin": "api_key",
"reason": "manual",
"scope": {
"id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
"type": "workspace"
}
}Pole origin rejestruje sposób powstania rekordu. Ręczne dodania otrzymują api_key lub user, w zależności od tego, czy wywołujący uwierzytelnił się kluczem API, czy sesją dashboardu. Automatyczne dodania otrzymują bounce_event lub complaint_event, w zależności od tego, jaki sygnał je utworzył.
Listowanie i wyszukiwanie
Te wywołania zwracają pierwszą stronę. W Go pusty trzeci argument rozpoczyna paginację; przekaż NextCursor z poprzedniej strony, aby pobrać następną.
const page = await bird.suppressions.list({ limit: 25 });
console.log(page.data.length);page = client.suppressions.list(limit=25)
print(len(page.data))page, err := client.Suppressions.ListPage(context.Background(), bird.SuppressionsListParams{Limit: 25}, "")
if err != nil {
log.Fatal(err)
}
fmt.Println(len(page.Data))$page = $bird->suppressions->list(['limit' => 25])->fetch();
echo count($page->data);bird email suppressions list --limit 25curl "https://us1.platform.bird.com/v1/email/suppressions?limit=25" \
-H "Authorization: Bearer $BIRD_API_KEY"Lista jest paginowana kursorem, od najnowszych, z możliwością filtrowania po reason. Aby sprawdzić jeden adres, przekaż go jako parametr zapytania email:
const page = await bird.suppressions.list({ email: "user@example.com" });
console.log(page.data.length);page = client.suppressions.list(email="user@example.com")
print(len(page.data))page, err := client.Suppressions.ListPage(context.Background(), bird.SuppressionsListParams{
Email: "user@example.com",
}, "")
if err != nil {
log.Fatal(err)
}
fmt.Println(len(page.Data))$page = $bird->suppressions->list(['email' => 'user@example.com'])->fetch();
echo count($page->data);bird email suppressions list --email user@example.comcurl "https://us1.platform.bird.com/v1/email/suppressions?email=user@example.com" \
-H "Authorization: Bearer $BIRD_API_KEY"Filtr email dopasowuje bez rozróżniania wielkości liter po prefiksie: user@example.com pasuje również do user@example.com.au. Porównaj każdy zwrócony adres z pełnym adresem, którego szukasz, i przejdź next_cursor przez każdą stronę, zanim zdecydujesz, czy pasujący rekord istnieje. Jeden adres może mieć kilka rekordów. Wywołujący MCP mogą użyć email_suppressions_check do wyszukiwania dokładnego adresu.
Gdy masz ID blokady, GET /v1/email/suppressions/{suppression_id} zwraca ten jeden rekord: suppressions.get w SDK lub bird email suppressions get <id> w CLI.
Usuń adres
await bird.suppressions.remove("sup_01ky7qckqrf06r38g49b9kxdbc");client.suppressions.remove("sup_01ky7qckqrf06r38g49b9kxdbc")if err := client.Suppressions.Remove(context.Background(), "sup_01ky7qckqrf06r38g49b9kxdbc"); err != nil {
log.Fatal(err)
}$bird->suppressions->remove('sup_01ky7qckqrf06r38g49b9kxdbc');bird email suppressions remove sup_01ky7qckqrf06r38g49b9kxdbc --yescurl -X DELETE https://us1.platform.bird.com/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc \
-H "Authorization: Bearer $BIRD_API_KEY"Jednego powodu nie da się usunąć w ten sposób. Rekord complaint można usunąć tylko jako zalogowany użytkownik dashboardu; klucz API otrzyma 422 SuppressionNotRemovableByAPIKey. Rekordy hard_bounce i manual można usunąć w obu przypadkach.
Zwraca 204 No Content i trwale usuwa dany rekord. Pozostałe rekordy dla tego samego adresu nie są zmieniane, a dostarczanie pozostaje zablokowane, dopóki jakikolwiek pozostały rekord blokuje kategorię wiadomości. Aby usunąć rekordy według adresu, paginuj wyszukiwanie ?email=, wybierz tylko dokładne dopasowania adresu i usuń każdy wybrany rekord po ID. Ostrożnie usuwaj rekord hard_bounce, ponieważ adres, który nadal nie istnieje, odbije się przy następnej wysyłce i ponownie się zablokuje.
Co się dzieje, gdy wysyłasz na zablokowany adres
Odrzucamy odbiorcę w widoczny dla Ciebie sposób. Odbiorca otrzymuje recipient_id i pojawia się na liście odbiorców wiadomości ze statusem rejected. Zdarzenia API i Twoje webhooki rejestrują zdarzenie email.rejected z rejection_reason: "recipient_suppressed". Pozostali odbiorcy są dostarczani normalnie.
Sama wiadomość jest nadal akceptowana z 202, nawet gdy wszyscy jej odbiorcy są zablokowani. Blokadę rozstrzygamy po przyjęciu wysyłki, podczas przetwarzania wiadomości, więc adres dodany teraz zacznie obowiązywać w ciągu kilku minut i nigdy nie zatrzyma wysyłki będącej już w toku.
Testowanie z sandboxem
Sandbox testowy obsługuje blokady w sposób deterministyczny. Wysyłka na suppressed@messagebird.dev zachowuje się tak, jakby adres znajdował się na Twojej liście: odbiorca jest odrzucany z rejection_reason: "recipient_suppressed" i nigdy nie trafia do dostarczenia. Adresy sandbox dla odrzuceń i skarg (bounce@messagebird.dev, complaint@messagebird.dev) przepuszczają wyniki przez prawdziwy pipeline zdarzeń, ale nie zapisują niczego na Twojej liście blokad, dzięki czemu te same adresy testowe można wielokrotnie wykorzystywać.
Następne kroki
- Kategorie: transactional kontra marketing i jak kategoria współdziała z polityką blokad
- Linki rezygnacji z subskrypcji: jak rezygnacje zapisują deklarowaną preferencję zamiast blokady
- Zdarzenia i webhooki: payload email.rejected i zdarzenia cyklu życia napędzające automatyczne blokady
- Sandbox testowy: magiczne adresy do symulowania każdego wyniku dostarczenia
- Dokumentacja API: Suppressions: pełne schematy żądań i odpowiedzi
- Co dzieje się, gdy ktoś zrezygnuje z subskrypcji: film, który śledzi jednego odbiorcę od strony rezygnacji do odrzuconej wysyłki
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.
Zrozum koncepcjęWhat is one-click unsubscribe, and how do I implement List-Unsubscribe?Poznaj możliwościEmail opt-outsPodążaj ścieżką naukiOperate messaging reliably
Uzyskaj brief wdrożeniowy