Soppressioni

Il tuo spazio di lavoro possiede una lista di soppressione: un insieme di indirizzi email a cui non consegniamo. Hard bounce e segnalazioni di spam vi finiscono automaticamente, e puoi aggiungere indirizzi anche manualmente. Inviare ripetutamente a indirizzi che rimbalzano o segnalano spam può far bloccare il tuo dominio dai provider di posta, quindi blocchiamo quegli invii prima che lascino la piattaforma.

Una disiscrizione non è in questa lista. Registra la preferenza espressa dal destinatario anziché un dato di recapitabilità, quindi si trova nella scheda Preferences . Consulta Link di disiscrizione per il funzionamento.

Gestisci la lista in Email > Suppressions, tramite le soppressioni API o con bird email suppressions.

La pagina Suppressions nella dashboard, con l'elenco degli indirizzi soppressi, il motivo, l'origine, la data di creazione e un pulsante Create suppression

I tre motivi e cosa bloccano

Ogni record ha un reason che indica perché l'indirizzo è in lista e una policy applies_to che controlla quali categorie blocca:

Motivo	applies_to	Categoria marketing	Categoria transazionale
hard_bounce	all	Bloccata	Bloccata
complaint	non_transactional	Bloccata	Consentita
manual	all	Bloccata	Bloccata

La suddivisione deriva dal significato di ciascun motivo:

hard_bounce: l'indirizzo non esiste. Inviare è inutile in qualsiasi categoria, quindi blocca tutto.
complaint: una dichiarazione di posta indesiderata. Chi ha segnalato la tua newsletter come spam potrebbe comunque aver bisogno di un reset della password o di una conferma d'ordine, quindi blocca solo gli invii non transazionali.
manual: una decisione deliberata tua o del tuo team. Non la mettiamo in discussione, quindi una soppressione manuale blocca ogni categoria, inclusa quella transazionale.

Un indirizzo può avere un record per ogni motivo, quindi un hard bounce e una precedente segnalazione di spam coesistono come record separati, e la consegna resta bloccata finché rimane almeno un record bloccante. In caso di dubbio blocchiamo tutto: se un record presenta un applies_to che la tua integrazione non ha mai visto, trattalo come bloccante per ogni categoria, esattamente come facciamo noi.

Note: reason: unsubscribe is deprecated on the suppressions API. Unsubscribes now record a preference instead of a suppression, so ?reason=unsubscribe matches nothing.

Come vengono aggiunti automaticamente gli indirizzi

Aggiungiamo le soppressioni in risposta ai segnali dei destinatari, quindi un bounce o una segnalazione non richiedono alcun intervento da parte tua:

Evento scatenante	Soppressione risultante
Hard bounce (email.bounced)	reason: hard_bounce, origin: bounce_event, applies_to: all
Hard bounce fuori banda (email.out_of_band_bounce)	reason: hard_bounce, origin: bounce_event, applies_to: all
Segnalazione di spam (email.complained)	reason: complaint, origin: complaint_event, applies_to: non_transactional

Una disiscrizione, sia tramite il link nel corpo del messaggio sia tramite il pulsante one-click, non compare qui: registra una preferenza nella scheda Preferences anziché aggiungere una riga a questa lista.

Solo un bounce di classe hard genera una soppressione, e la tabella di classificazione mostra quali valori bounce_class sono considerati hard. Due esiti che sembrano errori lasciano l'indirizzo inviabile:

Soft bounce e rinvii (email.deferred, oppure email.bounced con bounce_type: "soft"): errori temporanei come una casella piena. Riproviamo.
Rifiuti lato invio: errori di generazione e rifiuti di policy sono problemi dell'invio, non dell'indirizzo. Producono eventi email.rejected e nessuna soppressione.

Segnali ripetuti per un indirizzo già soppresso per lo stesso motivo non modificano il record originale, incluso il suo created_at. Il record conserva source_email_id e source_recipient_id, che collegano una soppressione automatica al messaggio e al destinatario esatti che l'hanno causata. Questi due campi rispondono alla domanda di supporto "why did this person stop getting our email" e sono null nelle aggiunte manuali.

Ogni aggiunta, automatica o manuale, emette un evento email_suppression.created verso il tuo endpoint webhook con il suppression_id, l'indirizzo soppresso email, il reason e il workspace_id, così il tuo sistema può replicare la lista senza polling:

Esempio di codice

{
  "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"
  }
}

Gestire le soppressioni tramite API

API aggiunge, elenca, cerca ed elimina singoli record. Gli indirizzi vengono convertiti in minuscolo prima dell'archiviazione e della ricerca, e non compaiono mai in un percorso URL, perché un percorso finisce nei log di accesso e un indirizzo email è un dato personale. Per trovare il record di un indirizzo, filtra la lista con ?email=.

Gli esempi SDK accedono alle soppressioni tramite il metodo raw-request di ciascun client, che gestisce autenticazione, tentativi e base URL come una chiamata tipizzata. La forma della risposta è quella che dichiari tu.

Aggiungere un indirizzo

type Suppression = { id: string; email: string; reason: string };

const suppression = await bird.request<Suppression>({
  method: "POST",
  path: "/v1/email/suppressions",
  body: { email: "user@example.com" },
});

client.post("/v1/email/suppressions", body={"email": "user@example.com"})

var suppression struct {
	Id     string `json:"id"`
	Email  string `json:"email"`
	Reason string `json:"reason"`
}
if err := client.Post(context.Background(), "/v1/email/suppressions", map[string]any{
	"email": "user@example.com",
}, &suppression); err != nil {
	log.Fatal(err)
}

$suppression = $bird->post('/v1/email/suppressions', body: [
    'email' => 'user@example.com',
]);

curl -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" }'

Su CLI, bird email suppressions copre list e remove; l'aggiunta di un indirizzo passa attraverso API.

Le aggiunte manuali ricevono reason: manual e applies_to: all, quindi bloccano ogni categoria. La chiamata è idempotente: una nuova soppressione restituisce 201 Created, e un indirizzo già soppresso manualmente restituisce 200 OK con il record esistente anziché un conflitto. In entrambi i casi il body è l'oggetto soppressione:

Esempio di codice

{
  "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"
  }
}

Il campo origin registra come il record è stato creato. Le aggiunte manuali ricevono api_key o user, a seconda che il chiamante si sia autenticato con una chiave API o una sessione dashboard. Le aggiunte automatiche ricevono bounce_event o complaint_event, a seconda del segnale che le ha generate.

Elencare e cercare

type Suppressions = { data: Array<{ id: string; email: string; reason: string }> };

const suppressions = await bird.request<Suppressions>({
  method: "GET",
  path: "/v1/email/suppressions?limit=25",
});
console.log(suppressions.data.length);

suppressions = client.get("/v1/email/suppressions?limit=25")
print(len(suppressions["data"]))

var out struct {
	Data []struct {
		Email  string `json:"email"`
		Reason string `json:"reason"`
	} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/email/suppressions?limit=25", &out); err != nil {
	log.Fatal(err)
}
fmt.Println(len(out.Data))

$suppressions = $bird->get('/v1/email/suppressions', query: ['limit' => 25]);

bird email suppressions list --limit 25

curl "https://us1.platform.bird.com/v1/email/suppressions?limit=25" \
  -H "Authorization: Bearer $BIRD_API_KEY"

La lista è paginata tramite cursore, dal più recente, e filtrabile per reason. Per controllare un singolo indirizzo, passalo come parametro query email:

const suppressions = await bird.request({
  method: "GET",
  path: "/v1/email/suppressions?email=user@example.com",
});
console.log(suppressions.data.length);

suppressions = client.get("/v1/email/suppressions?email=user@example.com")
print(len(suppressions["data"]))

var out struct {
	Data []struct {
		Email  string `json:"email"`
		Reason string `json:"reason"`
	} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/email/suppressions?email=user@example.com", &out); err != nil {
	log.Fatal(err)
}
fmt.Println(len(out.Data))

$suppressions = $bird->get('/v1/email/suppressions', query: ['email' => 'user@example.com']);

bird email suppressions list --email user@example.com

curl "https://us1.platform.bird.com/v1/email/suppressions?email=user@example.com" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Un array data vuoto significa che l'indirizzo non è soppresso; più record vengono restituiti quando si applica più di un motivo. Il filtro email cerca per prefisso senza distinzione tra maiuscole e minuscole, quindi un indirizzo completo restituisce i record di quell'indirizzo e un frammento come alice restituisce ogni indirizzo soppresso che inizia con esso.

Rimuovere un indirizzo

await bird.request({
  method: "DELETE",
  path: "/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc",
});

client.delete("/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc")

if err := client.Delete(context.Background(), "/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc", nil); err != nil {
	log.Fatal(err)
}

$bird->delete('/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc');

bird email suppressions remove sup_01ky7qckqrf06r38g49b9kxdbc --yes

curl -X DELETE https://us1.platform.bird.com/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc \
  -H "Authorization: Bearer $BIRD_API_KEY"

Restituisce 204 No Content. L'eliminazione è permanente: non conserviamo nulla e l'indirizzo torna inviabile. Eliminare per indirizzo richiede due chiamate, una ricerca ?email= per ottenere l'ID e poi l'eliminazione, e un indirizzo soppresso per più motivi richiede l'eliminazione di ogni record bloccante. Presta attenzione nel rimuovere un record hard_bounce, perché un indirizzo che ancora non esiste rimbalza al prossimo invio e si sopprime di nuovo.

Cosa succede quando invii a un indirizzo soppresso

Rifiutiamo il destinatario in modo che tu possa vederlo. Il destinatario riceve un recipient_id e compare nella lista dei destinatari del messaggio con stato rejected. Gli eventi API e i tuoi webhook registrano un evento email.rejected con rejection_reason: "recipient_suppressed". Il resto dei destinatari viene consegnato normalmente.

Il messaggio stesso viene comunque accettato con un 202, anche quando tutti i suoi destinatari sono soppressi. Risolviamo la soppressione dopo aver accettato l'invio, durante l'elaborazione del messaggio, quindi un indirizzo aggiunto ora si applica entro pochi minuti e non blocca mai un invio già in corso.

Test con il sandbox

Il sandbox di test esercita la gestione delle soppressioni in modo deterministico. Inviare a suppressed@messagebird.dev si comporta come se l'indirizzo fosse nella tua lista: il destinatario viene rifiutato con rejection_reason: "recipient_suppressed" e non raggiunge mai la consegna. Gli indirizzi sandbox per bounce e segnalazioni (bounce@messagebird.dev, complaint@messagebird.dev) eseguono i loro esiti attraverso la pipeline di eventi reale senza scrivere nulla nella tua lista di soppressione, così gli stessi indirizzi di test restano riutilizzabili tra un'esecuzione e l'altra.

Prossimi passi

Categorie: transactional rispetto a marketing, e come la categoria interagisce con la policy di soppressione
Link di disiscrizione: come le rinunce registrano una preferenza espressa anziché una soppressione
Eventi e webhook: il payload email.rejected e gli eventi del ciclo di vita che guidano la soppressione automatica
Sandbox di test: indirizzi speciali per simulare ogni esito di consegna
Riferimento API: Suppressions: schemi completi di richiesta e risposta
Cosa succede quando qualcuno annulla l'iscrizione: un video che segue un destinatario dalla pagina di disiscrizione fino a un invio rifiutato

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoWhat is one-click unsubscribe, and how do I implement List-Unsubscribe?Esplora la funzionalitàEmail opt-outs Segui il percorso di apprendimentoOperate messaging reliably

Ottieni un brief di implementazione